Skip to main content

Payouts using our widget or by token

You can make payouts to bank cards using a token or hash for a bank card. You can get a token/hash as follows:

A token does not depend on the project (X-PARTNER-PROJECT) within which it was created.

The scope of PCI DSS requirements that you must comply with depends on which option you choose.

Step 1. Get a public token​

The public token is needed to work with the widget. Send a token request to create a token, specifying the tokenize_widget widget type. You will receive a public token in response.

Request example 
curl -X POST \
  http://demo.bank131.ru/api/v1/token \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "tokenize_widget": {
      "access": true
    }
  }'

Step 2. Initialize the widget​

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

After this, the recipient can enter their bank card details into the widget form.

Step 3. Create a payment session​

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

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

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

Step 4. Start the payout​

Start the payout using the session/start/payout method. Pass the session identifier along with all the parameters for a payout with the hash you received from the widget.

info

You can find information on the hash or card using the token/info method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to.

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": "encrypted_card",
        "encrypted_card": {
          "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09"
        }
      }
    },
    "participant_details": {
      "recipient": {
        "full_name": "Ivanov Ivan Ivanovich"
      }
    },
    "amount_details": {
      "amount": 10000,
      "currency": "rub"
    },
    "metadata": "good"
  }'

Step 5. Wait for a webhook saying the payout is ready​

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

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": "2025-05-27T02:03:00.340663Z",
      "updated_at": "2025-05-27T02:03:00.745032Z",
      "next_action": "confirm",
      "payments": [{
        "id": "po_2025",
        "status": "pending",
        "created_at": "2025-05-27T02:03:00.203301Z",
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4940",
            "brand": "mir",
            "bin": "220024",
            "country_iso3": "RUS"
          }
        },
        "participant_details": {
          "recipient": {
            "full_name": "Ivanov Ivan Ivanovich"
          }
        },
        "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) {
    //do your logic here
}

Step 6. Confirm or cancel the payout​

Check the payout details and confirm that you are ready to perform the payout (session/confirm) or cancel it (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 7. Wait for a webhook with the payout results​

Bank 131 will send you a payment_finished webhook. The result of the payout can be found in the status field of the payments/payout_list array.

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 >

View error codes >

Example of how to handle a 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
}