Documentation

Documentation

  • Bank 131 API
  • Languages iconEnglish
    • Русский

›How Payments Work

131 Documentation

  • API features
  • Where to begin

Introduction to API

  • Interaction
  • API libraries
  • Testing
  • Version history

How Payouts Work

  • Features
  • How it all works
  • Main payout scenario
  • Payout refunds
  • The Self-employed

    • Payouts to the self-employed
    • Linking the self-employed

    Payout Methods

    • To a Russian bank card
    • To a foreign bank card
    • To a Russian bank account
    • To a QIWI Wallet
    • To a YooMoney (Yandex.Money)
    • To the Russian Federal Tax Agency

    Payout Scenarios

    • Payout to a card via widget
    • Single-request payout
    • Payout to a card with PCI DSS
    • Payout to a self-employed person with fiscal receipt

How Payments Work

  • Features
  • Payment process
  • Payments via bank card
  • Payments with later capture
  • Refunds
  • Recurring payments
  • Split Payments

    • Features and options
    • Split payments out of the box
    • Split payments using API

    Payment Scenarios

    • Paying via payment form
    • Paying with PCI DSS
    • Single-request payment

Widgets

  • Widget to get card details
  • Payment form widget
  • Widget for linking a self-employed person to the Bank

Passport Verification

  • Features
  • Interaction
  • Verification request
  • Verification status
  • HTTP codes

Reports

  • Payouts report
  • Payments report
  • Monthly report

API Reference

  • Objects
  • Methods
  • Webhooks
  • Error codes

Recurring payments

A recurring payment (or repeat payment) enables you to accept a payment and debit money without involving the user, via a token.

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

Recurrent token

How to get a 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.

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

The token may expire (e.g. if the associate 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 token in the request recurrent/status. In return, you will get RecurrentDetails 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 automatic payments), send a request recurrent/disable.

In response, you will receive RecurrentDetails. If is_active: false, it means the token is disabled and you cannot perform payments via it 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).

No-widget payment

When creating a payment session, you need to specify the value true in the field recurrent in PaymentOptions.

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

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

Widget payment

You need to show the user that recurrent debiting will be enabled after the payment, and obtain the user's consent using the checkbox Enable Automatic Payments.

To show this checkbox in the payment form, send a token creation request and specify the value true in the field show_recurrent_checkbox.

Example of creating a token for the recurrent payment enabling widget

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

Then, create a payment form with this token. If a user checks the box Enable Automatic 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 automatic payments

Automatic 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 previous accepted payment.

Recurring payment creation response example

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);
← RefundsFeatures and options →
  • Recurrent token
    • How to get a token
    • How to learn the token status
    • How to disable a token
  • How to accept recurring payments
    • Step 1. Successfully perform a payment with an instruction to create a recurrent token
    • Step 2. Save the token on successful payment
    • Step 3. Accept payments using the recurrent token
Documentation
Documentation
PayoutsPaymentsAPI Reference
Step by step
Payout to a card via widgetPayout to a card with PCI DSSPayout to the self-employed Paying via payment form
Get in touch
Ideas and partnerships — partners@131.ruMedia — press@131.ru
© 2021 Bank 131