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 nominal account to a bank card
    • 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 Telegram

    • How to create your Telegram bot
    • How to connect your Telegram bot
    • How to setup your Telegram bot

    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 self-employed person with fiscal receipt

This scenario describes how to perform a payout to a self-employed person. The main points:

  • Before the payout, you need to check that the person is in fact self-employed. If they are not, you then invite them to register (via the Federal Tax Agency).
  • You need to check if the self-employed person is linked to Bank 131. If they are not linked, you link them using the special widget.
  • Finally, you need to supply the payout request with additional parameters for fiscalization with the Federal Tax Agency.

What to do before performing a payout to a self-employed person

Before the first payout, link the self-employed person to Bank 131.

  • How to create a linkage

If the self-employed person is linked to Bank 131, you can proceed with the payout.

Step 1. Show the user the widget to obtain the card number

If you are performing a payout to a bank card and do not have a PCI DSS certificate, obtain tokenized details of the bank card through the widget. To do this:

  1. Obtain the token using the token request (the token can only be used once).

  2. Using this token, set up the widget to obtain the card details, show it to the self-employed person, and obtain the card details in a secure form.

How to add the widget

You can now proceed with the payout.

Step 2. Create a payment session

Create a payment session: this will contain all the actions you perform. Send the session/create request and obtain the session identifier.

Request example: session creation

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

Step 3. Start a payout with fiscal receipt

Create a payout using the session/start/payout/fiscalization method. In the session_id parameter, pass the identifier of the session created at the very beginning. In the object ProfessionalIncomeTaxpayer, transmit fiscalization data:

  • in the field payer_type, the value legal (if the payment is sent by a Russian company)
  • in the field payer_tax_number, the Taxpayer Identification Number (INN in Russia) of the company that sends the payment (required if payer_type: legal)
  • in the field tax_reference, specify the Taxpayer Identification Number (INN in Russia) of the self-employed
  • in the field FiscalizationDetails, specify details for generating a receipt

The set of mandatory payout parameters depends on where you are sending money: to a Russian bank card, to a foreign bank card, to a bank account, or to a QIWI wallet.

A payout request example

cURL
PHP
curl --location --request POST 'https://demo.bank131.ru/api/v1/session/start/payout/fiscalization' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"fiscalization_details": {
"professional_income_taxpayer": {
"tax_reference": "590613976192",
"payer_type": "legal",
"payer_tax_number": "3316004710",
"payer_name": "OOO Roga and Kopyta",
"services": [
{
"name": "Goods delivery",
"amount_details": {
"amount": 5000,
"currency": "rub"
}
}
]
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "4242424242424242"
}
}
},
"amount_details": {
"amount": 5000,
"currency": "rub"
},
"metadata": "good",
"participant_details": {
"recipient": {
"full_name": "Ivanov Ivan"
}
}
}'
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\Collection\FiscalizationServiceCollection;
use Bank131\SDK\DTO\FiscalizationService;
use Bank131\SDK\DTO\Participant;
use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer;

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

$client = new Client($config);

$services = new FiscalizationServiceCollection();
$services[] = new FiscalizationService(
'Delivery',
new Amount(5000, 'rub'),
1
);

$incomeInformation = new ProfessionalIncomeTaxpayer(
$services,
'590000000000'
);

$incomeInformation->setPayerName('OOO Roga and Kopyta');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

$recipient = new Participant();
$recipient->setFullName('Ivanov Ivan');

$request = RequestBuilderFactory::create()
->startPayoutSessionWithFiscalization('3230')
->setIncomeInformation($incomeInformation)
->setCard(new BankCard('4242424242424242'))
->setAmount(5000, 'rub')
->setRecipient($recipient)
->setMetadata('good')
->build();

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

Successful response example

{
    "status": "ok",
    "session": {
        "id": "ps_3230",
        "status": "created",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "updated_at": "2018-05-27T02:03:00.000000Z",
        "payments": [
            {
                "id": "po_2909",
                "status": "in_progress",
                "created_at": "2018-05-27T02:03:00.000000Z",
                "payment_method": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "fiscalization_details": {
                    "professional_income_taxpayer": {
                        "tax_reference": "590000000000",
                        "payer_type": "legal",
                        "payer_tax_number": "3300000000",
                        "payer_name": "OOO Roga and Kopyta",
                        "services": [
                            {
                                "name": "Service description",
                                "amount_details": {
                                    "amount": 10000,
                                    "currency": "rub"
                                }
                            }
                        ]
                    }
                },
                "metadata": "order123",
                "participant_details": {
                    "recipient": {
                        "full_name": "Ivanov Ivan"
                    }
                }
            }
        ]
    }
}

Unsuccessful response example

{
    "error": {
        "code": "invalid_request",
        "description": "participant_details.recipient.full_name.not_blank"
    },
    "status": "error"
}

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 -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) {
$session = $hook->getSession();
//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 to the self-employed person 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
}
← Payout to a card with PCI DSSFeatures →
  • What to do before performing a payout to a self-employed person
  • Step 1. Show the user the widget to obtain the card number
  • Step 2. Create a payment session
  • Step 3. Start a payout with fiscal receipt
  • 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