Recurring payments

A recurring payment (or repeated payment) enables you to accept a payment and debit money without involving the user, via a token. Useful for all types of subscriptions.

Currently, recurring payments can only be accepted from a bank card; other options will be added soon.

How to create a recurring payment

  1. Obtain the user's consent to direct debits.
  2. Perform a successful payment that will recur, and get a recurrent token.
  3. Perform payments using this token.

User Consent

Why you need it

Recurring payments are direct debits. They are performed at your command. The user does not confirm them: they only see funds debited from their card. This is why you assume full responsibility for such payments: the amount, frequency, and user's consent.

You need user's consent for dispute situations (e.g. if the user complaints about an unauthorized debit).

How to obtain user's consent

You can do it in any way you find convenient. The main point is that you need to verify the user had been aware of automatic debits when they made the first payment, and agreed to them.

How to do it:

  1. describe payment terms to make sure the user will read them
  2. ask the user to confirm they understand and agree to the terms (e.g. add an unambiguous checkbox like Save card, Enable automatic payments, Enable recurring donations, etc.).

If the user checks the box, thus verifying their consent, recurring payments become enabled. If they don't, recurring payments are not activated.

The checkbox can be on your side (in this case, you will decide how it looks and where it is located) or on our side—in our payment widget.

Recurrent token

You need to perform one payment successfully, selecting the option to save bank card details. In response to this payment, you will receive a recurrent token. This token can be saved and used to accept future payments.

How to get a token

When creating a payment session

Send recurrent=true (in PaymentOptions).

You can do this when creating a payment session or in any payment request.

If such a payment is successfully performed, you will receive the recurrent token with which you will be able to repeat the payment.

In this case, you need to get the user's consent on your side beforehand.

In our payment widget

If you perform a payment with the widget, you can show the checkbox I agree to recurring payments to the user.

If the user checks this box and the payment is performed successfully, you will receive the recurrent token.

Token statuses

When you create a token, it becomes active (is_active: true) and you can perform payments via the token.

The token may expire (e.g. if the associated bank card expires).

If a token is inactive (is_active: false) or expired, the payment will not be processed and you will see an error.

How to learn the token status

Send the request token/info. In the type parameter, pass recurrent_token value, in the recurrent_token.token parameter pass the token.

In return, you will get RecurrentTokenInfo with the date of token expiration (finished_at) and status (is_active). If is_active: true, you can perform payments via this token.

How to disable a token

If you don't want to use a token for payments anymore (e.g. a user disabled recurring payments), send a request recurrent/disable.

In response, you will receive RecurrentTokenInfo. If is_active: false, it means the token is disabled and you cannot perform payments via token anymore.

How to accept recurring payments

Step 1. Successfully perform a payment with an instruction to create a recurrent token

The payment procedure can be performed however you like (e.g. with or without the widget).

When creating a payment session or in the payment request in PaymentOptions, pass truein the recurrent field.

Example of a payment request with an instruction to create a recurrent token

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

Widget payment

If you perform a payment with a widget, you can show the user the checkbox I agree to recurring payments.

For that, in the widget token creation request, pass true in the show_recurrent_checkbox field.

This is optional. You can obtain the user's consent earlier, pass recurrent: true when creating a payment session, and show the user the widget with no checkboxes—like with ordinary payments.

Example of creating a token for the widget with the checkbox "I agree to recurring payments"

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
    }
}

Then, create a payment form with this token.

If a user checks the box Enable recurring payments (i.e. agrees to enable recurrent debiting from their card), you will receive a recurrent token.

Example of a widget to enable or disable recurring payments

Recurring payment widget

Step 2. Save the token on successful payment

If the payment is performed successfully (and the user enables recurrent debiting when paying through the form), you will get the recurrent token in the webhook payment_finished.

Webhook request body example

{
  "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
      }
    }]
  }
}

Step 3. Accept payments using the recurrent token

Send a request to accept a payment with the recurrent payment type. Instead of a bank card, pass the recurrent token you saved after the previously accepted payment.

Response example for the recurring payment creation

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);
← RefundsIntegration with Google Pay™ →