Вебхуки

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

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

Что отправлять в ответ​

ready_to_confirm​

Банк ждет от вас подтверждения, чтобы провести операцию (обязательно)​

Параметры уведомления​

Пример вебхука ready_to_confirm для подтверждения выплаты​

Пример вебхука ready_to_confirm для проведения оплаты​

payment_finished​

Банк сообщает вам о результате операции (обязательно)​

Параметры уведомления​

Пример вебхука payment_finished​

action_required​

Банк ждет дополнительный действий от вас или ваших пользователей (необязательно)​

Параметры вебхука​

Пример вебхука action_required​

ready_to_capture​

Банк сообщает вам, что деньги заморожены (необязательно)​

Параметры вебхука​

Пример вебхука ready_to_capture​

payment_refunded​

Банк 131 сообщает вам о результате проведения возврата​

Параметры вебхука​

Пример вебхука payment_refunded​

nominal_topup​

Банк сообщает вам о пополнении номинального счета (необязательно)​

Параметры уведомления​

Пример вебхука nominal_topup​

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

Что отправлять в ответ

`ready_to_confirm`

Банк ждет от вас подтверждения, чтобы провести операцию (обязательно)

Параметры уведомления

Пример вебхука ready_to_confirm для подтверждения выплаты

Пример вебхука ready_to_confirm для проведения оплаты

`payment_finished`

Банк сообщает вам о результате операции (обязательно)

Параметры уведомления

Пример вебхука payment_finished

`action_required`

Банк ждет дополнительный действий от вас или ваших пользователей (необязательно)

Параметры вебхука

Пример вебхука action_required

`ready_to_capture`

Банк сообщает вам, что деньги заморожены (необязательно)

Параметры вебхука

Пример вебхука ready_to_capture

`payment_refunded`

Банк 131 сообщает вам о результате проведения возврата

Параметры вебхука

Пример вебхука payment_refunded

`nominal_topup`

Банк сообщает вам о пополнении номинального счета (необязательно)

Параметры уведомления

Пример вебхука nominal_topup