Documentation

Documentation

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

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

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

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

Работа с API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Виджеты

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

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

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

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

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

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

Справочник API

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

Рекуррентные платежи

Рекуррентный платеж (автоплатеж или повтор платежа) — это возможность проводить оплату и списывать деньги без участия пользователя, по токену.

Сейчас проводить рекуррентные платежи можно только банковской картой, позже появятся другие способы.

Как сделать рекуррентный платеж

  1. Получить согласие пользователя на безакцептные списания.
  2. Провести успешный платеж, который потом будет повторяться, и получить рекуррентный токен.
  3. Проводить платежи по этому токену.

Согласие пользователя

Зачем это нужно

Рекуррентные платежи — это безакцептные списания. Они отправляются по вашей команде, пользователь их никак не подтверждает — только видит, как с его карты списываются деньги. Поэтому вы за такие платежи полностью отвечаете: за сумму, периодичность списаний и за то, что пользователь согласен платить вам таким образом.

Согласие нужно в спорных ситуациях: например, если пользователь пожалуется, что деньги списали без его ведома.

Как его получить

Любым удобным способом. Главное, чтобы в спорной ситуации вы могли подтвердить, что пользователь знал об автоплатежах, когда совершал первый платеж, и согласился на них.

Как это можно сделать:

  1. описать условия подключения платежей так, чтобы пользователь точно их прочел,
  2. получить подтверждение, что он всё знает и согласен — например, добавить при оплате чекбокс с понятной подписью (Сохранить карту, Подключить автоплатеж, Подписаться на пожертвования или что-то еще).

Если пользователь отмечает, что согласен на автоплатежи, автоплатеж включается. Если нет — значит, нет.

Чекбокс может быть на вашей стороне (и тогда вы решаете, как он выглядит и где находится) или на нашей — в нашем платежном виджете.

Рекуррентный токен

Вам нужно провести один успешный платеж с указанием сохранить данные банковской карты. В ответ на такой платеж вернется рекуррентный токен. Токен можно сохранить и проводить с ним следующие платежи.

Как получить токен

При создании платежной сессии

Передайте в запросе recurrent=true (в объекте PaymentOptions).

Это можно сделать при создании платежной сессии или в любом запросе на проведение платежа.

Если такой платеж пройдет успешно, вам вернется рекуррентный токен, по которому этот платеж можно повторить.

В этом случае вам нужно получить согласие пользователя на своей стороне — заранее.

В нашем платежном виджете

Если вы проводите платеж с виджетом, то можете показать пользователю чекбокс Соглашаюсь на автоплатежи.

Если пользователь отметит этот вариант и платеж пройдет успешно, вам вернется рекуррентный токен.

Статусы токена

Когда вы создаете токен, он становится активным (is_active: true) — по нему можно проводить платежи.

Если токен неактивен (is_active: false), платеж не пройдет, вернется ошибка.

Как узнать статус токена

Отправьте запрос token/info. В поле type передайте значение recurrent_token, в поле recurrent_token.token — токен, статус которого нужно узнать.

В ответ придет RecurrentTokenInfo с датой, до которой действует токен (finished_at), и его статусом (is_active). Дата окончания действия токена finished_at никак не проверяется на стороне Банка — токен останется активным и после даты, указанной в этом параметре. Если is_active: true, значит, по этому токену можно проводить платежи. Важно помнить, что активный токен не гарантирует успешного прохождения платежа, отказ может быть получен от эмитента банковской карты.

Как отключить токен

Если вы больше не хотите использовать токен для платежей (например, пользователь отключил автоплатеж), отправьте запрос recurrent/disable.

В ответ придет придет RecurrentTokenInfo. Если is_active: false, значит, токен отключен, по нему больше нельзя проводить платежи.

После отключения токена в параметре даты окончания действия токена finished_at может появиться дата, относящаяся к 2000 году — она ни на что не влияет, можно не обращать на неё внимание.

Как проводить рекуррентные платежи

Шаг 1. Проведите успешный платеж с указанием создать рекуррентный токен

Платеж можно проводить любым способом (например, с виджетом или без него).

При создании платежной сессии или в запросе на создание платежа в PaymentOptions нужно передать в поле recurrent значение true.

Пример запроса на оплату с указанием создать рекуррентный токен

cURL
PHP
curl --location --request POST 'https://demo.bank131.ru/api/v1/session/init/payment' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"payment_details": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "4242424242424242",
"expiration_month": "01",
"expiration_year": "22",
"security_code": "087"
}
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"customer": {
"reference": "lucky"
},
"payment_options": {
"recurrent": true
}
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;
use Bank131\SDK\DTO\Customer;
use Bank131\SDK\DTO\PaymentOptions;

$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$paymentOptions = new PaymentOptions();
$paymentOptions->setRecurrent(true);

$request = RequestBuilderFactory::create()
->initPaymentSession()
->setCard(new BankCard('4242424242424242', '01', '22', '087'))
->setAmount(10000, 'rub')
->setCustomer(new Customer('lucky'))
->setPaymentOptions($paymentOptions)
->build();

$response = $client->session()->initPayment($request);

Платеж с виджетом

Если вы проводите платеж виджетом, можете показать пользователю на виджете чекбокс Соглашаюсь на автоплатежи.

Для этого в запросе на создание токена для виджета передайте в поле show_recurrent_checkbox значение true.

Это необязательно: вы можете получить согласие пользователя раньше, передать recurrent: true при создании платежной сессии и показать пользователю виджет без галочки, как при обычном платеже.

Пример создания токена для виджета с чекбоксом «Соглашаюсь на автоплатежи»

cURL
POST /api/v1/token HTTP/1.1
Host: demo.bank131.ru
X-PARTNER-SIGN: hsgfjhsgdljfgasljdfglasgfljasgdlfjaghsdlf
X-PARTNER-PROJECT: shop-acquiring
Content-Type: application/json

{
"acquiring_widget": {
"session_id": "ps_34851",
"show_recurrent_checkbox": true
}
}

Потом сформируйте платежную форму с этим токеном.

Если пользователь поставит галочку в чекбоксе Соглашаюсь на автоплатежи (то есть согласится на проведение рекуррентных списаний с карты), вам придет рекуррентный токен.

Пример виджета с возможностью включить и выключить автоплатеж

Виджет с автоплатежом

Шаг 2. Сохраните токен после успешного платежа

Если платеж пройдет успешно (и при оплате через платежную форму пользователь согласится на рекуррентные списания), в вебхуке payment_finished вернется рекуррентный токен.

Пример тела запроса в вебхуке

{
  "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",
    "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"
        }
      },
      "recurrent": {
        "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1",
        "created_at": "2020-07-14T13:17:11+03:00",
        "finished_at": "2020-07-31T16:05:42+03:00",
        "is_active": true
        },
      "amount_details": {
        "amount": 10000,
        "currency": "rub"
      },
      "payment_options": {
        "recurrent": true
      }
    }]
  }
}

Шаг 3. Проводите платежи с использованием рекуррентного токена

Отправьте запрос на проведение платежа с типом оплаты recurrent, вместо данных банковской карты передайте рекуррентный токен, который вы сохранили при предыдущем платеже.

Пример запроса на создание рекуррентного платежа

cURL
PHP
curl --location --request POST 'https://demo.bank131.ru/api/v1/session/init/payment' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"payment_details": {
"type": "recurrent",
"recurrent": {
"token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"customer": {
"reference": "lucky"
}
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Customer;

$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
->initPaymentSession()
->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39')
->setAmount(10000, 'rub')
->setCustomer(new Customer('lucky'))
->build();

$response = $client->session()->initPayment($request);
← ВозвратыПлатежи через СБП по QR-коду →
  • Согласие пользователя
    • Зачем это нужно
    • Как его получить
  • Рекуррентный токен
    • Как получить токен
    • Статусы токена
    • Как узнать статус токена
    • Как отключить токен
  • Как проводить рекуррентные платежи
    • Шаг 1. Проведите успешный платеж с указанием создать рекуррентный токен
    • Шаг 2. Сохраните токен после успешного платежа
    • Шаг 3. Проводите платежи с использованием рекуррентного токена
Documentation
Документация
Массовые выплатыПрием платежейСправочник APIЮридические документы
Сценарии по шагам
Выплата на карту с токеномВыплата на карту с PCI DSSВыплата самозанятомуОплата через платежную форму
Напишите нам
Предложения и идеи — partners@131.ruПресса — press@131.ru
© 2022 Банк 131