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

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

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

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

  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 --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 при создании платежной сессии и показать пользователю виджет без галочки, как при обычном платеже.

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

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 --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-коду →