Вебхуки (Webhooks)

При изменении статуса инвойса WinWallet отправляет POST-запрос на callback_url, указанный при создании инвойса. Это server-to-server уведомление; Bearer-авторизация на стороне мерчанта для входящего webhook не требуется.

Формат входящего запроса

Метод и заголовки

Параметр	Значение
Метод	`POST`
Content-Type	`application/json`
Authorization	Не требуется

Тело запроса (payload)

Поле	Тип	Обязательный	Описание
`invoice_id`	string	Да	ID инвойса
`status`	integer	Да	Новый статус (2 = PAID и др.)
`amount`	integer	Да	Сумма инвойса
`currency`	string	Да	Валюта
`description`	string	Да	Описание
`merchant_transaction_id`	string	Да	ID транзакции мерчанта
`positions`	array	Да	Позиции инвойса
`merchant_data`	object	Нет	Данные, переданные при создании
`created_at`	integer	Да	UTC ms, создание
`updated_at`	integer	Да	UTC ms, последнее изменение статуса
`extra_data`	object	Да	Метаданные провайдера (чек, external id)

{
  "invoice_id": "inv_01970f4f6b7c7d52b2d9",
  "status": 2,
  "amount": 1500,
  "currency": "USD",
  "description": "Payment for order #1001",
  "merchant_transaction_id": "order_1001",
  "merchant_data": {
    "customer_id": 123,
    "order_id": "1001"
  },
  "positions": [
    {
      "title": "Premium subscription",
      "amount": 1500,
      "currency": "USD"
    }
  ],
  "created_at": 1779454179000,
  "updated_at": 1779454185000,
  "extra_data": {
    "provider_transaction_id": "txn_123456",
    "receipt_url": "https://pay.example.com/receipt/123"
  }
}
        

Идемпотентность и повторные доставки

Рекомендации:

Сохраняйте обработанные webhook в БД с уникальным ключом.
Сверяйте amount и currency с заказом в вашей системе.
При сомнении запросите актуальный статус через GET /invoice/status.

Ответ мерчанта

Ваш endpoint должен ответить HTTP 200 OK и JSON с полем success: true, чтобы шлюз считал доставку успешной.

{
  "success": true
}
        

Справочный контракт в OpenAPI

В спецификации описан эталонный контракт POST /invoice/callback (модели InvoiceCallbackRequest/InvoiceCallbackResponse). Реальный URL доставки — ваш callback_url, а не путь API WinWallet.

01 июня 2026