Payout from a settlement account to a bank account

This scenario describes the way to send a payout from a settlement account to a bank account. The payout is split into two steps, when you send the main payout amount first, and then send the transaction fee, if there is any. Both transactions details will be available in the appropriate statement in the Online Bank. The API allows to send payouts to legal entities and individuals, including the self-employed individuals. All the API parameters are passed unencrypted.

Accounts eligible to receive payouts

You can send payouts only to the accounts that begin with these numbers:

40817810
42301810
42302810
42303810
42304810
42305810
42306810
42307810
40802810
40702810 (for the accounts of legal entities)
40701810
40502810

You cannot send payouts to an account that begins with any other number.

Step 1. Start the transaction

Send the request that creates a payment session and starts the payout using session/init/payout/rko.

Mandatory parameters

For residents
For non-residents

Name	Type	Description
payment_method	PaymentMethod	Payment details
type	string	value: `bank_account`
bank_account	BankAccountPaymentMethod	Bank account
system_type	string	Bank transfer system. Always: `ru`
ru	BankAccountRU	Bank account object
bik	string	Recipient's bank BIC
account	string	Recipient's bank account
full_name	string	The individual's full name. In case of a payout to an account of a sole proprietor should be passed in the following format: `ИП <full name>`.
inn	string	INN. Mandatory for the payouts to individual proprietors.
kpp	string	The recipient's Tax Registration Reason Code (KPP) Mandatory for payouts to legal entities' accounts.
description	string	The purpose of the payout. Reference information
participant_details	ParticipantDetails	Information on payout participants
sender	Participant	Sender's details
account	string	Settlement account to send payout from.
recipient	Participant	Recipient's details
amount_details	AmountDetails	Amount
amount	int	Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000`.
currency	string	Currency code by ISO 4217. Case insensitive. Always: `rub`

Name	Type	Description
payment_method	PaymentMethod	Payment details
type	string	value: `bank_account`
bank_account	BankAccountPaymentMethod	Bank account
system_type	string	Bank transfer system. Always: `ru`
ru	BankAccountRU	Bank account object
bik	string	Recipient's bank BIC
inn	string	The recipient's INN, 10 digits for legal entities, 12 digits for individuals. Mandatory for the payouts to the legal entities' accounts
kpp	string	The recipient's Tax Registration Reason Code (KPP) Mandatory for payouts to legal entities' accounts.
account	string	Recipient's bank account The individual's full name. In case of a payout to an account of a sole proprietor should be passed in the following format: `ИП <full name>`. In case of a payout to a legal entity, enter the entity's name, if it is provided in the agreement. Important: if the name is passed incorrectly the recipient bank may cancel the payout and the payout will be refunded.
description	string	The purpose of the payout, accompanied by the monetary transaction code (as agreed with a Bank 131 manager). How to set this out
amount_details	AmountDetails	Amount details
amount	int	Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000`
currency	string	Currency code by ISO 4217. Case insensitive. Always: `rub`
participant_details	ParticipantDetails	Information on payout participants
sender	Participant	Sender's details
full_name	string	Name. Mandatory if the sender is an individual.
company_name	string	Company name. Mandatory if the sender is a legal entity.
address_line	string	Address. Important: a city and country should be specified in the following fields, do not duplicate them here.
country_iso3	string	Country code (ISO-3166-1 alpha-3)
city	string	The city
recipient	Participant	Recipient's details
full_name	string	Recipient's full name.

How to set out the payout purpose

In the payout purpose field (BankAccountRU.description) according to Russian legislation, the following must be specified:

the type of operation (e.g. service fee)
the basis, or reason, for the payment (e.g. the agreement number)
the name of the products and/or services provided
whether or not VAT is applicable

If your organization is not based in Russia, you will also need to add a currency transaction code in the following format: {VO\<currency transaction code>} without any indents or spaces. The code needs to be agreed beforehand with a Bank 131 manager.

The payout purpose should not contain the following characters: ?, !. The maximum length is 210 characters.

#### An example of a payout purpose

For residents
For non-residents

Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt

{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt

An example of a request for a payout to an individual

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
    "bik": "044525974",
    "account": "40817810400003869535",
    "full_name": "Ivan Ivanovich Test",
    "description": "Wire by the agreement"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    }
  }
}'

An example of a request for a payout to a legal entity

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
    "bik": "044525974",
    "account": "40702810500000000001",
    "full_name": "Company name",
    "inn": "1111111111",
    "kpp": "156605101",
    "description": "Payout by the agreement"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    }
  }
}'

Step 2.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're recommended to keep the confirm_information object for confirmation purposes.

You then reply with the 200 HTTP code.

Example of a `ready_to_confirm` webhook

  curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
        "id": "ps_260159",
        "status": "in_progress",
        "created_at": "2023-01-17T13:41:59.352487Z",
        "updated_at": "2023-01-17T13:42:01.657512Z",
        "payments": [
            {
                "id": "po_67428",
                "status": "pending",
                "created_at": "2023-01-17T13:41:59.594022Z",
                "payment_method": {
                    "type": "bank_account",
                    "bank_account": {
                        "system_type": "ru",
                        "ru": {
                            "bik": "049205131",
                            "account": "40702810300000000006",
                            "full_name": "Recipient company name",
                            "description": "Wire by the agreement VAT exempt",
                            "is_fast": false
                        }
                    }
                },
                "amount_details": {
                    "amount": 2700,
                    "currency": "RUB"
                },
                "amounts": {
                    "net": {
                        "amount": 2700,
                        "currency": "RUB"
                    }
                }
           }
           ]
        }
    }

Step 3. Confirm or cancel the payout

Check the payout details and confirm that you are ready to perform the payout using confirm_request or cancel it using cancel_request. If you choose to confirm sending the payout, note that ConfirmInformation is mandatory in the request.

Example of `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: signature' \
  -d  '{
  "session_id": "ps_1048967",
     "confirm_information":{
      "account_details": {
            "sender": {
                "account_number": "40702810300200000013",
                "name": "Client's name",
                "bank_name": "Bank 131",
                "bik": "049205131",
                "correspondent_account_number": "30101810822029205131",
                "inn": "3316004790",
                "kpp": "156605101"
            },
            "recipient": {
                "account_number": "40702810300000000006",
                "name": "Recipient company name",
                "bank_name": "Bank 131",
                "bik": "049205131",
                "correspondent_account_number": "30101810822029205131"
            }
        }
    }
}'   

Example of `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: signature' \
  -d  '{
  "session_id": "ps_1048967",
     "confirm_information":{
      "account_details": {
            "sender": {
                "account_number": "40702810300200000013",
                "name": "Client's name",
                "bank_name": "Bank 131",
                "bik": "049205131",
                "correspondent_account_number": "30101810822029205131",
                "inn": "3316004790",
                "kpp": "156605101"
            },
            "recipient": {
                "account_number": "40702810300000000006",
                "name": "Recipient company name",
                "bank_name": "Bank 131",
                "bik": "049205131",
                "correspondent_account_number": "30101810822029205131"
            }
        }
    }
}'

Step 4. 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 has been successful. If the status is failed, then the payout has not been completed because of an error.

More about payout statuses.

Payout refund

The payout you sent to an account in a bank in Russian Federation is subject to refund. Refunds are carried out within 5 days.

Testing payouts

You can test payouts made from your settlement account. To do this, use the confirm_information object from the ready_to_confirm webhook. It contains test data that is passed by the server and can be used for testing purposes only. This object needs to be sent in the confirm_request request.

To carry out testing:

Submit a request to create a payment session.
Check the status of the payment session.
Wait for our webhook.
Submit a request with test data.
Check the status of the payment session.

`confirm_information` object

An object with test data for generating a ready_to_confirm request.

Name	Type	Description
confirm_information	object	Object for payout testing
account_details	object	Object with information about the sender and recipient accounts
sender	object	Object with test information about the sender account
account_number	string	Sender's account number
name	string	Sender's name
bank_name	string	Sender's bank name
bik	string	Sender's bank BIK
correspondent_account_number	string	Sender's correspondent account
inn	string	Sender's bank INN
kpp	string	Sender's bank KPP
recipient	object	Object with test information about the recipient account
account_number	string	Recipient's account number
name	string	Recipient's name
bank_name	string	Recipient's bank name
bik	string	Recipient's bank BIK
correspondent_account_number	string	Recipient's correspondent account
inn	string	Recipient's bank INN
kpp	string	Recipient's bank KPP

Step 1. Create a payment session with a simultaneous start of the payment

Send a session/init/payout/rko request with necessary data to initialize a payment session.

curl --location 'https://demo.bank131.ru/api/v1/session/init/payout/rko' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--header 'X-PARTNER-SIGN: signature' \
--header 'Content-Type: application/json' \
--data '{
    "payment_method": {
        "type": "bank_account",
        "bank_account": {
            "system_type": "ru",
            "ru": {
                "bik": "044525974",
                "account": "40702810500000000001",
                "full_name": "Romashki Ltd.",
                "inn": "3316004790",
                "kpp": "156605101",
                "description": "Payout"
            }
        }
    },
    "amount_details": {
        "amount": 350,
        "currency": "rub"
    },
    "participant_details": {
        "sender": {
            "account": "40702810900000000011"
        }
    }
}'

Step 2. Check the status of the payment session

Check the status of the created payment session using a session/status request. If everything is ready for further processing of the transaction, you will receive "session.next_action": "confirm".

curl --location 'https://demo.bank131.ru/api/v1/session/status' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--header 'X-PARTNER-SIGN: signature' \
--header 'Content-Type: application/json' \
--data '{
    "session_id": "ps_2643"
}'

Step 3. Wait for a webhook with the `confirm_information` object

Wait for a ready_to_confirm webhook with the confirm_information object. It will be used in further testing.

{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_2643",
    "status": "in_progress",
    "created_at": "2024-02-20T08:42:35.905869Z",
    "updated_at": "2024-02-20T08:42:36.382627Z",
    "payments": [
      {
        "id": "po_513",
        "status": "pending",
        "created_at": "2024-02-20T08:42:35.965210Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "044525974",
              "account": "40702810500000000001",
              "full_name": "Romashki Ltd.",
              "description": "Payout",
              "is_fast": false,
              "kpp": "156605101",
              "inn": "3316004790"
            }
          }
        },
        "amount_details": {
          "amount": 350,
          "currency": "RUB"
        },
        "amounts": {
          "net": {
            "amount": 350,
            "currency": "RUB"
          },
          "gross": {
            "amount": 350,
            "currency": "RUB"
          }
        },
        "paymentMetadata": {},
        "participant_details": {
          "sender": {
            "account": "40702810900000000011"
          }
        },
        "payment_options": {
          "recurrent": false,
          "is_subsequent": false
        }
      }
    ],
    "next_action": "confirm",
    "session_metadata": {}
  },
  "confirm_information": {
    "account_details": {
      "sender": {
        "account_number": "account_number",
        "name": "name",
        "bank_name": "bank_name",
        "bik": "bik",
        "correspondent_account_number": "correspondent_account_number",
        "inn": "inn",
        "kpp": "kpp"
      },
      "recipient": {
        "account_number": "40702810500000000001",
        "name": "Romashki Ltd.",
        "bank_name": "bank_name",
        "bik": "bik",
        "correspondent_account_number": "correspondent_account_number",
        "inn": "3316004790",
        "kpp": "156605101"
      }
    }
  }
}

Step 4: Send the `confirm_information` object to verify payouts

Copy the confirm_information object from the received response and send it in a confirm_request request.

curl --location 'https://demo.bank131.ru/api/v1/session/confirm' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--header 'X-PARTNER-SIGN: signature' \
--header 'Content-Type: application/json' \
--data '{
    "session_id": "ps_2643",
    "confirm_information": {
        "account_details": {
            "sender": {
                "account_number": "account_number",
                "name": "name",
                "bank_name": "bank_name",
                "bik": "bik",
                "correspondent_account_number": "correspondent_account_number",
                "inn": "inn",
                "kpp": "kpp"
            },
            "recipient": {
                "account_number": "40702810500000000001",
                "name": "Romashki Ltd.",
                "bank_name": "bank_name",
                "bik": "bik",
                "correspondent_account_number": "correspondent_account_number",
                "inn": "3316004790",
                "kpp": "156605101"
            }
        }
    }
}'

Step 5. Check the status of the test payment session

Check the status of the test payment session in a session/status request. If the payment session was successfully completed, you will receive a session.action object with data about all the operations (within this test session).

curl --location 'https://demo.bank131.ru/api/v1/session/status' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--header 'X-PARTNER-SIGN: signature' \
--header 'Content-Type: application/json' \
--data '{
    "session_id": "ps_2643"
}'

Accounts eligible to receive payouts​

Step 1. Start the transaction​

Mandatory parameters​

How to set out the payout purpose​

#### An example of a payout purpose​

An example of a request for a payout to an individual​

An example of a request for a payout to a legal entity​

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

Example of a ready_to_confirm webhook​

Step 3. Confirm or cancel the payout​

Example of confirm_request​

Example of cancel_request​

Step 4. Wait to be notified of the results of the payout​

Payout refund​

Testing payouts​

confirm_information object​

Step 1. Create a payment session with a simultaneous start of the payment​

Step 2. Check the status of the payment session​

Step 3. Wait for a webhook with the confirm_information object​

Step 4: Send the confirm_information object to verify payouts​

Step 5. Check the status of the test payment session​