Skip to main content

Выплаты

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

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

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

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

{
"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: Пример запроса:
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": "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, полученный после успешного сохранения):

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

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

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

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