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 the amount_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.

Example of the ready_to_confirm webhook

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.

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: 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"
            }
        }
    }
}'

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: 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.

More about payout statuses.

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

NameTypeDescription
payment_methodPaymentMethodPayment details
typestringvalue: bank_account
bank_accountBankAccountPaymentMethodBank account
system_typestringBank transfer system. Always: ru
ruBankAccountRUBank account object
bikstringRecipient's bank BIC
accountstringRecipient's bank account
full_namestringThe 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>.
innstringINN. Mandatory for the payouts to individual proprietors.
kppstringThe recipient's Tax Registration Reason Code (KPP) Mandatory for the payouts to the individual proprietors legal entities' accounts.
descriptionstringThe purpose of the payout, Reference information
participant_detailsParticipantDetailsInformation on payout participants
senderParticipantSender's details
accountstringSettlement account to send payout from.
recipientParticipantRecipient's details
amount_detailsAmountDetailsAmount
amountintAmount in copecks. The value must be greater than 0. When sending 100 rubles, specify 10000.
currencystringCurrency code by ISO 4217. Case insensitive. Always: rub

Mandatory parameters for non-residents

NameTypeDescription
payment_methodPaymentMethodPayment details
typestringvalue: bank_account
bank_accountBankAccountPaymentMethodBank account
system_typestringBank transfer system. Always: ru
ruBankAccountRUBank account object
bikstringRecipient's bank BIC
innstringThe recipient's INN, 10 digits for legal entities, 12 digits for individuals. Mandatory for the payouts to the legal entities' accounts
kppstringThe recipient's Tax Registration Reason Code (KPP) Mandatory for the payouts to the legal entities' accounts.
accountstringRecipient'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.
descriptionstringThe purpose of the payout, accompanied by the monetary transaction code (as agreed with a Bank 131 manager). How to set this out
amount_detailsAmountDetailsAmount details
amountintAmount in copecks. The value must be greater than 0. When sending 100 rubles, specify 10000
currencystringCurrency code by ISO 4217. Case insensitive. Always: rub
participant_detailsParticipantDetailsInformation on payout participants
senderParticipantSender's details
full_namestringName. Mandatory if the sender is an individual.
company_namestringCompany name. Mandatory if the sender is a legal entity.
address_linestringAddress. Important: a city and country should be specified in the following fields, do not duplicate them here.
country_iso3stringCountry code (ISO-3166-1 alpha-3)
citystringThe city
recipientParticipantRecipient's details
full_namestringRecipient'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.

Example of the ready_to_confirm webhook

  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.

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: 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"
            }
        }
    }
}'

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: 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.

← Payout to a card via widgetPayout from an escrow account →