Skip to main content

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:

  1. Obtain the token using a 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 a session/create request and obtain the session identifier.

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 '{
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "order123"
}'

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 professional_income_taxpayer object, transmit fiscalization data:

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

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

Request example 
curl -X POST \
https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
    "fiscalization_details": {
        "professional_income_taxpayer": {
            "tax_reference": "590613976192",
            "payer_type": "legal",
            "payer_tax_number": "3316004710",
            "payer_name": "OOO Vector",
            "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"
        }
    }
}'
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 Vector",
            "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 a 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 
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": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "next_action": "confirm",
    "payments": [
      {
        "id": "po_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"
      }
    ]
  }
}'
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) {
    $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 session/confirm request) or cancel it (using the session/cancel request).

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 6. Wait to be notified of the results of the payout​

Bank 131 will send you a 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

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​

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::PAYMENT_FINISHED) {
    $session = $hook->getSession();
    //do your logic here
}