Payments by bank card

You can accept payments by bank cards.

This method is suitable for services that comply with the PCI DSS standard and store card data on their side.

Step 1. Create a payment session

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

Alternatively, you can use the session/init/payment method to create a session and a payment at the same time. In this case, specify all the payment parameters right away and skip the next step. This option is not recommended.

Creating a session

cURL
PHP

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": "good"
  }'

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('good')
    ->build();

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

Step 2. Start the payment

Start the payment using the session/start/payment method. Pass the session identifier along with the payment parameters.

Request example

cURL
PHP

curl -X POST \
  https://demo.bank131.ru/api/v1/session/start/payment \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_3230",
    "payment_details": {
      "type": "card",
      "card": {
        "type": "bank_card",
        "bank_card": {
          "number": "2200774546102058",
          "expiration_month": "01",
          "expiration_year": "26",
          "security_code": "123"
        }
      }
    },
    "customer": {
      "reference": "user123",
      "contacts": [{
        "email": "user@gmail.com"
      }]
    },
    "metadata": "good"
  }'

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;

$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()
    ->startPaymentSession('session_id')
    ->setCard(
        new BankCard(
            '2200774546102058',
            '01',
            '26',
            '123',
            'cardholder name'
        )
    )
    ->setCustomer(new Customer('user123'))
    ->setMetadata('good')
    ->build();

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

Step 3. 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.

Webhook 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_3230",
      "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": "2058",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }]
    }
  }'

Step 4. 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).

Confirming the session

cURL
PHP

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

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
PHP

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

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 5. Wait for a webhook on additional actions

The action_required webhook is sent if the payer's bank requests 3D Secure authentication.

Redirect the payer using the link from the customer_interaction.redirect.url parameter to complete 3D Secure authentication.

Webhook example

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "action_required",
    "session": {
      "id": "ps_3230",
      "status": "in_progress",
      "created_at": "2018-05-27T02:03:00.000000Z",
      "updated_at": "2018-05-27T02:03:00.000000Z",
      "acquiring_payments": [{
        "id": "pm_131",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [{
            "email": "user@gmail.com"
          }]
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "2058"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://bank131.ru?foo=bar",
            "base_url": "https://bank131.ru",
            "method": "POST",
            "qs": {
              "foo": "bar"
            },
            "params": {
              "paReq": "sdfew^//asdhbv",
              "MD": "abc75daefnn"
            }
          }
        }
      }]
    }
  }'

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

Payment scheme by bank card with PCI DSS

More about the payment statuses >

View error codes >

Step 1. Create a payment session​

Step 2. Start the payment​

Step 3. Wait for a webhook saying the payment is ready​

Step 4. Confirm or cancel the payment​

Step 5. Wait for a webhook on additional actions​

Step 6. Wait for a webhook with the payment results​

Sequence diagram​