Вебхуки
Вебхуки — это уведомления о событиях, которые происходят на стороне Банка 131. Банк отправляет вебхуки, чтобы сообщить о результате операции, запросить подтверждение или предупредить о действиях, которые вам нужно совершить. В рамках вебхуков вы также можете получать информацию о применяемой комиссии за операцию. Чтобы подключить данную функциональность, обратитесь к менеджеру Банка 131.
Как получать вебхуки
- В вашей системе создайте адрес, на который хотите получать вебхуки.
- Передайте его менеджеру Банка 131.
Что отправлять в ответ
Банк 131 ожидает, что в ответ на любой вебхук вы отправите HTTP-код 200.
Если в ответ Банк получит код 4** или 5**, то будет отправлять запрос через увеличивающийся промежутки времени, пока не получит ответ.
action_required
Банк ждет дополнительных действий от вас или ваших пользователей
Банк отправляет вам этот вебхук в случае, когда для продолжения операции вам или вашим пользователям нужно совершить какие-то действия. Например, пользователю необходимо пройти аутентификацию по 3D Secure при платеже банковской картой.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: action_required |
session | + | object | Платежная сессия |
Пример вебхука action_required
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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": "pm_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",
"bin": "220220"
}
},
"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"
}
}
},
"transaction_info": {
"rrn": "425307614918",
"auth_code": "057441"
}
}
]
}
}'
nominal_topup
Банк сообщает вам о пополнении номинального счета
Банк отправляет этот вебхук каждый раз, когда средства поступают на ваш номинальный счет в результате внутрибанковских или межбанковских операций. В теле вебхука содержится сумма поступивших средств, а также новый текущий баланс вашего счета.
Обратите внимание, что вы можете указать менеджеру Банка любой адрес, на который вы хотели бы получать данную информацию.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
inn | + | string | ИНН получателя |
kpp | - | string | КПП получателя |
account_number | + | string | Номер счета пополнения |
account_balance | + | int | Текущий баланс счета пополнения (Значение суммы в минорных единицах валюты. Если сумма платежа 100 рублей, передается 10000 ) |
doc_id | + | string | Идентификатор документа |
doc_num | + | string | Номер документа |
amount | + | int | Сумма платежа (Значение суммы в минорных единицах валюты. Если сумма платежа 100 рублей, передается 10000 ) |
currency | + | string | Код валюты платежа согласно ISO 4217 |
paymentDate | + | date | Дата и время проведения платежа в формате ISO 8601 |
purpose | - | string | Назначение платежа |
contragent_name | - | string | Имя отправителя |
contragent_inn | - | string | ИНН отправителя |
contragent_kpp | - | string | КПП отправителя |
contragent_account_number | + | string | Номер счета отправителя |
contragent_bank_bik | + | string | БИК банка отправителя |
contragent_bank_name | - | string | Наименование банка отправителя |
Пример вебхука nominal_topup
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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"
}'
payment_finished
Банк сообщает вам о результате операции
Банк отправляет этот вебхук, когда завершает операцию — оплату или выплату. В
теле вебхука приходят все параметры операции, в том числе ее статус (в поле
status
). Например, если вы отправляете выплату и получили статус succeeded
в этом вебхуке, значит, выплата прошла успешно.
Также в теле вебхука в параметре receipt
передается идентификатор чека ФНС и ссылка на него. Перейдите по ссылке, чтобы скачать чек.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: payment_finished |
session | + | object | Платежная сессия |
Пример вебхука payment_finished
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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": "po_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": "******"
}
},
"transaction_info": {
"rrn": "425307614918",
"auth_code": "057441"
}
}
]
}
}'
payment_refunded
Банк 131 сообщает вам о результате проведения возврата
Банк 131 отправляет вам этот вебхук после проведения возврата. В параметрах уведомления приходит информация о платежной сессии, включающей в себя информацию о возвратах.
Вебхук отправляется в следующих случаях:
- если вы сделали возврат с помощью метода
session/refund
, - если банк получателя вернул вам выплату на счет в российском банке,
- в рамках процедуры chargeback.
Если возврат сделан в рамках процедуры chargeback, в объекте
refunds
вы увидите дополнительную строку:"is_chargeback": true
.
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: payment_refunded |
session | + | object | Платежная сессия |
Пример вебхука payment_refunded
curl - X POST\
https: //partner.ru \
-H 'Content-Type: application/json'\ -
-H 'X-PARTNER-SIGN: signature' \
-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",
"bin": "220220"
}
},
"amount_details": {
"amount": 1000,
"currency": "rub"
},
"amounts": {
"fee": {
"merchant_fee": {
"amount": 10,
"currency": "RUB"
}
}
},
"transaction_info": {
"rrn": "425307614919",
"auth_code": "057441"
},
"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"
},
"transaction_info": {
"rrn": "425307614918",
"auth_code": "057441"
}
}]
}]
}
}'
ready_to_capture
Банк сообщает вам, что деньги заморожены
Банк 131 отправляет этот вебхук при холдировании — после первого этапа платежа,
который проходит в две стадии. Это значит, что сумма успешно заморожена, а Банк
ждет от вас команды. Чтобы списать деньги, отправьте запрос (session/capture
).
Чтобы отменить оплату, отправьте (session/cancel
).
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: ready_to_capture |
session | + | object | Платежная сессия |
Пример вебхука ready_to_capture
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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": "pm_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"
}
]
}
}'
ready_to_confirm
Банк ждет от вас подтверждения, чтобы провести операцию
Банк 131 отправляет этот вебхук, когда готов провести операцию — выплату или
платеж. Вам нужно проверить параметры операции и принять решение. Если всё
в порядке, подтвердите операцию: отправьте Банку (session/confirm
). Если что-то не так, отмените операцию: отправьте запрос (session/cancel
).
Параметры вебхука
Название | Обязательность | Тип | Описание |
---|---|---|---|
type | + | string | Тип вебхука: ready_to_confirm |
session | + | object | Платежная сессия |
confirm_information | - (обязательно только при операциях с номинальным счетом) | object | Информация для подтверждения операции |
Примеры вебхука ready_to_confirm
- Подтверждение выплаты
- Проведение оплаты
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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": "po_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"
}
]
}
}'
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-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": "pm_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"
}
]
}
}'