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 раз