Documentation

Documentation

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

›Payout Scenarios

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
    • Fiscalization

    Payout Methods

    • To a Russian bank card
    • To a Russian bank account
    • To a QIWI Wallet
    • To a YooMoney (Yandex.Money)
    • To the Russian Federal Tax Agency
    • Via FPS by a phone number

    Payout Scenarios

    • Payout to a card via widget
    • Payout from a settlement account
    • Payout from an escrow account
    • Payout in a foreign currency
    • 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
  • Payments via FPS by QR code
  • Payments via QIWI wallet
  • 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
  • Methods

    • Verification request
    • Verification status
  • Response and errors

The Self-employed

  • General info
  • Linking
  • Testing
  • Verification
  • Notifying
  • Accruals

Reports

  • Payouts report
  • Payments report
  • Monthly report

API Reference

  • Objects
  • Methods
  • Webhooks
  • Error codes

Payout to a bank card via widget

This scenario describes how to perform a payout to a bank card if you cannot obtain and store the bank card details on your side (i.e. you do not have a PCI DSS certificate).

You can obtain tokenized card details using the tokenization widget, and then perform the payout securely.

Step 1. Generate a public token

The token is needed to work with the widget. Send a request to create a token, and use it to pass the type of widget you want to work with. You will receive the token in response.

Request example

cURL
PHP
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '{
"tokenize_widget": {
"access": true
}
}'
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()
->setTokenizeWidget()
->build();

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

Step 2. Show the details collection form to the recipient

To do this, you'll need to access our JavaScript library and add the tokenization widget to the page, where the recipient will then be able to fill in the form with their card details.

The recipient then enters their card details, and you'll receive tokenized details that you can use to perform the payout.

You can initialize the widget using the token you have obtained at the previous step.

  • How to add the tokenization widget

Step 3. Begin the payout

Send a request for payment session creation (session/create), then a separate request for payout creation using this session's identifier (session/start/payout). In the EncryptedCard object, pass the tokenized bank card details obtained from the widget.

You can find information about the token or card through the method token/info. This includes receiving the last 4 numbers of the card, in order to show the user the payment destination.

The exact set of mandatory parameters depends on the recipient's card type.

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. if you are paying 100 rubles, you will need to pass 10000 in the amount_details.amount field).

View the parameters for payouts to Russian cards

Request examples

Create 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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '
{
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"metadata": "order123"
}'
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()
->createPayoutSession()
->setAmount(10000, 'rub')
->setMetadata('order123')
->build();

$response = $client->session()->create($request);
Payout start
cURL
PHP
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: e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff' \
-d '{
"session_id": "3230",
"payment_method": {
"type": "card",
"card": {
"type": "encrypted_card",
"encrypted_card": {
"number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09",
"expiration_date_hash":"f4286b9a8e0eb7974f34a996ee732fd861868f2fc7aaa7ed5cca8de2489534ad",
"cardholder_name_hash":"dd6cce1e06790019dd266c6f70430f87dd378df802c6b7494395156f62533ce6",
"security_code_hash":"7756b897e88c035f34c6658a147e263b29b480a5cdf76581012ff10ede478c4c"
}
}
},
"metadata": "good"
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\EncryptedCard;

$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()
->startPayoutSession('session_id')
->setCard(
new EncryptedCard(
'number_hash',
'expiration_date_hash',
'cardholder_name_hash',
'security_code_hash'
)
)
->setMetadata('good')
->build();

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

Step 4. Wait for notification that the Bank is ready to perform the payout

Bank 131 will send you the mandatory ready_to_confirm webhook (using the webhooks address you provided to your Bank 131 manager previously). 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.

You then reply with the 200 HTTP code.

Webhook example: ready_to_confirm

cURL
curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"
type": "ready_to_confirm",
"
session": {
"
id": "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": "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"
}
]
}
}'

An example of handling a webhook using SDK

PHP
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 5. Confirm or cancel the payout

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

Request example: confirm_request

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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "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');

Request example: cancel_request

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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "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 6. Wait to be notified of the results of the payout

Bank 131 will send you the mandatory payment_finished webhook. The webhook body will contain all the details of the payout. The result of the payout can be found in the payment.status field.

If the status is succeeded, then the payout has been successful. If the status is failed, then the payout has not been completed because of an error.

More about payout statuses

An example of handling a webhook using SDK

PHP
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
}
← Via FPS by a phone numberPayout from a settlement account →
  • Step 1. Generate a public token
  • Step 2. Show the details collection form to the recipient
  • Step 3. Begin the payout
  • Step 4. Wait for notification that the Bank is ready to perform the payout
  • Step 5. Confirm or cancel the payout
  • Step 6. Wait to be notified of the results of the payout
Documentation
Documentation
PayoutsPaymentsAPI ReferenceService documents
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
© 2023 Bank 131