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

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

• без участия пользователя, по токену. Такие платежи называются Merchant Initialized Transaction (MIT);
• с идентификацией пользователя посредством 3D Secure. Такие платежи называются Customer Initialized Transaction (CIT).

Рекуррентные платежи, к которым относится описание этой странице, являются платежами MIT, участие пользователя в них не требуется. Подробнее о платежах с идентификацией пользователя (CIT).

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

При каждом новом платеже одной и той же картой генерируется новый рекуррентный токен. Он привязан не к карте, а к платежу. Если нужно идентифицировать карту, можно использовать cквозной идентификатор карты.

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

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

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

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

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

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

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

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

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

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

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

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

Токен для рекуррентных платежей

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

Полученный токен можно в дальнейшем использовать и для выплат.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cURL

curl -X POST
https://demo.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "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
  }
}'

PHP

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

curl -X POST \
https://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "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

curl -X POST 
https://demo.bank131.ru/api/v1/session/init/payment' \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "recurrent",
    "recurrent": {
      "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39"
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  }
}'

PHP

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);