Перейти к основному содержимому

Переводы

Переводы с карты на карту (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 - ссылка, служащая для перенаправления клиента на сайт мерчанта после неуспешного проведения перевода

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

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"
}

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

{
"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: Пример запроса:
GET /v2/transfer-orders/{{transfer_order_id}} HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..

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

{
"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.

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

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

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"
}

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

{
"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Срок действияПлатежная система
Карта получателя552204270506673652501/2025Mastercard
Карта отправителя440563970401509681501/2025Visa