Payments using our payment widget

You can accept bank card payments via our payment widget. In this case, card data is stored at Bank 131, not on your side.

Step 1. Create a payment session

Create a session using the session/create method. You will receive the payment session identifier in response.

Example

cURL

curl -X POST \
  https://demo.bank131.ru/api/v1/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "customer": {
      "reference": "user123",
        "contacts": [{
          "email": "user@gmail.com"
        }]
    },
    "amount_details": {
      "amount": 10000,
      "currency": "rub"
    },
      "metadata": "order123"
  }'

PHP

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$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()
    ->createPaymentSession()
    ->setAmount(10000, 'rub')
    ->setMetadata('order123')
    ->build();

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

Step 2. Get a public token

A public token is required to initialize the widget. Send a request to Bank 131 to create a token (token), specifying the widget type as acquiring_widget. The response will contain your public token.

To perform recurring payments, add an I agree to recurring payments checkbox to the payment form. To do this, set the show_recurrent_checkbox parameter to true.

Example

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_123456"
    }
  }'

PHP

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$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()
    ->issuePublicTokenBuilder()
    ->setAcquiringWidget(
        'ps_123456',
        'https://success.url',
        'https://failed.url',
        false
    )
    ->build();

$publicTokenResponse = $client->widget()->issuePublicToken($request);
$publicToken = $publicTokenResponse->getPublicToken();

Step 3. Initialize the widget on your site

Initialize the widget on your site using the public token obtained in the previous step.

After this, the customer will be able to enter their bank card details into the data collection form, and Bank 131 will initiate the payment without your involvement.

Step 4. Wait for a webhook saying the payment is ready

Bank 131 will send you a ready_to_confirm webhook. This means that the payment can be performed and the Bank is waiting for you to confirm or cancel it.

Example

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
      "id": "ps_123456",
      "status": "in_progress",
      "created_at": "2018-05-27T02:03:00.000000Z",
      "updated_at": "2018-05-27T02:03:00.000000Z",
      "acquiring_payments": [{
        "id": "pm_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [{
            "email": "user@gmail.com"
          }]
        },
        "payment_details": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "order123"
      }]
    }
  }'

Step 5. Confirm or cancel the payment

Check the payment details and confirm that you are ready to perform the payment (session/confirm) or cancel it (session/cancel).

If you receive an action_required webhook, it means the customer's bank requires 3D Secure authentication. Redirection happens automatically.

Example

Confirming the session

cURL

curl -X POST \
  https://demo.bank131.ru/api/v1/session/confirm \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_123456"
  }'

PHP

use Bank131\SDK\Client;
use Bank131\SDK\Config;

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

$client = new Client($config);

$response = $client->session()->confirm('session_id');

Canceling the session

cURL

curl -X POST \
  https://demo.bank131.ru/api/v1/session/cancel \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_123456"
  }'

PHP

use Bank131\SDK\Client;
use Bank131\SDK\Config;

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

$client = new Client($config);

$response = $client->session()->cancel('session_id');

Step 6. Wait for a webhook with the payment results

Bank 131 will send you a payment_finished webhook. The result of the payment can be found in the status field of the acquiring_payments/payment_list array.

If the status is succeeded, then the payment was successful. If the status is failed, then the payment failed because of an error.

Sequence diagram

More about the payment statuses >

View error codes >