Вебхуки

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

Documentation

Самозанятые

Способы получения выплат

Выплаты по шагам

Сплит-платежи

Платежи по шагам

Методы

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

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

`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