Payout from an escrow account to a bank account

This scenario describes the way to send a payout from an escrow 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 sending payouts to legal entities and individuals, including the self-employed individuals. All the API parameters are passed unencrypted.

You can get a notification every time funds are added to your escrow account as a result of any internal or bank-to-bank transaction (but not in case of a refund). To enable this functionality, give your Bank manager an address to which you would like to receive such notifications. Using the nominal_topup webhook you will be able to get information on your escrow account replenishments and its current balance without having to log in to online banking and check the account state.

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 via session/init/payout/nominal.

Parameters

For residents
For non-residents

Name	Mandatory	Type	Description
payment_method	+	object	Payment details
type	+	string	Value: `bank_account`
bank_account	+	object	Bank account
system_type	+	string	Bank transfer system. Always: `ru`
ru	+	object	Bank account object
bik	+	string	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	- (mandatory for payouts to individual proprietors and legal entities)	string	INN
kpp	- (mandatory for payouts to legal entities)	string	The recipient's Tax Registration Reason Code (KPP)
description	+	string	The purpose of the payout. Reference information
participant_details	+	object	Information on payout participants
sender	+	object	Sender's details
account	+	string	Bank escrow account to send the payout from
beneficiary_id	+	string	Beneficiary's INN
recipient	+	object	Recipient's details
beneficiary_id	+	string	Beneficiary's INN. Not applicable for FPS (SBP) transactions
amount_details	+	object	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	Mandatory	Type	Description
payment_method	+	object	Payment details
type	+	string	Value: `bank_account`
bank_account	+	object	Bank account
system_type	+	string	Bank transfer system. Always: `ru`
ru	+	object	Bank account object
bik	+	string	Recipient's bank BIC
inn	- (mandatory for payouts to individual proprietors and legal entities)	string	The recipient's INN
kpp	- (mandatory for payouts to legal entities)	string	The recipient's Tax Registration Reason Code (KPP)
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>`. 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	+	object	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	+	object	Information on payout participants
sender	+	object	Sender's details
full_name	- (mandatory if the sender is an individual)	string	Name
company_name	- (mandatory if the sender is a legal entity)	string	Company name
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	+	object	Recipient's details
full_name	+	string	Recipient's full name

How to specify the beneficiary's details

Sending payouts from an escrow account requires you to specify the beneficiary's details, namely, the beneficiary's INN. You should pass the beneficiary's INN within the participant_details object as the sender's or recipient's details, depending on their role in the transaction. Before you send any payout from an escrow account, you should provide the list of your beneficiaries to your manager in Bank 131.

How to set out the payout purpose

In the payout purpose field (bank_account.ru.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.

Payout purpose example

For residents
For non-residents

Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt

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

Request example

To individuals
To legal entities

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-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": "John Doe",
        "description": "Wire by the agreement Ivan Ivanovich Test VAT exempt"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient": {
      "beneficiary_id": "1234567890"
    }
  }
}'

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-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": "Wire by the agreement VAT exempt"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient": {
      "beneficiary_id": "1234567890"
    }
  }
}'

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

Bank 131 will send you the ready_to_confirm (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.

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_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 session/confirm or cancel it using session/cancel. If you choose to confirm sending the payout, note that confirm_information is mandatory in the 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_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's name",
        "bank_name": "Bank 131",
        "bik": "049205131",
        "correspondent_account_number": "30101810822029205131"
      }
    }
  }
}'   

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_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's 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

A payout you sent to an account in a bank in the Russian Federation may be refunded. Refunds are carried out within 5 days.

If you enabled our webhooks, in case of a refund you will receive a payment_refunded webhook. If our webhooks are disabled, you can find out if an amount was refunded as follows:

using the session/status request
analyzing the payouts report

Testing payouts

You can test payouts made from your escrow 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 session/confirm 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.

Creating a session

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "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".

Request example

curl -X GET \
https://demo.bank131.ru/api/v1/session/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "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.

Webhook example

{
  "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 session/confirm request.

Request example

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_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 the session.action object with data about all the operations (within this test session).

Request example

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

Accounts eligible to receive payouts​

Step 1. Start the transaction​

Parameters​

How to specify the beneficiary's details​

How to set out the payout purpose​

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

Step 3. Confirm or cancel the payout​

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​

Accounts eligible to receive payouts

Step 1. Start the transaction

Parameters

How to specify the beneficiary's details

How to set out the payout purpose

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

Step 3. Confirm or cancel the payout

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