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:

Obtain the token using the token request (the token can only be used once).
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
}

Documentation

The Self-employed

Payout Methods

Payout Scenarios

Split Payments

Payment Scenarios

Payout to a self-employed person with fiscal receipt

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

Request example: session creation

Step 3. Start a payout with fiscal receipt

A payout request example

Successful response example

Unsuccessful response example

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

Webhook example: ready_to_confirm

An example of handling a webhook using SDK

Step 5. Confirm or cancel the payout

Request example: confirm_request

Request example: cancel_request

Step 6. Wait to be notified of the results of the payout

An example of handling a webhook using SDK