Перейти к основному содержимому

Вебхуки

Вебхуки — это уведомления о событиях, которые происходят на стороне Банка 131. Банк отправляет вебхуки, чтобы сообщить о результате операции, запросить подтверждение или предупредить о действиях, которые вам нужно совершить. В рамках вебхуков вы также можете получать информацию о применяемой комиссии за операцию. Чтобы подключить данную функциональность, обратитесь к менеджеру Банка 131.

Как получать вебхуки

  1. В вашей системе создайте адрес, на который хотите получать вебхуки.
  2. Передайте его менеджеру Банка 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 отправляет вам этот вебхук после проведения возврата. В параметрах уведомления приходит информация о платежной сессии, включающей в себя информацию о возвратах.

Вебхук отправляется в следующих случаях:

Если возврат сделан в рамках процедуры 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"
}
]
}
}'