Выплаты

Выплаты с корпоративной карты мерчанта на карту клиента (OCT) - удобное и безопасное решение для онлайн-переводов средств со счета компании на карты физических лиц. Для осуществления выплаты необходимо знать PAN карты получателя.

Подготовка к интеграции

Прежде чем приступить к интеграции сервиса выплат, вам необходимо оставить заявку на подключение и связаться с менеджером ioka для обсуждения условий подключения данного сервиса для вашего магазина.

Проведение выплаты включает следующие шаги:

1. Создание заказа для осуществления выплаты
2. Перенаправление клиента на форму ввода PAN для получения выплаты
3. Получение уведомления о статусе выплаты

Также, вы можете производить выплату на раннее сохраненную карту получателя. Для этого необходимо выполнить следующие шаги:

1. Сохранение данных получателя
2. Создание заказа для осуществления выплаты
3. Отправка запроса для инициации выплаты по receiver_id (id карты получателя в системе ioka)
4. Получение уведомления о статусе выплаты q

Создание заказа для осуществления выплаты

Обязательные параметры для создания заказа:

• amount - сумму необходимо указывать в минорных денежных единицах, т.е. для создания заказа на сумму 500 тенге, необходимо ввести 50000 (1 тенге = 100 тиын)
• type - тип выплаты, для создания заказа с возможностью осуществления выплаты необходимо передать в это поле значение PAYOUT

Дополнительные параметры для создания заказа:

• external_id - внешний идентификатор заказа в системе мерчанта
• description - описание заказа
• extra_info - дополнительные данные, связанные с заказом, передаются в виде словаря
• due_date - дата и время окончания действия заказа, после которого по нему нельзя будет произвести выплату
• back_url - ссылка, служащая для перенаправления клиента на сайт мерчанта после проведения выплаты
• success_url - ссылка, служащая для перенаправления клиента на сайт мерчанта после успешного проведения выплаты
• failure_url - ссылка, служащая для перенаправления клиента на сайт мерчанта после неуспешного проведения выплаты

Пример запроса:

HTTP

POST /v2/transfer-orders HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..
Content-Type: application/json

{
    "amount": 15000,
    "type": "PAYOUT",
    "back_url": "https://back.kz",
    "success_url": "https://success.kz",
    "failure_url": "https://failure.kz"
}

cURL

curl --location --request POST 'https://stage-api.ioka.kz/v2/transfer-orders' \
--header 'API-KEY: eyJ0eXAiOiJKV1..' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 15000,
    "type": "PAYOUT",
    "back_url": "https://back.kz",
    "success_url": "https://success.kz",
    "failure_url": "https://failure.kz"
}'

Python

import requests
import json

url = "https://stage-api.ioka.kz/v2/transfer-orders"

payload = json.dumps({
    "amount": 15000,
    "type": "PAYOUT",
    "back_url": "https://back.kz",
    "success_url": "https://success.kz",
    "failure_url": "https://failure.kz"
})
headers = {
    'API-KEY': 'eyJ0eXAiOiJKV1..',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
order = response.json()['order']

print(order['checkout_url'])

PHP

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://stage-api.ioka.kz/v2/transfer-orders');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "amount": 15000,
    "type": "PAYOUT",
    "back_url": "https://back.kz",
    "success_url": "https://success.kz",
    "failure_url": "https://failure.kz"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'API-KEY' => 'eyJ0eXAiOiJKV..',
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Пример ответа:

{
    "order": {
        "id": "tro_1234567890",
        "status": "NOT_TRANSFERRED",
        "created_at": "2023-01-01T12:00:00.000000",
        "shop_id": "shp_test",
        "type": "PAYOUT",
        "amount": 15000,
        "currency": "KZT",
        "external_id": null,
        "description": null,
        "extra_info": null,
        "due_date": null,
        "corp_card_id": null,
        "receiver_id": "TESTCARDID",
        "back_url": "https://back.kz",
        "success_url": "https://success.kz",
        "failure_url": "https://failure.kz",
        "template": null,
        "checkout_url": "https://stage-api.ioka.kz/transfer-orders/tro_1234567890"
    },
    "order_access_token": "tro_1234567890_secret_a564b..."
}

Статусы заказа

Статус	Описание
NOT_TRANSFERRED	Первоначальный статус. По заказу не была осуществлена успешная выплата.
TRANSFERRED	Перевод по заказу был произведен успешно

Перенаправление клиента на форму выплаты

Для осуществления выплаты необходимо перенаправить пользователя на адрес checkout_url, полученный в теле ответа на создание заказа, где находится форма сбора карточных данных.

Заказ можно считать успешным, как только он перешел в статус TRANSFERRED. Плательщик может вернуться на страницу магазина, если при создании заказа были переданы параметры back_url, success_url, failure_url.

В случае неуспешной попытки, на форме будет показана причина отклонения и появится возможность осуществить выплату повторно.

Проверка статуса выплаты

Доступны несколько способов для проверки статуса платежа:

1. Настроить получение уведомлений (webhook-ов) от ioka на события TRANSFER_APPROVED, TRANSFER_DECLINED.
2. Периодически запрашивать информацию о заказе методом GetTransferOrderByID: Пример запроса:

HTTP

GET /v2/transfer-orders/{{transfer_order_id}} HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..

cURL

curl --location --request GET 'https://stage-api.ioka.kz/v2/transfer-orders/{{transfer_order_id}} \
--header 'API-KEY: eyJ0eXAiOiJKV1..' 

Python

import requests

url = "https://stage-api.ioka.kz/v2/transfer-orders/{{transfer_order_id}}"

headers = {
    'API-KEY': 'eyJ0eXAiOiJKV1..'
}

response = requests.get(url, headers=headers)
order = response.json()['order']

print(order['checkout_url'])

PHP

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://stage-api.ioka.kz/v2/transfer-orders/{{transfer_order_id}}');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'API-KEY' => 'eyJ0eXAiOiJKV..'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Пример ответа:

{
    "id": "tro_1234567890",
    "status": "TRANSFERRED",
    "created_at": "2023-08-01T09:46:09.066330",
    "shop_id": "shp_47L5EG2WT8",
    "type": "PAYOUT",
    "amount": 15000,
    "currency": "KZT",
    "external_id": null,
    "description": null,
    "extra_info": null,
    "due_date": null,
    "corp_card_id": null,
    "receiver_id": "e5KLDQmQTQ",
    "back_url": "https://back.kz",
    "success_url": "https://success.kz", 
    "failure_url": "https://failure.kz",
    "template": null,
    "checkout_url": "https://dev-transfers.ioka.kz/transfer-orders/tro_1234567890",
    "transfers": [
        {
            "id": "trn_Q7X6ZLDDZF",
            "order_id": "tro_1234567890",
            "status": "DECLINED",
            "created_at": "2023-08-01T09:47:30.217477",
            "transferred_amount": null,
            "processing_fee": 0.0,
            "sender": {
                "id": null,
                "pan_masked": "440563******5096",
                "expiry_date": "12/24",
                "holder": null,
                "payment_system": "VISA",
                "emitter": "halykbank",
                "email": null,
                "phone": null
            },
            "acquirer": null,
            "tds": null,
            "action": null,
            "error": {
                "code": "WRONG_CARD_DATA",
                "message": "Проверьте введённые данные карты и повторите еще раз."
            },
            "receiver_pan_masked": "440563******0013"
        },
        {
            "id": "trn_44DHXUAJRU",
            "order_id": "tro_1234567890",
            "status": "APPROVED",
            "created_at": "2023-08-01T09:48:00.501788",
            "transferred_amount": null,
            "processing_fee": 0.0,
            "sender": {
                "id": "pyr_TESTCARDID",
                "pan_masked": "440563******5096",
                "expiry_date": "01/25",
                "holder": null,
                "payment_system": "VISA",
                "emitter": "halykbank",
                "email": null,
                "phone": null
            },
            "acquirer": {
                "name": "epay_v2",
                "reference": "321352483756"
            },
            "tds": null,
            "action": null,
            "error": null,
            "receiver_pan_masked": "440563******0013"
        }
    ]
}

Выплата на сохраненную карту

Сохранение данных получателя

Для сохранения информации о получателе вам необходимо создать плательщика, а затем сохранить карточные данные в системе ioka, перенаправив плательщика на форму сохранения карты. Вы можете более подробно ознакомиться с необходимыми методами в разделе "Сохранение карты".

Отправка запроса для инициации выплаты по receiver_id

Для инициации выплаты на успешно сохраненную карту необходимо создать заказ и инициировать выплату по transfer_order_id (order.id), с указанием receiver_id (card.id, полученный после успешного сохранения):

Пример запроса:

HTTP

POST /v2/transfer-orders/{{transfer_order_id}}/payout HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..
Content-Type: application/json

{
    "receiver_id": "TESTCARDID"
}

cURL

curl --location --request POST 'https://stage-api.ioka.kz/v2/transfer-orders/{{transfer_order_id}}/payout' \
--header 'API-KEY: eyJ0eXAiOiJKV1..' \
--header 'Content-Type: application/json' \
--data-raw '{
    "receiver_id": "TESTCARDID"
}'

Python

import requests
import json

url = "https://stage-api.ioka.kz/v2/transfer-orders/{{transfer_order_id}}/payout"

payload = json.dumps({
    "receiver_id": "TESTCARDID"
})
headers = {
    'API-KEY': 'eyJ0eXAiOiJKV1..',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
order = response.json()['order']

print(order['checkout_url'])

PHP

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://stage-api.ioka.kz/v2/transfer-orders/{{transfer_order_id}}/payout');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "receiver_id": "TESTCARDID"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'API-KEY' => 'eyJ0eXAiOiJKV..',
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Пример ответа:

{
    "id": "trn_0EL3ODJLBJ",
    "order_id": "tro_SBPVLX6HSI",
    "status": "APPROVED",
    "created_at": "2023-08-01T11:59:59.815460",
    "transferred_amount": 15000,
    "processing_fee": 0.0,
    "acquirer": {
        "name": "epay_v2",
        "reference": "321356018766"
    },
    "tds": false,
    "receiver_pan_masked": "440563******0013"
}

Тестовые карты

Описание	Номер карты	CVV	Срок действия	Платежная система
Карта получателя	5522042705066736	525	01/2025	Mastercard
Карта отправителя	4405639704015096	815	01/2025	Visa