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

Вебхуки

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

transaction_registration​

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

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

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

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

НазваниеОбязательностьТип данныхОписание
session_payment_id+stringID сессии payment
session+objectДанные сессии
  id+stringID сессии 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+stringID платежа
    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"
              }
            }
          }
        }
      }
    ]
  }
}