Вебхуки
Вебхуки — это уведомления о событиях, которые происходят на стороне Банка 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": "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"
},
"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": "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"
},
"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": "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"
},
"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": "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"
},
"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": "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"
},
"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"
},
"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"
}
}]
}]
}
}'