Вебхуки
Вебхуки — это уведомления о событиях, которые происходят на стороне Банка 131. Банк отправляет вебхуки, чтобы сообщить о результате операции, запросить подтверждение или предупредить о действиях, которые вам нужно совершить. В рамках вебхуков вы также можете получать информацию о применяемой комиссии за операцию. Чтобы подключить данную функциональность, обратитесь к менеджеру Банка 131.
Как получать вебхуки
- Создайте адрес в вашей системе, на который хотите получать вебхуки.
- Передайте его менеджеру Банка 131.
- Сообщите менеджеру, какие вебхуки вам нужны (это зависит от вашего сценария работы с API). По умолчанию вам будут приходить только обязательные вебхуки.
Что отправлять в ответ
Банк 131 ожидает, что в ответ на любой вебхук вы отправите HTTP-код 200.
Если в ответ Банк получит код 4 или 5, то будет отправлять запрос через увеличивающийся промежутки времени, пока не получит ответ.
ready_to_confirm
Банк ждет от вас подтверждения, чтобы провести операцию (обязательно)
Банк 131 отправляет этот вебхук, когда готов провести операцию — выплату или
платеж. Вам нужно проверить параметры операции и принять решение. Если всё
в порядке, подтвердите операцию: отправьте Банку confirm_request
. Если что-то
не так, отмените операцию: отправьте запрос cancel_request
.
Параметры уведомления
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: ready_to_confirm |
session | + | PaymentSession | Платежная сессия |
confirm_information | - (обязательно только при операциях с номинальным счетом) | ConfirmInformation | Информация для подтверждения операции |
Пример вебхука ready_to_confirm для подтверждения выплаты
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "ps_3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"next_action": "confirm",
"payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_method": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"metadata": "good"
}
]
}
}'
Пример вебхука ready_to_confirm для проведения оплаты
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "ps_3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"metadata": "good"
}
]
}
}'
payment_finished
Банк сообщает вам о результате операции (обязательно)
Банк отправляет этот вебхук, когда завершает операцию — оплату или выплату. В
теле вебхука приходят все параметры операции, в том числе ее статус (в поле
status
). Например, если вы отправляете выплату и получили статус succeeded
в этом вебхуке, значит, выплата прошла успешно.
Также в теле вебхука в параметре receipt
передается идентификатор чека ФНС и ссылка на него. Перейдите по ссылке, чтобы скачать чек.
Параметры уведомления
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: payment_finished |
session | + | PaymentSession | Платежная сессия |
Пример вебхука payment_finished
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "payment_finished",
"session": {
"id": "ps_3230",
"status": "accepted",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "2018",
"status": "succeeded",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_method": {
"type": "bank_account",
"bank_account": {
"system_type": "ru",
"ru": {
"bic": "*******02",
"account": "****************5734",
"full_name": "***",
"description": "*****",
"is_fast": false
}
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"fiscalization_details": {
"professional_income_taxpayer": {
"services": [
{
"name": "****",
"amount_details": {
"amount": "10000",
"currency": "rub"
}
"quantity": 1
}
],
"tax_reference": "*********628",
"receipt": {
"id": "**********",
"link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print"
},
"payer_type": "foreign",
"payer_name": "******"
}
}
}
]
}
}'
action_required
Банк ждет дополнительный действий от вас или ваших пользователей (необязательно)
Банк отправляет вам этот вебхук в случае, когда для продолжения операции вам или вашим пользователям нужно совершить какие-то действия. Например, пользователю необходимо пройти аутентификацию по 3-D Secure при платеже банковской картой.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: action_required |
session | + | PaymentSession | Платежная сессия |
Пример вебхука action_required
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "action_required",
"session": {
"id": "ps_3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [{
"id": "131",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference":"user@131.ru"
},
"payment_details": {
"type": "card",
"card": {
"brand": "visa",
"last4": "8801"
}
},
"amount_details": {
"amount": 15000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"customer_interaction": {
"type": "redirect",
"redirect": {
"url": "https://bank131.ru?foo=bar",
"base_url": "https://bank131.ru"
"method": "POST",
"qs": {
"foo": "bar"
},
"params": {
"paReq": "sdfew^//asdhbv",
"MD": "abc75daefnn"
}
}
}
}]
}
}
}'
ready_to_capture
Банк сообщает вам, что деньги заморожены (необязательно)
Банк 131 отправляет этот вебхук при холдировании — после первого этапа платежа,
который проходит в две стадии. Это значит, что сумма успешно заморожена, а Банк
ждет от вас команды. Чтобы списать деньги, отправьте запрос session/capture
.
Чтобы отменить оплату, отправьте session/cancel
.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: ready_to_capture |
session | + | PaymentSession | Платежная сессия |
Пример вебхука ready_to_capture
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_capture",
"session": {
"id": "ps_3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "2018",
"status": "pending",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"metadata": "good"
}
]
}
}'
payment_refunded
Банк 131 сообщает вам о результате проведения возврата
Банк 131 отправляет вам этот вебхук после проведения возврата. В параметрах уведомления приходит информация о платежной сессии, включающей в себя информацию о возвратах.
Вебхук отправляется в следующих случаях:
- если вы сделали возврат с помощью метода
session/refund
, - если банк получателя вернул вам выплату на счет в российском банке,
- в рамках процедуры chargeback.
Если возврат сделан в рамках процедуры chargeback, в объекте
refunds
вы увидите дополнительную строку:"is_chargeback": true
.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Наименование хука. payment_refunded |
session | + | PaymentSession | Платежная сессия |
Пример вебхука payment_refunded
curl - X POST\
https: //partner.ru \
-H 'Content-Type: application/json'\ -
H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc'\ -
d '{
"type": "payment_refunded",
"session": {
"id": "ps_3230",
"status": "accepted",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [{
"id": "pm_2705",
"status": "succeeded",
"created_at": "2018-05-27T02:03:00.000000Z",
"finished_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "card",
"card": {
"brand": "visa",
"last4": "4242"
}
},
"amount_details": {
"amount": 1000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"metadata": "good",
"refunds": [{
"id": "rf_203",
"status": "accepted",
"created_at": "2018-05-27T02:03:00.000000Z",
"finished_at": "2018-05-27T02:03:00.000000Z",
"is_chargeback": true,
"amount_details": {
"amount": 1000,
"currency": "rub"
}
}]
}]
}
}'
nominal_topup
Банк сообщает вам о пополнении номинального счета (необязательно)
Банк отправляет этот вебхук каждый раз, когда средства поступают на ваш номинальный счет в результате внутрибанковских или межбанковских операций. В теле вебхука содержится сумма поступивших средств, а также новый текущий баланс вашего счета.
Обратите внимание, что вы можете указать менеджеру Банка любой адрес, на который вы хотели бы получать данную информацию.
Параметры уведомления
Название | Обязательность | Тип | Описание |
---|---|---|---|
inn | + | string | ИНН получателя |
kpp | - | string | КПП получателя |
account_number | + | string | Номер счета пополнения |
account_balance | + | int | Текущий баланс счета пополнения (Значение суммы в минорных единицах валюты. Если сумма платежа 100 рублей, передается 10000) |
payment | + | Payment | Данные платежа |
abs_doc_id | + | string | Идентификатор документа |
abs_doc_num | + | string | Номер документа |
amount | + | string | Сумма платежа (Значение суммы в минорных единицах валюты. Если сумма платежа 100 рублей, передается 10000) |
currency | + | string | Код валюты платежа согласно ISO 4217 |
payment_date | + | date | Дата и время проведения платежа в формате ISO 8601 |
purpose | - | string | Назначение платежа |
contragent | + | Contragent | Данные контрагента |
name | - | string | Имя контрагента |
inn | - | string | ИНН контрагента |
kpp | - | string | КПП контрагента |
account_number | + | string | Номер счета контрагента |
bank_bik | + | string | БИК банка контрагента |
bank_name | - | string | Наименование банка контрагента |
Пример вебхука nominal_topup
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"inn": "3316004790",
"kpp": "156605101",
"account_number": "40702810600200000014",
"account_balance": 518619720,
"doc_id": "2080040124641368",
"doc_num": "333",
"amount": 66660,
"currency": "810",
"paymentDate": "2023-07-27T20:04:36.807000+03:00",
"purpose": "Пополнение номинального счета на сумму в размере 5896.60 рублей",
"contragent_name": "ООО Рога и Копыта",
"contragent_inn": "1655415696",
"contragent_kpp": "165501001",
"contragent_account_number": "30110810800000000593",
"contragent_bank_bik": "049205131",
"contragent_bank_name": "ООО \"Банк 131\""
}'