Documentation

Documentation

  • API Банка 131
  • Languages iconРусский
    • English

›Справочник API

Документация

  • Возможности API
  • С чего начать

Работа с API

  • Формат работы
  • Библиотеки
  • Тестирование
  • История изменений

Массовые выплаты

  • Возможности
  • Как всё работает
  • Сценарии выплат
  • Возвраты выплат
  • Самозанятые

    • Выплаты самозанятым
    • Привязка самозанятого
    • Фискализация без выплаты

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

    • На российскую банковскую карту
    • На счет в российском банке
    • В кошелек QIWI
    • В кошелек ЮMoney (Яндекс.Деньги)
    • В налоговую
    • Через СБП по номеру телефона

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

    • Выплата на карту с виджетом
    • Выплата с номинального счета
    • Выплата одним запросом
    • Выплата на карту с PCI DSS
    • Выплата самозанятому с фискализацией

Прием платежей

  • Возможности
  • Процесс платежа
  • Платеж банковской картой
  • Платежи с холдированием
  • Возвраты
  • Рекуррентные платежи
  • Платежи через СБП по QR-коду
  • Платежи через Телеграм

    • Как создать платежного бота
    • Как подключить платежного бота
    • Как настроить платежного бота

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

    • Варианты и возможности
    • Сплит-платежи без доработок
    • Сплит-платежи по API

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

    • Оплата через платежную форму
    • Оплата с PCI DSS
    • Платеж одним запросом

Виджеты

  • Виджет для токенизации карты
  • Виджет платежной формы
  • Виджет для привязки самозанятого

Проверка паспорта

  • Возможности
  • Взаимодействие
  • Методы

    • Проверка паспорта
    • Статус проверки
  • Ответы и ошибки

Акты и реестры

  • Реестр выплат
  • Реестр платежей
  • Акт

Справочник API

  • Объекты
  • Методы
  • Вебхуки
  • Коды ошибок

Вебхуки

Вебхуки — это уведомления о событиях, которые происходят на стороне Банка 131. Банк отправляет вебхуки, чтобы сообщить о результате операции, запросить подтверждение или предупредить о действиях, которые вам нужно совершить.

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

  1. Создайте адрес в вашей системе, на который хотите получать вебхуки.
  2. Передайте его менеджеру Банка 131.
  3. Сообщите менеджеру, какие вебхуки вам нужны (это зависит от вашего сценария работы с 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 в этом вебхуке, значит, выплата прошла успешно.

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

НазваниеОбязательностьТипОписание
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": "card",
                    "card": {
                        "last4": "4242",
                        "brand": "visa"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "metadata": "good"
            }
        ]
    }
}'

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,
  • если банк получателя вернул вам выплату на счет в российском банке.

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

НазваниеОбязательностьТипОписание
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",
            "amount_details": {
                "amount": 1000,
                "currency": "rub"
            }
        }]
    }]
  }
}'

← МетодыКоды ошибок →
  • ready_to_confirm
  • payment_finished
  • action_required
  • ready_to_capture
  • payment_refunded
Documentation
Документация
Массовые выплатыПрием платежейСправочник APIЮридические документы
Сценарии по шагам
Выплата на карту с токеномВыплата на карту с PCI DSSВыплата самозанятомуОплата через платежную форму
Напишите нам
Предложения и идеи — partners@131.ruПресса — press@131.ru
© 2022 Банк 131