Skip to main content

Payout to a bank card

This scenario describes how to perform a payout to a bank card if you decided to obtain and store bank card details on your side (you must comply with the additional PCI DSS requirements).

In this case, you have two options:

  • Create a payment session and perform the payout with a single request.
  • Create a payment session first, and then perform the payout.

Below is a description of the recommended option, the one that involves creating a session separately.

Payout to a card, with a session created separately​

Step 1. Create a payment session​

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

More about payment sessions

Use the request headers to pass your project identifier and the request's signature.

More about request format

Creating a session 
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 '{
  "metadata": "order123"
}'

Step 2. Start the payout​

Start the payout using the session/start/payout method.

  • In the session_id parameter, pass the identifier of the session created in Step 1.
  • In the type parameter of the payment_method/payout_details object, pass card.
  • In the bank_card object, pass the recipient's bank card details.

If you are sending money to a Russian bank card, you will need the following:

  • card number
  • recipient's name
  • amount in ruble decimal format (e.g. to pay 100 rubles, pass 10000 in the amount_details.amount field)

View the parameters for payouts to Russian cards

Request example 
curl -X POST \
https://demo.bank131.ru/api/v1/session/start/payout \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "good"
}'

Step 3. Wait for a notification that the Bank is ready to perform the payout​

Bank 131 will send you a ready_to_confirm webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). The webhook body will contain all the details of the payout.

Reply with the 200 HTTP code.

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",
    "next_action": "confirm",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}'
Handling the webhook using SDK 
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;

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

$client = new Client($config);

$hook = $client->handleWebHook('sign from headers', 'request body');

if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) {
    $session = $hook->getSession();
    //do your logic here
}

Step 4. Confirm or cancel the payout​

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

Confirming the session 
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"
}'
Canceling the session 
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"
}'

Step 5. Wait to be notified of the results of the payout​

Bank 131 will send you a payment_finished webhook. The webhook body will contain all the details of the payout. The result of the payout can be found in the status field of the payments/payout_list object.

If the status is succeeded, then the payout was successful. If the status is failed, then an error occurred during the payout.

More about the payout statuses

Handling the webhook using SDK 
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;

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

$client = new Client($config);

$hook = $client->handleWebHook('sign from headers', 'request body');

if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) {
    $session = $hook->getSession();
    //do your logic here
}