Secure API Docs (stage)

Webhook уведомления отправляются методом POST на notification_url.

Источник notification_url:

URL из запроса (/init, /withdrawal, /refund) имеет приоритет.
Если URL не передан в запросе, используется URL из настроек мерчанта.

Формат передачи:

В зависимости от настроек мерчанта используется application/json или application/x-www-form-urlencoded.

Рекомендации по обработке:

Всегда проверяйте signature.
Считайте delivery идемпотентным и дедуплицируйте события по webhook_id.
Возвращайте 2xx сразу после валидации подписи и постановки события в очередь.
Реальное финальное состояние операции при спорных кейсах подтверждайте через методы опроса статуса (/status, /withdrawal_request).

Webhook для Invoice

Поле	Описание	Пример
`order`	Номер заказа на стороне мерчанта	`df78cf8f-db88-4344-8d03-cdbd2a7077cf`
`amount`	Сумма invoice	`14.0000`
`status`	Статус invoice	`failed`
`currency`	Валюта invoice	`EUR`
`signature`	Подпись webhook	`0TUnDdSVPPX5OE28w3Kofc_PZV8jYWzgfUY47wdyF9M`
`timestamp`	Время успешной оплаты, приходит для `complete`/`partial_complete`	`2026-02-17T21:02:53+00:00`
`created_at`	Время создания invoice	`2026-02-17 17:26:32.882207+00:00`
`invoice_id`	ID invoice в системе	`019c6ca3-b0b1-03dd-0eaf-7d90862c7e2e`
`masked_pan`	Маскированный PAN карты (может быть пустым)	`411111XXXXXX1111`
`product_id`	ID endpoint/product	`019b6f11-bfb1-f170-1274-bcdaf8308b3d`
`webhook_id`	ID webhook (одинаковый при повторах)	`019c6d83-9908-48ec-9e50-66916c2ae099`
`amount_paid`	Фактически оплаченная сумма	`0.0000`
`custom_data`	Дополнительные данные	``
`customer_id`	ID клиента	`019c473b-6d73-41a7-e336-1101913f2d83`
`merchant_id`	ID мерчанта	`019b6f11-bf8a-34fd-284c-ff6f167ebc79`
`customer_fee`	Комиссия с покупателя	`0.0000`
`phone_number`	Телефон плательщика (может быть пустым)	`351934595652`
`webhook_type`	Тип webhook	`invoice`
`fee_from_merchant`	Комиссия с мерчанта	`0.0000`
`payment_status_updated_at`	Время последнего обновления платежного статуса	`2026-02-17 21:31:06.864601+00:00`
`payment_error_code`	Код ошибки, приходит только для неуспешного статуса (`failed`)	`provider_error`
`payment_error`	Текст ошибки, приходит только для неуспешного статуса (`failed`)	`Something went wrong`
`first_name`	Имя клиента, если было передано и включено в payload	`Dmitry`
`last_name`	Фамилия клиента, если была передана и включена в payload	`Rukhlenko`

Пример тела callback (webhook) по успешному invoice:

json

{
  "order": "20242577181",
  "amount": "3000.0000",
  "status": "complete",
  "currency": "RUB",
  "signature": "7Whj7Of_q3viHVGWWVrh-rOhQk51OzTAuBYbl_jE1HY",
  "timestamp": "2026-02-17T21:02:53+00:00",
  "created_at": "2026-02-17 20:17:10.258751+00:00",
  "invoice_id": "019c6d3f-e672-43c3-606e-a9a76c4a9a0c",
  "masked_pan": "",
  "product_id": "019667a5-0b06-3197-fa34-4dbaa6ca82d3",
  "webhook_id": "019c6d69-c408-3b2b-ee2e-1a9cac2acb65",
  "amount_paid": "3000.0000",
  "custom_data": "",
  "customer_id": "019847cc-f5cc-09b6-a22a-2138669e1261",
  "merchant_id": "01966446-681e-5bf4-d7c2-04a7349bfac3",
  "customer_fee": "0.0000",
  "phone_number": "",
  "webhook_type": "invoice",
  "fee_from_merchant": "397.5000",
  "payment_status_updated_at": "2026-02-17 21:02:53.937092+00:00"
}

Пример webhook неуспешного invoice. Набор полей зависит от настроек webhook; здесь показаны поля суммы и времени, доступные в актуальных версиях webhook. Поля timestamp нет, поскольку платёж не завершился успешно.

json

{
  "webhook_type": "invoice",
  "webhook_id": "00000000-0000-4000-8000-000000000002",
  "invoice_id": "00000000-0000-4000-8000-000000000102",
  "product_id": "00000000-0000-4000-8000-000000000201",
  "merchant_id": "00000000-0000-4000-8000-000000000301",
  "order": "order-demo-002",
  "amount": "100.0000",
  "amount_paid": "0.0000",
  "currency": "EUR",
  "status": "failed",
  "customer_fee": "0.0000",
  "fee_from_merchant": "0.0000",
  "masked_pan": "",
  "customer_id": "",
  "phone_number": "",
  "custom_data": "",
  "created_at": "2026-01-01 12:00:00.000000+00:00",
  "payment_status_updated_at": "2026-01-01 12:00:30.000000+00:00",
  "payment_error_code": "COMMON_ERROR",
  "payment_error": "Payment failed. Contact support",
  "signature": "{{webhook_signature}}"
}

Webhook для Withdrawal

Поле	Описание	Пример
`webhook_type`	Тип webhook	`withdrawal`
`withdrawal_request_id`	ID выплаты в системе	`9a7ef4da-34ab-40f2-bf20-cf05cb9dbef8`
`product_id`/`endpoint_id`	ID endpoint/product	`b3f47861-1510-4fe9-b7db-1b8a5511f6f6`
`merchant_id`	ID мерчанта	`bb8ca755-f9ec-4990-b21b-c56d28277887`
`order`	Ваш ID выплаты	`wdr-00001`
`requested_amount`	Запрошенная сумма	`100.0000`
`amount`	Фактическая сумма выплаты	`100.0000`
`fee_from_merchant`	Комиссия мерчанта	`1.0000`
`currency`	Валюта	`EUR`
`status`	Статус выплаты	`done` / `rejected`
`masked_pan`	Маскированная карта получателя	`411111XXXXXX1111`
`customer_id`	Идентификатор клиента	`9ad3c1a7-16cf-43bb-8a87-dab72bc9dc09`
`custom_data`	Дополнительные данные	`{...}`
`payment_error_code`	Код ошибки	`COMMON_ERROR`
`payment_error`	Текст ошибки	`Insufficient funds`
`webhook_id`	ID webhook (стабилен при ретраях)	`ac2c8cf6-6c1f-4499-b2da-c50152c6936a`
`signature`	Подпись webhook	`0juDyl...`

Пример тела callback (webhook):

json

{
  "webhook_type": "withdrawal",
  "withdrawal_request_id": "9a7ef4da-34ab-40f2-bf20-cf05cb9dbef8",
  "product_id": "b3f47861-1510-4fe9-b7db-1b8a5511f6f6",
  "merchant_id": "bb8ca755-f9ec-4990-b21b-c56d28277887",
  "order": "wdr-00001",
  "requested_amount": "100.0000",
  "amount": "100.0000",
  "fee_from_merchant": "1.0000",
  "currency": "EUR",
  "status": "done",
  "masked_pan": "411111XXXXXX1111",
  "customer_id": "9ad3c1a7-16cf-43bb-8a87-dab72bc9dc09",
  "custom_data": "",
  "webhook_id": "ac2c8cf6-6c1f-4499-b2da-c50152c6936a",
  "signature": "0juDylapbc0NtVGCobWHwTm3F_lMqUC8g0ivl3lH5O0"
}

Пример webhook отклонённой выплаты:

json

{
  "webhook_type": "withdrawal",
  "webhook_id": "00000000-0000-4000-8000-000000000004",
  "withdrawal_request_id": "00000000-0000-4000-8000-000000000402",
  "product_id": "00000000-0000-4000-8000-000000000201",
  "merchant_id": "00000000-0000-4000-8000-000000000301",
  "order": "withdrawal-demo-002",
  "requested_amount": "100.0000",
  "amount": "0.0000",
  "fee_from_merchant": "0.0000",
  "currency": "EUR",
  "status": "rejected",
  "masked_pan": "",
  "customer_id": "",
  "custom_data": "",
  "payment_error_code": "COMMON_ERROR",
  "payment_error": "Payment failed. Contact support",
  "signature": "{{webhook_signature}}"
}

requested_amount содержит запрошенную сумму выплаты, а amount — фактическую. Для отклонённой выплаты причина передаётся в payment_error_code и payment_error. Суммы в примере демонстрационные; обрабатывайте значения, полученные в webhook.

Webhook для Refund

Поле	Описание	Пример
`webhook_type`	Тип webhook	`refund`
`refund_id`	ID возврата	`8f30f6ef-d6b8-4200-9f54-8a0c1808f5d8`
`invoice_id`	ID исходного платежа	`d51817bd-efd6-4a76-a73a-81b2832cb432`
`product_id`	ID endpoint/product	`b3f47861-1510-4fe9-b7db-1b8a5511f6f6`
`merchant_id`	ID мерчанта	`bb8ca755-f9ec-4990-b21b-c56d28277887`
`order`	Ваш внешний ID	`order-0001`
`amount`	Сумма возврата	`10.0000`
`fee_from_merchant`	Комиссия мерчанта	`0.1000`
`currency`	Валюта	`EUR`
`masked_pan`	Маскированная карта	`411111XXXXXX1111`
`status`	Статус возврата	`new` / `pending` / `complete` / `failed`
`webhook_id`	ID webhook (стабилен при ретраях)	`c38b45c9-f4df-4d01-9c88-66a94d6dce7f`
`signature`	Подпись webhook	`i7iU9E...`

Пример тела callback (webhook):

json

{
  "webhook_type": "refund",
  "refund_id": "8f30f6ef-d6b8-4200-9f54-8a0c1808f5d8",
  "invoice_id": "d51817bd-efd6-4a76-a73a-81b2832cb432",
  "product_id": "b3f47861-1510-4fe9-b7db-1b8a5511f6f6",
  "merchant_id": "bb8ca755-f9ec-4990-b21b-c56d28277887",
  "order": "order-0001",
  "amount": "10.0000",
  "fee_from_merchant": "0.1000",
  "currency": "EUR",
  "masked_pan": "411111XXXXXX1111",
  "status": "complete",
  "webhook_id": "c38b45c9-f4df-4d01-9c88-66a94d6dce7f",
  "signature": "i7iU9E5cQ2Nwm0e8aA4R2QMj6rYyceK1K8y46oR4h4g"
}

Криптовалютные webhook

Криптовалютные пополнения используют webhook платежей, выплаты — webhook выплат. Уведомления отправляются, если включены для вашей интеграции. Набор общих полей зависит от настроек и версии webhook. При проверке подписи учитывайте все полученные поля, включая crypto_*.

В уведомлениях могут присутствовать дополнительные поля; их значения — строки:

Поле	Значение
`crypto_asset`	Идентификатор актива и сети, например `USDT_TRC20`
`crypto_amount`	Сумма перевода в блокчейне; сохраняйте точность десятичного числа
`crypto_tx_hash`	Хеш транзакции блокчейна
`crypto_from_address`	Адрес отправителя
`crypto_to_address`	Адрес назначения
`crypto_tag`	Tag или memo адреса назначения; может быть пустым, если не используется
`crypto_wallet_id`	ID кошелька для пополнений; только для webhook пополнения
`crypto_wallet_address`	Выданный адрес для пополнений; только для webhook пополнения

Пример уведомления о криптовалютном пополнении:

json

{
  "webhook_type": "invoice",
  "webhook_id": "b834ad91-d6d2-48a7-b1a0-2f7d7f3f3b1f",
  "merchant_id": "16ec5bed-30a5-470c-9b41-c74ead9d4855",
  "product_id": "e82b948f-5416-4560-bcd2-bbec03247dd5",
  "invoice_id": "5f6bce4e-d6f4-4381-a0cb-4810e39d9739",
  "order": "2d1c2e44-cbc2-4478-8b1a-ff354ecad4fc",
  "status": "complete",
  "amount": "100.000000000000000000",
  "currency": "USDT",
  "customer_id": "d4e816c8-eed4-4cff-a628-671c71594714",
  "customer_fee": "0.0000",
  "fee_from_merchant": "0.0000",
  "masked_pan": "",
  "phone_number": "",
  "custom_data": "",
  "timestamp": "2026-09-14T10:00:00+00:00",
  "crypto_asset": "USDT_TRC20",
  "crypto_amount": "100.000000000000000000",
  "crypto_tx_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "crypto_from_address": "TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8",
  "crypto_to_address": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj",
  "crypto_tag": "",
  "crypto_wallet_id": "58184561-a14b-4e42-8e37-6f47b8f7a754",
  "crypto_wallet_address": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj",
  "signature": "{{callback_signature}}"
}

Пример уведомления о завершённой криптовалютной выплате:

json

{
  "webhook_type": "withdrawal",
  "webhook_id": "2c3b4d5e-6f70-4812-9234-56789abcdef0",
  "merchant_id": "16ec5bed-30a5-470c-9b41-c74ead9d4855",
  "product_id": "e82b948f-5416-4560-bcd2-bbec03247dd5",
  "withdrawal_request_id": "9a7ef4da-34ab-40f2-bf20-cf05cb9dbef8",
  "order": "crypto-wdr-001",
  "status": "done",
  "requested_amount": "0.0001",
  "amount": "0.0001",
  "currency": "TRX",
  "fee_from_merchant": "0.0000",
  "masked_pan": "",
  "customer_id": "d4e816c8-eed4-4cff-a628-671c71594714",
  "custom_data": "",
  "crypto_asset": "TRX",
  "crypto_amount": "0.0001",
  "crypto_tx_hash": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
  "crypto_from_address": "TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8",
  "crypto_to_address": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj",
  "crypto_tag": "",
  "signature": "{{callback_signature}}"
}

Шесть полей перевода также могут присутствовать в ответе проверки статуса криптовалютной выплаты. Их отсутствие не меняет статус операции: сведения о транзакции блокчейна могут появиться позже. Поля ID и адреса кошелька относятся только к пополнениям.

Работа с Webhook

Webhook для Invoice

Webhook для Withdrawal

Webhook для Refund

Криптовалютные webhook