Skip to main content

Webhooks

При подтверждении платежа вашим клиентом, процесс оплаты может занять от нескольких минут до нескольких часов. Вместо того чтобы узнавать статус платежа, периодически отправляя GET-запросы, вы можете подписаться на уведомления (webhook, callback) о платежных событиях.

Платежные события создаются при изменении статуса платежа. Как только событие создается, на которое вы подписались, ioka отправляет уведомление в виде POST-запроса на указанный вами Webhook URL. В уведомлении содержатся все данные платежа на момент, когда его статус изменился.

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

Формат Webhook URL

https://<your-website>/<your-webhook-endpoint>

Например, если ваш домен — https://myshop.kz, а маршрут к конечной точке веб-перехватчика — @app.route('/ioka_webhooks', method=['POST']), укажите https://myshop.kz/ioka_webhooks в качестве Webhook URL.

Платежные события

  • ORDER_EXPIRED: Создается после истечения срока действия заказа. Статус заказа: EXPIRED.
  • PAYMENT_DECLINED: Создается после неуспешной авторизации платежа. Статус платежа: DECLINED.
  • PAYMENT_APPROVED: Создается после успешной авторизации двухстадийного платежа. Статус платежа: APPROVED.
  • PAYMENT_CAPTURED: Создается после успешного списания платежа. Статус платежа: CAPTURED.
  • PAYMENT_CANCELED: Создается после успешной отмены авторизованного платежа. Статус платежа CANCELLED.
  • CARD_APPROVED: Создается после успешной верификации карты. Статус карты APPROVED.
  • CARD_DECLINED: Создается после неуспешной верификации карты. Статус карты DECLINED.

Полный список событий можно посмотреть в документации

Обработка полученных сообщений

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

ioka генерирует контрольную сумму, используя алгоритм HMAC вместе с SHA-256. В качестве ключа используется секретный ключ уведомления, который передается в ответе при создании уведомления.

Для дополнительной аутентификации источника уведомления, можете проверить IP-адрес отправителя:

  • В боевой среде уведомления будут приходить со следующих IP-адресов:
    • 94.247.132.210

Пример уведомления

Схема данных, отправляемых в уведомлении доступна в примере.

{
"event": "PAYMENT_APPROVED",
"order": {
"id": "string",
"shop_id": "string",
"status": "UNPAID",
"created_at": "string",
"amount": 0,
"currency": "KZT",
"capture_method": "AUTO",
"external_id": "string",
"description": "string",
"extra_info": {},
"due_date": "string"
},
"payment": {
"id": "string",
"order_id": "string",
"status": "PENDING",
"created_at": "2019-08-24T14:15:22Z",
"approved_amount": 0,
"captured_amount": 0,
"refunded_amount": 0,
"processing_fee": 0,
"payer": {
"pan_masked": "string",
"expiry_date": "string",
"holder": "string",
"payment_system": "string",
"emitter": "string",
"email": "user@example.com",
"phone": "string",
"customer_id": "string",
"card_id": "string"
},
"error": {
"code": "string",
"message": "string"
},
"acquirer": {
"name": "string",
"reference": "string"
},
"action": {
"url": "string"
}
}
}

При генерации контрольной суммы, все ключи объекта сортируется и убираются все пробелы между парами ключ-значение. Собирается json строка как указано в примере ниже:

{"event":"PAYMENT_APPROVED","order":{"amount":0,"capture_method":"AUTO","created_at":"string","currency":"KZT","description":"string","due_date":"string","external_id":"string","extra_info":{},"id":"string","shop_id":"string","status":"UNPAID"},"payment":{"acquirer":{"name":"string","reference":"string"},"action":{"url":"string"},"approved_amount":0,"captured_amount":0,"created_at":"2019-08-24T14:15:22Z","error":{"code":"string","message":"string"},"id":"string","order_id":"string","payer":{"card_id":"string","customer_id":"string","email":"user@example.com","emitter":"string","expiry_date":"string","holder":"string","pan_masked":"string","payment_system":"string","phone":"string"},"processing_fee":0,"refunded_amount":0,"status":"PENDING"}}

Стратегия доставки

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