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.
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.
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 -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 valuelegal
(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 ifpayer_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 --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
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 -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 -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.
Also, the webhook body will contain information on the Federal Tax Service receipt in the receipt
parameter: its identifier and a link to download it. Click the link to download the receipt.
Sample receipt
An example of handling 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
}