Payout from a settlement account
Using a settlement account, you can send payouts to bank cards issued by Russian Federation banks and also to bank accounts of the banks of Russian Federation.
Payout to a bank card
This scenario describes how to make a payout from a settlement account to a bank card. The payout consists of two transactions, first, the payment amount itself, and second, the payment commission. Details of both transactions are presented in the appropriate bank statement which can be accessible via the online bank.
You can obtain tokenized card details using the tokenization widget, and then send the payout securely.
Step 1. Generate a public token
The token is needed to work with the widget. Send a request to create a token
, and use it to pass the type of widget you want to work with. You will receive the token in response.
Request example
curl -X POST \
http://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '{
"tokenize_widget": {
"access": true
}
}'
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()
->issuePublicTokenBuilder()
->setTokenizeWidget()
->build();
$response = $client->widget()->issuePublicToken($request);
$publicToken = $response->getPublicToken();
Step 2. Show the details collection form to the recipient
To do this, you will need to access our JavaScript library and add the tokenization widget to the page, where the recipient will then be able to fill in the form with their card details.
The recipient then enters their card details, and you'll receive tokenized details that you can use to perform the payout.
You can initialize the widget using the token you have obtained at the previous step.
Step 3. Start the payout
Send a request for payment session creation session/multi/create/rko
,
then a separate request for payout creation using this session's identifier session/multi/start/payment/rko
.
In the EncryptedCard
object, pass the tokenized bank card details obtained from the widget.
You can find information about the token or card through the method
token/info
. This includes receiving the last 4 numbers of the card, in order to show the user the payment destination.
If you are sending money to a Russian bank card, you will need the following:
- card number;
- recipient's name;
- amount in ruble decimal format (e.g. if you are paying 100 rubles, you will need to pass
10000
in theamount_details.amount
field).
View the parameters for payouts to Russian cards
Request examples
Create session
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/create/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d {
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_bank_account",
"transfer_from_bank_account": {
"description": "Purpose of payout"
}
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "****************"
}
}
},
"participant_details": {
"sender": {
"full_name": "Sender's details"
},
"recipient": {
"full_name": "Ivan Ivanovich Ivanov"
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"customer": {
"reference": "123456789012"
}
}
Payout start
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff' \
-d '{
"session_id": "3230",
"metadata": "good"
}'
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.
ready_to_confirm
webhook
Example of the curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"session": {
"id": "ps_14667043",
"status": "in_progress",
"created_at": "2022-09-14T09:32:19.891392Z",
"updated_at": "2022-09-14T09:32:20.494410Z",
"payments": [
{
"id": "po_7639847",
"status": "pending",
"created_at": "2022-09-14T09:32:20.100149Z",
"customer": {
"reference": "123456789012"
},
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"amounts": {
"net": {
"amount": 293400,
"currency": "RUB"
},
"gross": {
"amount": 293400,
"currency": "RUB"
}
},
"participant_details": {
"sender": {
"full_name": "Acme"
},
"recipient": {
"full_name": "Ivan Ivanovich Ivanov"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_6933973",
"status": "pending",
"created_at": "2022-09-14T09:32:20.099952Z",
"customer": {
"reference": "123456789012"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_bank_account",
"transfer_from_bank_account": {
"description": "Payout by the agreement",
"card_mask": "553691******8371"
}
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"amounts": {
"net": {
"amount": 293400,
"currency": "RUB"
},
"gross": {
"amount": 293400,
"currency": "RUB"
}
},
"participant_details": {
"sender": {
"full_name": "Acme"
},
"recipient": {
"full_name": "Ivan Ivanovich Ivanov"
}
}
}
],
"next_action": "confirm"
},
"confirm_information": {
"transfer_details": {
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"customer": {
"account_number": "40702810700200000000",
"name": "Company name",
"bank_name": "Bank 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"recipient": {
"account_number": "30233810000000000000",
"name": "ООО Банк 131",
"bank_name": "ООО Банк 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"purpose": "Payout by the agreement",
"amount": {
"amount": 293400,
"currency": "RUB"
}
}
}
},
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.
confirm_request
Example of 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": "ps_14667043",
"confirm_information": {
"transfer_details": {
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"customer": {
"account_number": "40702810700200000000",
"name": "Company name",
"bank_name": "Bank 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"recipient": {
"account_number": "30233810000000000000",
"name": "Bank 131",
"bank_name": "Bank 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"purpose": "Payout by the agreement",
"amount": {
"amount": 293400,
"currency": "RUB"
}
}
}
}'
cancel_request
Example of 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": "ps_14667043",
"confirm_information": {
"transfer_details": {
"payment_method": {
"type": "card",
"card": {
"brand": "mastercard",
"last4": "8371",
"country_iso3": "RUS"
}
},
"customer": {
"account_number": "40702810700200000000",
"name": "Company name",
"bank_name": "Bank 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"recipient": {
"account_number": "30233810000000000000",
"name": "Bank 131",
"bank_name": "Bank 131",
"bik": "049205131",
"correspondent_account_number": "30101810822000000000"
},
"purpose": "Payout by the agreement",
"amount": {
"amount": 293400,
"currency": "RUB"
}
}
}
} '
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 has been successful. If the status is failed
, then the payout has not been completed because of an error.
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
}
Payout 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 payount 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 sesssion and starts the payout using session/init/payout/rko
.
Mandatory parameters for Russian 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 the payouts to the individual proprietors 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 copecks. The value must be greater than 0. When sending 100 rubles, specify 10000 . |
currency | string | Currency code by ISO 4217. Case insensitive. Always: rub |
Mandatory parameters 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 |
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 the payouts to the 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 copecks. The value must be greater than 0. When sending 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 payout purpose should not contain the following characters:
?
,!
. The maximum length is 210 characters.
#### An example of a payout purpose
Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt
An example of a payout purpose for non-residents of the Russian Federation
{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt
An example of a request for a payout to an individual
https://demo.bank131.ru/api/v1/session/init/payout/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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
https://demo.bank131.ru/api/v1/session/init/payout/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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 the mandatory 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.
ready_to_confirm
webhook
Example of the curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-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 confirm_information is mandatory in the request.
confirm_request
Example of 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": "ps_1048967",
"confirm_information":{
"account_details": {
"sender": {
"account_number": "40702810300200000013",
"name": "Merchant 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"
}
}
}
}'
cancel_request
Example of 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": "ps_1048967",
"confirm_information":{
"account_details": {
"sender": {
"account_number": "40702810300200000013",
"name": "Merchant 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 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.
succeeded
— indicates a successful payout.
failed
— indicates an error. Refer here for details.
Refer here for details about payout status.
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.