Вебхуки

Вебхуки — это уведомления о событиях, которые происходят на стороне Банка 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",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "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",
                    "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
                }
            },
            "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",
                        "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
                    }
                },
                "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",
                        "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
                    }
                },
                "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",
                        "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "amounts": {
                  "fee": {
                    "merchant_fee": {
                      "amount": 10,
                      "currency": "RUB"
                    }
                  }
                },
                "metadata": "good"
            }
        ]
    }
}'

`transaction_registration`

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

родительская сессия, в рамках которой средства были приняты (session_payment_id),
текущая сессия, в рамках которой деньги были выданы (session_id),
сумма выдачи.

Платежный партнер может отключить передачу данного вебхука. Для этого надо обратиться к менеджеру Банка 131.

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

Название	Обязательность	Тип данных	Описание
session_payment_id	+	string	ID сессии payment
session	+	object	Данные сессии
id	+	string	ID сессии payout
status	+	string	Текущий статус сессии. Возможные значения
created_at	+	string	Дата и время создания сессии в формате RFC 3339. Пример: `2022-11-15T15:38:50.255803Z`
updated_at	+	string	Дата и время обновления сессии в формате RFC 3339. Пример: `2022-11-15T15:38:50.255803Z`
error	-	object	Ошибка. Возвращается только если была ошибка по сессии
description	-	string	Описание ошибки
code	-	string	Код ошибки
payments	+	array	Данные платежа
id	+	string	ID платежа
status	+	string	Текущий статус платежа. Возможные значения
created_at	+	string	Дата и время создания платежа в формате RFC 3339. Пример: `2022-11-15T15:38:50.255803Z`
finished_at	-	string	Дата и время финализации платежа в формате RFC 3339. Пример: `2022-11-15T15:38:50.255803Z`
payment_method	+	object	Способ платежа
type	+	string	Название способа платежа. Возможное значение: `moneysend`
amount_details	+	object	Объект `amount_details`, переданный в запросе
amount	+	float	Сумма в минорных значениях
currency	+	string	Валюта
paymentMetadata	-	object	Дополнительные метаданные
parentSessionId	-	string	Номер сессии `payment`
participant_details	+	object	Информация об отправителе и получателе. Объект гарантирован. Все ключи и вложенные объекты не гарантируются
sender	-	object	Данные отправителя. Объект гарантирован. Все ключи и вложенные объекты не гарантируются
recipient	-	object	Данные получателя. Объект гарантирован. Все ключи и вложенные объекты не гарантируются
error	-	object	Причина ошибки транзакции. Возвращается только если была ошибка по сессии
description	-	string	Описание ошибки
code	-	string	Код ошибки

Примеры вебхука transaction_registration

{
  "session_payment_id": "ps_949108",
  "session": {
    "id": "ps_949139",
    "status": "accepted",
    "created_at": "2023-03-03T15:00:05.864870Z",
    "updated_at": "2023-03-03T15:00:06.307414Z",
    "payments": [
      {
        "id": "po_231420",
        "status": "succeeded",
        "created_at": "2023-03-03T15:00:05.948271Z",
        "finished_at": "2023-03-03T15:00:06.136321Z",
        "payment_method": {
          "type": "moneysend",
          "moneysend": {}
        },
        "amount_details": {
          "amount": 143000,
          "currency": "USD"
        },
        "paymentMetadata": {
          "parentSessionId": "ps_949108"
        },
        "participant_details": {
          "sender": {
            "full_name": "Анастасия Медынич Олеговна",
            "first_name": "Анастасия",
            "last_name": "Медынич",
            "middle_name": "Олеговна",
            "country_iso3": "RUS",
            "city": "Стерлитамак",
            "postal_code": "",
            "building": "1",
            "date_of_birth": "1994-01-06",
            "street": "Конаковская",
            "state": "Республика Башкортостан",
            "description": "описание описания",
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "6916 706690",
              "issue_date": "2020-01-01",
              "division_code": "",
              "issued_by": "ОВД ПО Кировскому району"
            },
            "citizenship_country_iso3": "RUS",
            "service_point": {
              "id": "1",
              "name": "точка на Ленина",
              "country_iso3": "RUS",
              "state": "Москва",
              "city": "Москва",
              "street": "Ленина",
              "house": "1",
              "oktmo": "36634436111",
              "terminal_id": "345"
            },
            "source_of_money": "зарплата",
            "contacts": {
              "phone": {
                "full_number": "+79376151530",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "6151530"
              }
            }
          },
          "recipient": {
            "full_name": "Ivan Olegov Sergeevich",
            "first_name": "Ivan",
            "last_name": "Olegov",
            "middle_name": "Sergeevich",
            "date_of_birth": "1987-11-08",
            "currency": "USD",
            "contacts": {
              "phone": {
                "full_number": "+43523452345",
                "country_iso3": "TUR",
                "operator_code": "352",
                "short_number": "3452345"
              }
            }
          }
        }
      }
    ]
  }
}

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

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

action_required​

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

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

nominal_topup​

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

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

payment_finished​

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

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

payment_refunded​

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

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

ready_to_capture​

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

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

ready_to_confirm​

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

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

transaction_registration​

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

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

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

`action_required`

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

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

`nominal_topup`

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

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

`payment_finished`

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

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

`payment_refunded`

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

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

`ready_to_capture`

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

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

`ready_to_confirm`

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

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

`transaction_registration`

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