Webhooks API

Webhooks are used to notify merchants about transaction updates in real-time. When a transaction status changes, a webhook event is triggered and sent to the merchant's configured endpoint.

Each webhook event contains the following structure:

{

  "name": "transaction.<status>",
  "merchantId": "123456",
  "data": {
    "id": "txn_abcdef123456",
    "amount": 1000,
    "balance": 9000,
    "currency": "USD",
    "status": "charged",
    "type": "payment",
    "paymentMethod": "card",
    "payerIp": "192.168.1.1",
    "merchantReference": "INV-1001",
    "description": "Order payment",
    "createdAt": "2024-04-01T12:00:00Z",
    "updatedAt": "2024-04-01T12:05:00Z",
    "authedAt": "2024-04-01T12:02:00Z",
    "confirmedAt": "2024-04-01T12:03:00Z",
    "processedAt": "2024-04-01T12:04:00Z",
    "processedAmount": 1000,
    "storeId": "store_1234",
    "terminalId": "term_5678",
    "secure3d": true,
    "paymentLinkId": "link_9999",
    "paymentSessionId": "sess_8888",
    "cardTokenId": "token_7777",
    "parentTransactionId": "txn_parent1234",
    "recurringType": "subscription",
    "retrievalReferenceNumber": "RRN987654321",
    "customerId": "cust_654321"
  }
}

Merchants should implement webhook listeners to handle these events and update their system accordingly. It is recommended to:

Log incoming events for debugging.
Process event data and update the order status.
Respond with a 200 OK to acknowledge receipt of the webhook.

API Вебхуков

Webhooks используются для уведомления продавцов об обновлениях транзакций в режиме реального времени. Когда статус транзакции изменяется, создаётся событие webhook и отправляется на настроенный у продавца endpoint.

Каждое событие webhook имеет следующую структуру:

{

  "name": "transaction.<status>",
  "merchantId": "123456",
  "data": {
    "id": "txn_abcdef123456",
    "amount": 1000,
    "balance": 9000,
    "currency": "USD",
    "status": "charged",
    "type": "payment",
    "paymentMethod": "card",
    "payerIp": "192.168.1.1",
    "merchantReference": "INV-1001",
    "description": "Order payment",
    "createdAt": "2024-04-01T12:00:00Z",
    "updatedAt": "2024-04-01T12:05:00Z",
    "authedAt": "2024-04-01T12:02:00Z",
    "confirmedAt": "2024-04-01T12:03:00Z",
    "processedAt": "2024-04-01T12:04:00Z",
    "processedAmount": 1000,
    "storeId": "store_1234",
    "terminalId": "term_5678",
    "secure3d": true,
    "paymentLinkId": "link_9999",
    "paymentSessionId": "sess_8888",
    "cardTokenId": "token_7777",
    "parentTransactionId": "txn_parent1234",
    "recurringType": "subscription",
    "retrievalReferenceNumber": "RRN987654321",
    "customerId": "cust_654321"
  }
}

Обработка событий Webhook

Продавцам следует реализовать webhook-обработчики для обработки этих событий и соответствующего обновления своей системы. Рекомендуется:

Логировать входящие события для отладки.
Обрабатывать данные события и обновлять статус заказа.
Отвечать 200 OK, чтобы подтвердить получение webhook.

26 August 2025