Добавление Callback URL

Callback URL — это URL-адрес, на который AlfaBit Pay отправляет уведомления о статусах транзакций. Эти уведомления позволяют вашему сервису получать обновления в реальном времени и автоматически обрабатывать изменения состояния транзакций.

Как добавить Callback URL:

1. Войдите в свою учетную запись AlfaBit Pay.

2. Перейдите в раздел “Мерчанты” и выберите нужного мерчанта.

3. Перейдите во вкладку "API ключи".

4. В секции Callback URL нажмите кнопку “Добавить” и укажите адрес, на который вы хотите получать уведомления.

5. После добавления Callback URL на него будут отправляться вебхуки обновления статусов транзакций.

Техническая информация о Callback URL

• Метод отправки: POST

• Формат данных: application/json

• Тело запроса (body) содержит сериализованный объект заказа, аналогичный ответу метода GET /integration/orders/:orderUid.

• Уведомления отправляются при изменении статуса транзакции.

Безопасность

⚠️ Важно! Вебхуки отправляются только с IP-адресов AlfaBit. Необходимо настроить ваш сервер на приём запросов только с доверенных IP

"callbackIps": [
  "18.194.211.115",
  "3.70.205.120",
  "3.250.143.116",
  "185.252.146.25"
]

Рекомендуется реализовать проверку IP-адреса источника при получении запроса.

Пример тела запроса

 {
  "netCommission": null,
  "comment": "Пример комментария",
  "publicComment": "Order N123456",
  "merchantUid": "11111111-2222-3333-4444-555555555555",
  "merchantName": "ExampleMerchant",
  "merchantId": "999",
  "type": "invoice-without-amount",
  "status": "inProgress",
  "invoiceCurrencyCode": null,
  "currencyInCode": "USDCSOL",
  "currencyOutCode": "USDT-INTERNAL",
  "invoiceAmount": "0",
  "amountInExpected": "0",
  "amountInFact": "850",
  "amountOutExpected": "849.48966",
  "amountOutFact": "0",
  "hedgeRate": "1.0004",
  "isDone": false,
  "apiMode": "api",
  "risk": "0",
  "requisites": "2xXXXXXXXHiddenXXXXXXXXXXXXXXX",
  "requisitesIn": "2xXXXXXXXHiddenXXXXXXXXXXXXXXX",
  "billingTag": null,
  "requisitesQrCode": "https://example.org/qr-code/sample.png",
  "assetInCode": "USDC",
  "assetOutCode": "USDT",
  "networkInCode": "SOL",
  "networkOutCode": null,
  "balanceAfter": "0",
  "callbackUrl": "https://yourdomain.com/webhook-handler",
  "invoicePublicUrl": "https://pay.example.org/invoice/xxxx-xxxx-xxxx",
  "txId": "7xZpTq8NjDF3VgAwQ12RtWvPqEoKcYB94XjUPkzdvNhLrA9mJXkLmGzEyWd7Ubcz",
  "expirationTime": "2025-04-09T12:14:33.418Z",
  "isImPayed": false,
  "isBayerPaysService": false,
  "serviceFeeCurrencyCode": null,
  "netFeeCurrencyCode": null,
  "id": 123456,
  "uid": "00000000-aaaa-bbbb-cccc-111111111111",
  "createdAt": "2025-04-09T11:54:33.609Z",
  "updatedAt": "2025-04-09T11:58:51.883Z",
  "deletedAt": null,
  "paymentTiming": "onTime",
  "amountValidity": "valid",
  "signature": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
}

В теле запроса передаётся JSON заказа — аналогичный GET /integration/orders/:orderUid.

Возможные статусы транзакции

Поле status может принимать одно из следующих значений:

Статус	Описание
created	Заявка создана, ожидается начало обработки
success	Транзакция завершена успешно
warning	Непредвиденная ошибка, требуется ручное вмешательство
failed	Ошибка при проведении транзакции
inProgress	Заявка находится в процессе выполнения
invoiceWaitCreate	Ожидается создание инвойса
invoiceNotCreated	Ошибка создания инвойса
invoiceWaitRequisites	Ожидается выдача реквизитов
invoiceWaitPay	Ожидание оплаты клиентом
invoiceWaitConfirms	Ожидание подтверждений в блокчейне
invoiceWaitCheck	Ожидание результата AML проверки
invoiceNotPayed	Инвойс не был оплачен
invoiceCheckBlocked	Транзакция пополнения приостановлена по результатам AML проверки
withdrawBlocked	Транзакция вывода приостановлена по результатам AML проверки