Переводы

Переводы с карты на карту (P2P) - удобное и безопасное решение для онлайн-переводов денег между картами различных банков в РК. Для осуществления перевода необходимы полные данные карты отправителя и получателя.

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

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

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

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

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

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

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

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

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

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

• 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": "TOPUP",
    "receiver_id": "TESTCARDID",
    "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": "TOPUP",
    "receiver_id": "TESTCARDID",
    "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": "TOPUP",
    "receiver_id": "TESTCARDID",
    "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": "TOPUP",
    "receiver_id": "TESTCARDID",
    "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": "TOPUP",
        "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": "TOPUP",
    "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"
        }
    ]
}

Перевод с сохраненной карты

Важно

Если клиент при первом переводе выбрал Сохранить карту на этом сайте, то в webhook-е или в ответе на запрос GetTransferOrderByID, в объекте sender придет заполненный параметр id.

Для инициации выплаты с успешно сохраненной карты необходимо отправить запрос:

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

HTTP

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

{
    "sender_id": "pyr_TESTCARDID"
}

cURL

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

Python

import requests
import json

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

payload = json.dumps({
    "sender_id": "pyr_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}}/topup');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "sender_id": "pyr_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,
    "sender": {
        "pan_masked": "440563******5096",
        "expiry_date": "01/25",
        "payment_system": "VISA",
        "emitter": "halykbank"
    },
    "acquirer": {
        "name": "epay_v2",
        "reference": "321356018766"
    },
    "tds": false,
    "receiver_pan_masked": "440563******0013"
}

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

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