# Bank 131 API > Bank 131 API provides everything you need for payments, payouts, and settlement between people and companies online. Base URL: `https://demo.bank131.ru` (demo) / `https://proxy.bank131.ru` (live). Sign every request body with RSA-SHA256 and send Base64 signature in `X-PARTNER-SIGN` header. Include `X-PARTNER-PROJECT` in every request. ## Getting Started - [Bank 131 API](https://developer.131.ru/en/): API for Internet platforms offering various online services [Bank 131](https://131.ru/en/) API provides everything you need for payments, payouts, and settlement between people and companies online. :::tip[AI-friendly] We now provide [llms.txt](/llms.txt) and [llms-full.txt](https://developer.131.ru/llms-full.txt) to enable seamless integration with AI-powered tools and agents. — llms.txt gives a compact overview of the site structure and key sections, allowing AI models to quickly grasp the context. — llms-full.txt contains a comprehensive plain-text export of all relevant content across the project. It is designed for use cases that require full-context analysis, such as semantic search, summarization, or code generation based on the complete knowledge base. You can now reference these files directly in your AI tools, eliminating the need to manually scrape or copy-paste content for each query. ::: --- - [API features](https://developer.131.ru/en/intro): API for Internet platforms providing various online services Bank 131 enables participants of online platforms to easily and securely accept payments, send payouts, make transfers, and pay VAT (the so-called Google tax). Only transactions in fiat currencies are supported (cryptocurrency transactions are not supported). #### Platform examples - Online foreign language courses - Online stores and marketplaces - Accommodation rental services - Donation and charity platforms - Food delivery services - Taxi and transportation service platforms - Courier settlement systems Bank 131 cooperates with sole proprietors and legal entities—both Russian and foreign, including small businesses and financial organizations. ### Payouts The table below shows who and which way can receive payouts. ###### Residents of the Russian Federation | Recipient | Bank account | Bank card | YooMoney wallet |       FPS       | |-----------------------|:------------------:|:---------------------:|:----------------:|:----------------------------------------------------------------:| | Individuals | + | + | + | + | | Sole proprietors | + | + | - | + | | Self-employed persons | + | + | + | + | | Legal entities | + (from an escrow/settlement account only) | + (no guarantee) | - | - | ###### Non-residents of the Russian Federation | Recipient | Bank account | Bank card | YooMoney wallet |       FPS       | |-----------------------|:------------------:|:---------------------:|:----------------:|:----------------------------------------------------------------:| | Individuals | + | + | + | + | | Sole proprietors | + | + | - | + | | Self-employed persons | + | + | + | + | | Legal entities | + | + (no guarantee) | - | - | [Learn more about payouts >](/payouts/payouts-intro) ### Payment processing With our API you can do the following: - accepts payments from individuals paying from their bank cards - process delayed capture payments - accept recurring payments [Learn more about accepting payments >](/payments/payment-intro) ### VAT payment Foreign companies providing electronic services to users in Russia can pay the VAT (the Google tax). [Learn more about VAT payments >](/payouts/payout-taxes) Bulk transactions are not supported. Each request processes a single transaction to a single recipient. --- - [Where to begin](https://developer.131.ru/en/before): How to test and perform real operations ## Do testing (without real data) 1. Submit an API integration request on [Bank 131's website](https://www.131.ru/en). A Bank 131 manager will contact you, help you gain access, and answer your questions. 2. Issue a [secret key and a public key](/reference/reference-format.mdx#request-signature). These keys are intended for test requests only. Performing operations with real data will require different keys. 3. Share your public key with the Bank and get the Bank's public key. 4. If you want to get [webhooks](/reference/webhooks) from the Bank, provide your account manager with a URL at which you would like to receive them. Upon completing these steps, you will receive a test project identifier—a unique code assigned by the Bank to your business for API authentication. This identifier is required for all requests. For example, it allows the Bank to determine the origin of a payment. ## Go live :::warning Important! All organizations that process, transmit, or store payment card data, as well as those that do not process, transmit, or store such data directly but are able to impact card data security, are required to comply with the Payment Card Industry Data Security Standard (PCI DSS). The scope of requirements depends on the payout or payment method. Using the widget of Bank 131 reduces the number of applicable requirements. For more information, please visit the [official NSPK website](https://www.nspk.ru/cards-mir/security). ::: Before starting to work with live data, ensure that all operations in the test mode are completed without errors. 1. Complete your legal entity KYC procedure with Bank 131 and sign an agreement. 2. Open and top up the required accounts: - a settlement account–for payouts and payments, including via the Faster Payments System (FPS) - an escrow account–for intermediary payments made on behalf of other parties, including via the Faster Payments System (FPS) - a collateral account–for payouts and payments, except for the Faster Payments System (FPS) 3. Issue a [secret key and a public key](/reference/reference-format.mdx#request-signature) for operations with real data. 4. Share your public key with the Bank and get the Bank's public key. 5. Join the Electronic Document Workflow (see the [rules](/assets/general/electronic_workflow_rules_en.pdf)). Specify your public key in the [Certificate of recognition of the electronic signature verification key](/assets/online/bank131_remote_banking_service_rules.pdf). :::note For webhooks, you can use the same URL address you used for testing or you can provide your account manager with another one. ::: After everything is set up for you, you will get a project identifier for performing live transactions. :::info Bank 131 notifies about planned technical works and maintenance windows via email to the address specified in the contract or when registering a project. ::: --- - [API request format](https://developer.131.ru/en/reference/format): All about working with Bank 131 API Bank 131 API uses the JSON format for data exchange. Communication is handled via HTTP requests and responses using the POST and GET methods. ## API version Currently, Bank 131 supports two API versions for certain methods. Some object names vary depending on the version. :::info Using incorrect object names may result in failed operations. ::: | API v1 | API v2 | |----------------------|----------------------| | `payment_method` | **`payout_details`** | | `payments` | **`payout_list`** | | `acquiring_payments` | **`payment_list`** | Methods supported in API v2 - [`session/create`](/reference/methods#sessioncreate) - [`session/init/payout`](/reference/methods#sessioninitpayout) - [`session/init/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/start/payout`](/reference/methods#sessionstartpayout) - [`session/start/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/init/payment`](/reference/methods#sessioninitpayment) - [`session/init/payment/sync`](/reference/methods#sessioninitpaymentsync) - [`session/start/payment`](/reference/methods#sessionstartpayment) - [`session/confirm`](/reference/methods#sessionconfirm) - [`session/capture`](/reference/methods#sessioncapture) - [`session/cancel`](/reference/methods#sessioncancel) - [`session/refund`](/reference/methods#sessionrefund) - [`fps/customer_verification`](/reference/methods#fps_verification) - [`session/status`](/reference/methods#sessionstatus) - [`session/init/payout/nominal`](/reference/methods#payout-nominal) - [`session/multi/create/nominal`](/reference/methods#sessionmulticreatenominal) - [`session/multi/init/payment/nominal`](/reference/methods#sessionmultiinitpaymentnominal) - [`session/multi/start/payment/nominal`](/reference/methods#sessionmultistartpaymentnominal) - [`session/init/payout/rko`](/reference/methods#payout-rko) - [`session/multi/create/rko`](/reference/methods#sessionmulticreaterko) - [`session/multi/start/payment/rko`](/reference/methods#sessionmultistartpaymentrko) ## Endpoint #### How to set this out ` + /api/v{API version number} + ` #### Server address For demo testing: `https://demo.bank131.ru` For live transactions: `https://proxy.bank131.ru` Example: **API v1**: `https://demo.bank131.ru/api/v1/session/init/payout` **API v2**: `https://demo.bank131.ru/api/v2/session/init/payout` ## API authentication Each time you send a request, you must provide your project identifier and the request signature. This allows the Bank to identify you and verify that the request originated from you. | Name | Mandatory | Type | Description | |-------------------------|--------------------------------------------------------------------------------------------|--------|-----------------------------------------------------------| | `X-PARTNER-PROJECT` | \+ | string | Project identifier. Given to you by your Bank 131 manager | | `X-PARTNER-SIGN` | \+ | string | [Request signature](#request-signature) | | `X-PARTNER-SUBMERCHANT` | \- (mandatory for financial institutions that are non-residents of the Russian Federation) | string | Payer's identifier (for legal entities) | Request example with authentication ```json showLineNumbers 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 '{ // request body }' ``` ### Request signature A signature is required to verify that a request originated from you and not from someone else, and that it was not modified in transit. Two keys are needed for signature verification: a public key (shared with the Bank in the [Certificate of recognition of the electronic signature verification key](/assets/online/bank131_remote_banking_service_rules.pdf)) and a private key (stored securely on your side). The Bank uses the public key to validate requests. The private key is used to sign your requests and must never be disclosed to anyone. You need to generate these two keys using the RSA algorithm. #### Creating request body signature The entire request body must be signed exactly as it is sent to the Bank (i.e., the full text in JSON format). Your private key is required to create the signature. The signature is generated using the SHA-256 encryption method. After creation, the signature must be encoded into Base64 format so it can be transmitted with the request. #### Verifying incoming requests from Bank 131 All outgoing requests from Bank 131 are signed using its secret key. To ensure a request is genuinely from the Bank, you must verify this signature. You use the Bank's public key and the SHA-256 algorithm to perform this verification. The signature is transmitted in Base64 format. Save Bank 131's public key in the PEM format: - For live testing - For demo testing Signature generation and validation examples ```openssl showLineNumbers # Generating the private key $ openssl genrsa -out private.pem 2048 # Generating the public key based on the private key $ openssl rsa -in private.pem -pubout > public.pem # Creating the myfile.txt file contents $ echo test > myfile.txt # Generating the signature $ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt # Signature ready for transfer $ base64 sha256.sign # Checking the signature $ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt Verified OK ``` ```php showLineNumbers $data = "test"; //Obtaining the pointer to the private and public keys $privateKey = openssl_pkey_get_private("file://private.pem"); $publicKey = openssl_pkey_get_public("file://public.pem"); //Generating the signature based on the data using the private key openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); //Encoding the signature into Base64 to transmit it $base64Signature = base64_encode($signature); //On receiving the signature, decoding it from Base64 $decodedSignature = base64_decode($base64Signature); //Validating the received signature using the public key (success = 1) $isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256); ``` ## Idempotency key An idempotency key is a unique code that you generate for each operation to prevent the same operation from being executed multiple times. For example, you sent a payment request, but due to a slow internet connection, you are unsure if it went through. If you send the request again, the funds might be debited twice. To avoid this, use an idempotency key. You generate the key yourself and send it with the request. The Bank stores this key and, if a request with the same key arrives within 24 hours, the Bank will recognize it as a duplicate request and will not perform the operation again. The idempotency key identifier is specified in the request header. | Name | Mandatory | Type | Description | | ----------------- | -------------- | ------ | ---------------------------------------------------- | | `X-PARTNER-IDEMPOTENCY-KEY` | - | string | Idempotency key (from 4 to 64 characters) | Example of a request with an idempotency key ```json showLineNumbers 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' \ -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \ -d '{ // request body }' ``` Methods supporting the idempotency key feature - [`session/create`](/reference/methods#sessioncreate) - [`session/init/payout`](/reference/methods#sessioninitpayout) - [`session/init/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/start/payout`](/reference/methods#sessionstartpayout) - [`session/start/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/init/payment`](/reference/methods#sessioninitpayment) - [`session/init/payment/sync`](/reference/methods#sessioninitpaymentsync) - [`session/start/payment`](/reference/methods#sessionstartpayment) - [`session/confirm`](/reference/methods#sessionconfirm) - [`session/capture`](/reference/methods#sessioncapture) - [`session/cancel`](/reference/methods#sessioncancel) - [`session/refund`](/reference/methods#sessionrefund) #### Errors Below is a list of common errors that may occur when using the key: - `idempotency_key_params_mismatch` — The key has already been used for another session - `idempotency_key_already_exists` — The previous request with the same key is still in progress - `idempotency_key_not_supported` — This method cannot be used with an idempotency key [View error codes >](/reference/errors) ## Libraries You can use the [PHP SDK](https://github.com/bank131/php-sdk) library to integrate with Bank 131 API. Native SDKs for iOS and Android are not provided. --- - [API testing](https://developer.131.ru/en/reference/testing): Data for test operations Before performing operations with real data, test the integration with Bank 131 on the demo server: `https://demo.bank131.ru`. This allows you to try out different payment and payout scenarios and check error handling through the use of special test values. To do this, [obtain your test project identifier](/before) and download Bank 131's public key for testing in the PEM format The rules for forming and sending requests on the test server are the same as when working with actual data. IP addresses our webhooks arrive from during testing: `89.169.172.243` and `158.160.169.64`. :::warning Do not use `localhost` or `127.0.0.1` as the value of the `return_url` parameter of the [`payment_options`](/reference/objects#payment_options) object—requests with these values will not be processed. ::: ### Bank cards for test operations Use both cards with 3D Secure support and without it. :::info You can create any tokens for test cards. ::: Cards with 3D Secure support: | Card number | Payment system | Country | |------------------|----------------|-------------| | 2200774546102058 | Mir | Russia | | 4000000000000002 | Visa | USA | | 5500000000000004 | MasterCard | North Korea | To go successfully through 3D Secure, specify: `12345`. Cards without 3D Secure support: | Card number | Payment system | Country | |------------------|----------------|----------------| | 4242424242424242 | Visa | United Kingdom | | 5101180000000007 | MasterCard | Turkey | ### YooMoney wallet for test operations Use any wallet number containing 11–12 digits. ### Bank account for test operations Use any account number containing 20 digits. ## Testing unsuccessful operations To test errors at various stages of payment and payout processing, pass one of the following values in the `customer.reference` field of the `customer` object. | Value | Result | |---------|--------------------------------------------------------------------------------------------------------------------------------| | `thief` | For payments only. The payment will be canceled when money is put on hold | | `loser` | For payments and payouts. The payment will be canceled when the funds on hold are debited; the payment will result in an error | --- - [Standard payout and payment scenarios](https://developer.131.ru/en/reference/typical): Standard payout and payment scenarios The information below will help you understand how to generally perform payouts and payments via API. It includes the main steps, but depending on the selected transaction method or conditions you might need to complete additional actions. Find the detailed scenarios for each particular case in the [Payouts](/payouts/payouts-intro) and [Payments](/payments/payment-intro) sections, respectively. :::info When working with bank cards, you have to comply with the PCI DSS standard, but the scope of the requirements depends on the way you perform a payout or a payment. If you use Bank 131 widget, you will have to comply with fewer requirements. ::: You can decide whether you want to get [webhooks](/reference/webhooks). If they are disabled, you will have to send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request each time to understand the next step and transaction results. The steps depend on whether or not you use our widget. 1. Send a [token](/reference/methods#token) request to get a public token. The token is used to initialize the widget. 2. [Initialize the widget](/payouts/tokenize-widget) using the received token. >Save the hash for future payouts. 3. Start the payout in one of the following ways: - send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request and then a [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) request with the session identifier and payout details—the recommended option - start a session and the payout simultaneously ([`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)) 4. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from the Bank, indicating that it is ready to perform the payout and is waiting for your confirmation. 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout. >To enable automatic confirmation, contact you manager at Bank 131. 6. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook with the payout results. If the status is `succeeded`, the payout was successful. 1. Start the payout in one of the following ways: - send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request and then a [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) request with the session identifier and payout details—the recommended option - start a session and the payout simultaneously ([`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)) 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from the Bank, indicating that it is ready to perform the payout and is waiting for your confirmation. 3. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout. >To enable automatic confirmation, contact you manager at Bank 131. 4. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook with the payout results. If the status is `succeeded`, the payout was successful. The steps depend on whether or not you use our widget. 1. Create a payment session with a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request. In the response you will get the session identifier. 2. Send a [token](/reference/methods#token) request to get a public token. The token is used to initialize the widget. 3. [Initialize the widget](/payments/payment-widget) using the received token. 4. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from the Bank, indicating that it is ready to perform the payment and is waiting for your confirmation. 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. >To enable automatic confirmation, contact you manager at Bank 131. 6. Wait for a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook. It means the required amount is held on the bank card successfully. Capture the full amount or a part of it ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)), or cancel the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). >Skip this step if [delayed capture payments](/payments/payment-hold) are not enabled for you. In this case, the funds will be put on hold and captured automatically. 7. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook with the payment results. If the status is `succeeded`, the payment was successful. 1. Start the payment in one of the following ways: - send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request and then a [`session/start/payment`](/reference/methods#sessionstartpayment) request with the session identifier and payment details—the recommended option - start a session and the payment simultaneously ([`session/init/payment`](/reference/methods#sessioninitpayment)) 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from the Bank, indicating that it is ready to perform the payment and is waiting for your confirmation. 3. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. >To enable automatic confirmation, contact you manager at Bank 131. 4. If you get an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook from Bank 131, this means that you will need to take an additional action to perform the payment. For instance, the payer might need to go through 3D Secure. Send the HTTP 200 OK code in response and redirect the payer to the address for 3D Secure. 5. Wait for a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook. It means the required amount is held on the bank card successfully. Capture the full amount or a part of it ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)), or cancel the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). >Skip this step if [delayed capture payments](/payments/payment-hold) are not enabled for you. In this case, the funds will be put on hold and captured automatically. 6. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook with the payment results. If the status is `succeeded`, the payment was successful. --- - [Configuring trust for certificates of the Russian Ministry of Digital Development for working with Bank 131 services](https://developer.131.ru/en/reference/certificates): Installation of Russian Ministry of Digital Development certificates To ensure your system can connect to Bank 131 services over a secure TLS channel, it needs to trust the Russian certificate authorities that issue our certificates. If the required root certificates are missing from your operating system or application software's trusted certificate store, the certificate chain validation will fail, and the connection cannot be established. :::note[Attention] Install the Russian Trusted CA certificates in advance—this will reduce the risk of disruptions when working with our services and ensure stable integration. ::: ## Main steps 1. [Get](#get_certificate) the current certificates from the National Certification Center of the Russian Ministry of Digital Development (Russian Trusted CA). 2. [Install](#import_certificate) the root and intermediate Russian Trusted CA certificates into the trusted certificate store of your operating system or software platform. 3. [Verify](#check_certificate) that the integration is working properly. ### Getting the certificates Current certificates and official instructions are available on the Gosuslugi portal: `https://www.gosuslugi.ru/crt`. Install two certificates: * **Russian Trusted Root CA** — root certificate * **Russian Trusted Sub CA** — intermediate certificate ### Installing the certificates 1. Download the Russian Trusted CA certificates. 2. Double-click the certificate file to open it. 3. Select **Install Certificate**. 4. Launch the Certificate Import Wizard. 5. Place the certificate in the **Trusted Root Certification Authorities** store. 6. Complete the import and confirm the installation. 7. Restart the applications and browsers you are using. For Debian/Ubuntu-based systems, run the following commands: ```json sudo cp russian_trusted_root_ca.pem /usr/local/share/ca-certificates/russian_trusted_root_ca.crt sudo cp russian_trusted_sub_ca.pem /usr/local/share/ca-certificates/russian_trusted_sub_ca.crt sudo update-ca-certificates ``` For RHEL/CentOS-based systems: ```json sudo cp russian_trusted_*.pem /etc/pki/ca-trust/source/anchors/ sudo update-ca-trust ``` After updating the certificate store, restart your application services. If your integration runs on Java, you may need to additionally import the certificates into the JVM truststore: ```json # Create a separate truststore and import both certificates keytool -importcert -alias russian_trusted_root \ -file russian_trusted_root_ca.pem \ -keystore russian_truststore.jks \ -storepass -noprompt keytool -importcert -alias russian_trusted_sub \ -file russian_trusted_sub_ca.pem \ -keystore russian_truststore.jks \ -storepass -noprompt ``` Specify the truststore when launching the application: ```json showLineNumbers java -Djavax.net.ssl.trustStore=/path/to/russian_truststore.jks \ -Djavax.net.ssl.trustStorePassword= \ -jar app.jar ``` ### Verifying the installation To verify that the trusted certificate chain is available: * send a test request to the Bank 131 API * ensure there are no SSL/TLS errors * check that the application logs do not contain any entries about an untrusted certificate or certificate chain validation errors Possible errors when the required root or intermediate certificates are missing from the trusted store: * `certificate verify failed` * `unable to get local issuer certificate` * `certificate chain validation error` * `SSL handshake failed` --- ## Payouts - [Collateral account API](https://developer.131.ru/en/payouts/collateral-intro): Details on operations with a collateral account in Bank 131 From a collateral account, you can make payouts to cards and accounts at Russian banks, as well as to YooMoney wallets. You deposit funds to your account in advance, and Bank 131 debits the funds and transfers them to the recipients. Bank 131 only processes payouts if there are sufficient funds in the collateral account to cover both the transfer amount and the fee. Therefore, you should regularly check the account balance. If you plan to make payouts via the Faster Payments System (FPS), you will need to open a [settlement account](/settlement-account/settlement-intro) or [an escrow account](/escrow-account/escrow-intro). ### Features - Payouts: - to bank cards ([by card number](/payouts/payout-pcidss), [with our widget or by token](/payouts/payout-tokenized-card)) and to Russian bank accounts ([by account number](/payouts/russian-account), [with our widget or by token](/payouts/payout-tokenized-account)) - [to YooMoney wallets](/payouts/yoomoney) - [to the FTS](/payouts/payout-taxes) - Balance info. Check your collateral account balance using the [`wallet/balance`](/reference/methods#walletbalance) method. ### Accounts for payouts Accounts allowed for payouts from collateral accounts --- - [Monthly reports](https://developer.131.ru/en/payouts/finance-act): Via email, EDM, or on paper --- - [Single-request payouts by account number](https://developer.131.ru/en/payouts/payout-account-simple): Save time on creating and performing payouts You can send a payout by account number within a single request. The system automatically handles data transfer and confirms payouts without any intermediate steps. To enable singe-request payouts, contact your Bank 131 account manager. Once this option is enabled, all your payouts will be processed this way. To disable it, contact your account manager again. ### Step 1. Create a session along with a payout Send a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request, specifying [the parameters for payouts](/payouts/russian-account-parameters). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Перевод средств по договору № 5015553111 Иванов Иван Иванович НДС не облагается" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\BankAccount\BankAccountRu; $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() ->initPayoutSession() ->setBankAccount( new BankAccountRu( '044525971', '40817810100000270411', 'Иванов Иван Иванович', 'Перевод средств по договору № 5015553111 Иванов Иван Иванович НДС не облагается' ) ) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->initPayout($request); ``` ### Step 2. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds) Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2025-05-27T02:03:00.809901Z", "updated_at": "2025-05-27T02:03:00.360812Z", "payments": [{ "id": "po_2025", // highlight-next-line "status": "succeeded", "created_at": "2025-05-27T02:03:00.204563Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Transfer of funds under agreement N 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` --- - [Speedy payouts to accounts via BESP](https://developer.131.ru/en/payouts/payout-account-sistema-besp): Speedy payouts to accounts via BESP You can send money from your collateral, settlement, or escrow account to bank accounts as speedy payouts through the [BESP system](https://www.banki.ru/wikibank/sistema_besp)—in this case, the money will be credited within an hour. To enable speedy payouts, contact your account manager at Bank 131. The tariffs for speedy payouts are fixed in the agreement with Bank 131. ### Accounts for payouts The accounts you can send payouts to depend on the account you make a payout from: settlement, escrow, or collateral one. Accounts allowed for payouts from settlement/escrow accounts Accounts allowed for payouts from collateral accounts ### Making a speedy payout :::warning If this payout method was not stipulated in your agreement with Bank 131, the transaction will fail with a `routing_internal_error`. In case the recipient's bank is not connected to the BESP system, the payout will be sent as a standard one, but Bank 131 will charge the commission for a speedy payout anyway. ::: [Follow the standard scenario of a payout without our widget](/reference/typical) specifying the parameters required for a payout from a [collateral](/payouts/russian-account-parameters), [settlement](/settlement-account/russian-account-parameters), or [escrow](/escrow-account/russian-account-parameters) account. Make sure you pass `true` in the `is_fast` parameter of the [`ru`](/reference/reference-objects.mdx#ru) object, otherwise a standard payout will be made. #### Object example ```json showLineNumbers { "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt", // highlight-next-line "is_fast": "true" } } } ``` [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds.mdx) --- - [Payouts to cards in a foreign currency](https://developer.131.ru/en/payouts/payout-currency): Payouts in a foreign currency To enable payouts in a foreign currency, sign an agreement with Bank 131. :::warning If you enabled automatic confirmation earlier, disable it to see the amount in rubles to be debited that is returned in a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. To do this, contact your account manager at Bank 131. ::: When sending a request, specify the amount in the required currency. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, // highlight-start "amount_details": { "amount": 10000, "currency": "usd" }, // highlight-end "metadata": "good" }' ``` Bank 131 will convert the amount at the exchange rate specified in your agreement and debit the ruble equivalent from your account. The recipient will receive the payment in Russian rubles. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.346700Z", "updated_at": "2025-05-27T02:03:00.100044Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.568099Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, // highlight-start "amount_details": { "amount": 800000, "currency": "rub" }, // highlight-end "metadata": "good" }] } }' ``` You can make a payout in a foreign currency in one of the following ways: - [by card number](/payouts/payout-pcidss) - [with our widget or by token/hash](/payouts/payout-tokenized-card) --- - [Payouts via FPS to a phone number](https://developer.131.ru/en/payouts/payout-fps-phone): Payouts to individuals' accounts via FPS You can make payouts to an account of an individual by their phone number via the Faster Payment System (FPS) from your settlement or escrow account. To do this, open a settlement account with Bank 131, after which the Bank signs you up to the Faster Payment System. :::info To see an up-to-date list of banks participating in FPS, use our [`fps/banks`](/reference/methods#banks_fps) method. ::: Before making a payout using the new details, check whether the recipient is registered in FPS using the [`fps/customer_verification`](/reference/methods#fps_verification) method. For subsequent payouts using the same details, verification is not required. :::warning Important! FPS payouts cannot be refunded. ::: ### Payout parameters | Name | Mandatory | Type | Description | |-------------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payout data](/reference/reference-objects.mdx#payment_method) | |   `type` | + | string | Value: `bank_account` | |   `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |     `system_type` | + | string | Bank transfer system. Always: `faster_payment_system` | |     `faster_payment_system` | + | object | [FPS data](/reference/reference-objects.mdx#faster_payment_system) | |       `phone` | + | string | Recipient's phone number | |       `bank_id` | + | string | Identifier of the recipient's bank in FPS | |       `description` | + | string | [Payout purpose](#target) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |   `currency` | + | string | Currency code according to ISO 4217. Case insensitive. Always: `rub` | | `participant_details` | - (mandatory for payouts from an escrow account) |object | [Information on the payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender details](/reference/reference-objects.mdx#participant_details_sender) | |       `account` | + | string | Escrow account number from which to make the payout | |   `recipient` | + | object | [Recipient details](/reference/reference-objects.mdx#participant_details_recipient) | |       `beneficiary_id` | + | string | INN of the beneficiary | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:140 characters #### Payout purpose example `Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ## How to perform a payout from the settlement account Use the [payout scenario without our widget](/settlement-account/settlement-payout-accounts) sending the parameters from the table above. Example of an FPS payout from the settlement account ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", // highlight-start "bank_account": { "system_type": "faster_payment_system", "faster_payment_system": { "phone": "79680000000", "bank_id": "100000000069", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } // highlight-end } }, "amount_details": { "amount": 30000, "currency": "rub" }, "metadata": "good" }' ``` ### How to perform a payout from the escrow account :::warning Important! Before making a payout, submit a list of beneficiaries to Bank 131 to [identify them](/escrow-account/verification-intro). ::: Use the [payout scenario without our widget](/escrow-account/escrow-payout-accounts) sending the parameters from the table above. Example of an FPS payout from the escrow account ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", // highlight-start "bank_account": { "system_type": "faster_payment_system", "faster_payment_system": { "phone": "79680000000", "bank_id": "100000000069", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } // highlight-end } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } }, "metadata": "good" }' ``` --- - [About payouts](https://developer.131.ru/en/payouts/payouts-intro): API for convenient and secure payouts You can securely and with ease execute payouts to individuals, legal entities, sole proprietors, and self-employed persons as well as pay [VAT](/payouts/payout-taxes) to the Federal Tax Service. You can make payouts in both Russian rubles and [foreign currency](/payouts/payout-currency). You can send money to: - [bank cards](/payouts/russian-card) (Visa, MasterCard, and Mir) - [Russian bank accounts](/payouts/russian-account) - [YooMoney wallets](/payouts/yoomoney) Also, you can send money by the recipient's phone number [via the FPS](/payouts/payout-fps-phone). :::info Bank 131 provides a [daily payout report](/finance/payouts-daily-report) and a [monthly payout report](/payouts/finance-act). ::: ## Bank accounts Depending on your goals and objectives, you will need one or more accounts: a settlement account, a collateral account, and/or an escrow account. #### Settlement account With a settlement account, you can send payouts to counterparties, disburse salaries, settle taxes, and perform other transactions. You can transfer money to Russian bank cards and accounts, or send it by phone number via the FPS. [Learn more on working with the settlement account >](/settlement-account/settlement-intro) #### Escrow account An escrow account is a special bank account for settlements between transaction participants. The key feature of this account is that the funds in it belong to third parties—the beneficiaries, and not to you as the account holder. These beneficiaries are your clients under contracts. You are authorized to manage the funds on their behalf, but you do not own them. To open an escrow account, you must first have a settlement account. The escrow account is used exclusively for payouts, ensuring a clear separation between your funds and your clients' funds. From your escrow account, you can make payouts to bank cards and Russian bank accounts, including via FPS. Before making any payouts, submit a list of beneficiaries to Bank 131. [Learn more on working with the escrow account >](/escrow-account/escrow-intro) #### Collateral account Use your collateral account if you do not need a settlement account. First you deposit funds to the account in advance, and Bank 131 makes payouts provided there are sufficient funds in the account for the transfer, including the fee. Regularly check the balance of your collateral account using the [`wallet/balance`](/reference/reference-methods.mdx#walletbalance) method. If the balance is low, top it up in advance. You can transfer money to cards and accounts at Russian banks, as well as to YooMoney wallets. [Learn more on working with the collateral account >](/payouts/collateral-intro) ## Processing, transferring, and storing card details Choose how you will process, transfer, and store card details: - On your own. You will need to comply with all the requirements of PCI DSS for this method. You can send payouts: - by card number. You get the number using any convenient method and make a payout. - by a bank card token or hash. - Using Bank 131 widget. It is sufficient to meet PCI DSS requirements to operate this widget. You simply embed the widget on your website, the user enters their card number, and Bank 131 saves it in its system and returns a hash to you for payouts. ## Card identifier A card identifier is necessary to determine which card the recipient is using and to identify cases where multiple recipients are using the same card. The identifier is generated based on the card number and its expiration date if it is available. It is passed in the `card_id` parameter of the [`card`](/reference/objects#card) object. By default, `card_id` is unique for each project but you can choose this value to be the same across all your projects. [Learn more about the project >](/before) :::info A card identifier is not a replacement for a token and cannot be used to make payouts or to retrieve all cards linked to a recipient. ::: To set up the identifier, contact your manager at Bank 131. ## Refunds Funds transfers to accounts in Russian banks may be declined. This can occur, for instance, if the account is blocked. In this case, the money is returned to the sender's account. The refund is carried out within 7 business days. [Learn more about payout refunds >](/payouts/payout-refunds) ## Tariffs and limits The tariffs for payouts are fixed in your agreement with Bank 131. You can discuss them with your manager. The limits vary depending on the payout method. --- - [Single-request payouts by card number](https://developer.131.ru/en/payouts/payout-pcidss-simple): Save time on creating and performing payouts You can send a payout by card number within a single request. The system automatically handles data transfer and confirms payments without any intermediate steps. In this case, you will need to comply with all the requirements of PCI DSS for this method. To enable singe-request payouts, contact your account manager at Bank 131. Once this option is enabled, all your payouts will be processed this way. To disable it, contact your account manager again. ### Step 1. Create a session along with a payout Send a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request, specifying [the parameters for payouts](/payouts/russian-card). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Participant; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $participant = new Participant(); $participant->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->initPayoutSession('3230') ->setCard(new BankCard('2200********4940')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->initPayout($request); ``` ### Step 2. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2025-05-27T02:03:00.303051Z", "updated_at": "2025-05-27T02:03:00.890003Z", "payments": [{ "id": "po_2025", // highlight-next-line "status": "succeeded", "created_at": "2025-05-27T02:03:00.760584Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers 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 } ``` --- - [Payouts by card number](https://developer.131.ru/en/payouts/payout-pcidss): Payouts by card number To make payouts by card number, you will need to comply with all the requirements of PCI DSS for this method. ### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers 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 '{ "metadata": "good" }' ``` ```php showLineNumbers 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() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` ### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-card). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Participant; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $participant = new Participant(); $participant->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->startPayoutSession('3230') ->setCard(new BankCard('2200********4940')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayout($request); ``` ### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.012389Z", "updated_at": "2025-05-27T02:03:00.023504Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.102036Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` ### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/reference-objects.mdx#payout_status) [View error codes >](/reference/errors) Handling the webhook using SDK ```php showLineNumbers 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 } ``` --- - [Refunds of payouts made to accounts](https://developer.131.ru/en/payouts/payout-refunds): Checking the payouts status When transferring money to accounts in Russian banks, the transaction may be rejected. For example, if the recipient's account is blocked. In such cases, the funds are returned to the sender's account. The refund is processed within 7 business days. :::info You cannot cancel or get back a successful payout. You can only negotiate with the recipient to return the funds back to you. ::: You can learn that a payout was returned because of a failed deposit in the following ways: - Bank 131 will send you a [`payment_refunded`](/reference/reference-webhooks.mdx#payment_refunded) webhook with the identifier of the returned payout in the `id` field of the `payments`/`payout_list` array. - If you do not receive webhooks, request the [payment session status](/reference/reference-methods.mdx#sessionstatus). In return you will get the payout details and, if the payout was returned, the refund details. - Check the [payout report](/finance/finance-payouts-daily-report.mdx). The day after the payout is returned, a new entry with the payout details will appear in the report: the `typeOfPayment` parameter will have the `Refund` value. --- - [Parameters for payouts to Russian bank accounts](https://developer.131.ru/en/payouts/russian-account-parameters): Payouts to the self-employed, sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors| |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | |          `is_fast` | - | string | For [speedy payouts](/payouts/payout-account-sistema-besp) (via BESP) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#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` | | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | |          `is_fast` | - | string | For [speedy payouts](/payouts/payout-account-sistema-besp) (via BESP) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#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](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `full_name` | - (mandatory if the sender is an individual) | string | Sender's 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 (ISO-3166-1 alpha-3 | |       `city` | + | string | City | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters #### Payout purpose example `Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ### What next [Payouts by bank account number >](/payouts/russian-account) [Payouts using our widget or by token >](/payouts/payout-tokenized-account) --- - [Payouts by bank account number](https://developer.131.ru/en/payouts/russian-account): Payouts by bank account number You can send money from your collateral account to bank accounts as follows: - [as a standard payout](#payout_account)—the money will be credited within a period from 2 hours to 3 banking days (this depends on the recipient's bank) - [as a speedy payout through the BESP system](https://www.banki.ru/wikibank/sistema_besp)—the money will be credited within an hour ### Making a standard payout #### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/payouts/russian-account-parameters) with open card data and skip the next step. This option is not recommended. Request example ```json showLineNumbers 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 '{ "metadata": "good" }' ``` #### Step 2. Send the payout Send a [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) request, specifying the session identifier alongside the [payout parameters](/payouts/russian-account-parameters). Example of a payout by account number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "{VO99090} Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "sender": { "full_name": "Vector LLC", "address_line": "123 Main Street", "country_iso3": "USA", "city": "New York" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` #### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.456004Z", "updated_at": "2025-05-27T02:03:00.756005Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.355006Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout. Confirming a payout ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Пример с отменой выплаты ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. :::info To get notifications when funds are credited to the recipient's account, enable the [`confirmation_payout`](/reference/webhooks#confirmation_payout) webhook. To do this, contact your account manager at Bank 131. Webhook delivery is not guaranteed by Bank 131, as it depends on the recipient bank. ::: [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds) --- - [Payout parameters for Russian bank cards](https://developer.131.ru/en/payouts/russian-card): Payouts by Visa, MasterCard, and Mir Which parameters to specify depends on how you send data. Below are the mandatory parameters to perform a payout to a Russian bank card by token, hash, or via the Bank 131 widget. | Name | Mandatory | Type | Description | |---------------------------------------------|-------------------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment data](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Values: `encrypted_card` or `tokenized_card` | |       `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Encrypted card details](/reference/reference-objects.mdx#encrypted_card) | |          `number_hash` | + | string | Card number hash | |       `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | |          `token` | + | string | Card number token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | Below are the mandatory parameters to perform a payout to a Russian bank card by its number. | Name | Mandatory | Type | Description | |-----------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, bank account, etc.) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Value: `bank_card` | |       `bank_card` | + | object | [Card details](/reference/reference-objects.mdx#bankcard) | |          `number` | + | string | Card number | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | ### What next [Payouts by card number >](/payouts/payout-pcidss) [Payouts using our widget or by token/hash >](/payouts/payout-tokenized-card) --- - [Main payout scenario](https://developer.131.ru/en/payouts/payout-scenarios): Payouts via API with and without a token ## What kinds of scenarios we have Payouts via API can be performed with or without a token. The choice of a scenario depends on how the payment is received and whether you decided to collect and store bank card details on your side. ### Payout to a bank card with the widget In this case, you cannot store and send the recipient's bank card details with open parameters, which means the payout can only be performed using a token, via the [tokenization widget](/payouts/widget-tokenize.mdx). The widget allows you to obtain the user's card details and pass them along within your request in a secure tokenized form. [How to perform a payout to a bank card using our widget](/payouts/payout-tokenized-card.mdx) > To show the user which bank card will receive the payment, use the [`token/info`](/reference/reference-methods.mdx#token_info) method. It takes the last 4 numbers of the card by its token. ### Payout to a bank card, bank account, via FPS, YooMoney wallet No need to use a token: all the payout parameters can be passed along with open parameters. ## Payment session All API operations are carried out within a payment session ([`session`](/reference/reference-objects.mdx#payment_session)) – payouts, payments, and refunds. You can perform payouts in two ways: - initiate the payout when you start the session (as a single request, [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)) - or create a session and only then perform the payout (making two requests: [`session/create`](/reference/reference-methods.mdx#sessioncreate) and [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout)). For example, to immediately obtain the session identifier and use it to monitor the payout status. ## Main payout scenario >#### These steps are only necessary for payouts with the widget >1. Send a request for token creation to access the JavaScript library. >2. Create the [widget](/payouts/widget-tokenize.mdx) with this token, show it to the user, and obtain the card details in tokenized form. >Tokenized card details can be saved so that you can send money to that card later. 3. Perform the payout however you prefer: - either first create a payment session ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) and then create a payout using this session's identifier ([`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout)) - or create a session and a payout simultaneously ([`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)). In the request for payout creation, you pass the method of receiving the payment and all the parameters mandatory for that method. 1. Make sure Bank 131 is ready to perform a payment and is waiting for your approval. There are two options: - get a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook from Bank 131 - send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request and wait until `confirm` is returned in the `session.next_action` field. 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the operation. 6. Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the result of the payout. If the status is `succeeded`, the payout has been performed successfully. > A payout to a Russian bank account may be refunded within 5 days. In this case, you will receive a `payment_refunded` webhook. [Learn more about payout refunds](/payouts/payout-refunds.mdx) ## Scenario of payouts to self-employed people If you are paying out to self-employed people, the scenario will be slightly different. - Before the start of the payout (at the very beginning), check that the person really is self-employed and is linked to Bank 131. - If the INN belongs to the self-employed person but is not linked to Bank 131, you should immediately link it using the [special linking widget](/payouts/widget-selfemployed.mdx). - If everything is fine, perform the payout following the standard scenario. Along with the payment, send fiscalization details: [`session/init/payout/fiscalization`](/reference/reference-methods.mdx#sessioninitpayoutfiscalization) or [`session/start/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization). [More about payouts to the self-employed](/selfemployed/intro) ## Single-request payout For payouts to bank accounts or to cards, there is a simplified scenario: you send the payout using a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request and obtain the result from a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook or using the [`session/status`](/reference/reference-methods.mdx#sessionstatus) method. [How to perform a single-request payout](/payouts/payout-pcidss-simple.mdx) ## Payout in a foreign currency (other than Russian ruble) The following steps are eligible for payouts in a foreign currency: - Send a request to create a payment session [`session/create`](/reference/reference-methods.mdx#sessioncreate). - Send a request to create a payout using this session identifier [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout). - Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook from Bank 131 to make your payout. For more details on how to perform payouts in a foreign currency, click [here](/payouts/payout-currency.mdx) ## Payout statuses The status of a payout is returned in the `status` field of the [`payments`/`payout_list`](/reference/objects#payout_status) array. To query it, wait for a webhook from Bank 131 or send a [`session/status request`](/reference/reference-methods.mdx#sessionstatus) with the identifier of the session containing this payout. You can choose any of these options or combine them as you wish. --- - [Payouts to the Russian Federal Tax Service](https://developer.131.ru/en/payouts/payout-taxes): Payouts to the Russian Federal Tax Service `Google tax`—is a value-added tax (VAT) for foreign companies that provide electronic services to customers in Russia. To pay it using our API, contact your manager. ### Possible scenarios **With an automatic deduction**. This scenario is for you if you [accept payments](/payments/payment-intro) through Bank 131. Bank 131 automatically withholds the tax amount from each payment. When the payment deadline arrives, the funds are already in your collateral account. **With account top-up**. You top up your collateral account with Bank 131. Then, the Bank executes your orders for payouts to the tax service. >To check the collateral account balance, use the [`wallet/balance`](/reference/reference-methods.mdx#walletbalance) method. ### How to pay the tax To pay the tax, specify the following bank details: ``` BIC: 017003983  Treasury Account: 03100643000000018500  Treasury Single Account: 40102810445370000059  Recipient: Federal Treasury of Russia (Federal Tax Service of Russia) INN: 7727406020  KPP: 770801001 KBK: 18201061201010000510 ``` Send a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request with a minimal or [extended](#parameters_full) set of parameters, when you need to specify additional details (for example, KBK, OKTMO, period, etc.). #### Payout with a minimal set of parameters **Request parameters** | Name | Mandatory | Type | Description | |-------------------------------------|-----------|--------|--------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | array | [Payout data](/reference/reference-objects.mdx#payment_method) | |   `type` | + | string | Value: `tax` | |   `tax` | + | object | [Data for making a VAT payout](/reference/reference-objects.mdx#tax) | |     `type` | + | string | Payout method. Always: `tax_short` | |     `tax_details` | + | object | [Tax details](/reference/reference-objects.mdx#tax_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 20000, "currency": "rub" }, "payment_method": { "type": "tax", "tax": { // highlight-next-line "type": "tax_short", "tax_details": {} } } }' ``` #### Payout with an extended set of parameters **Request parameters** | Name | Mandatory | Type | Description | |-----------------------------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | array | [Payout data](/reference/reference-objects.mdx#payment_method) | |   `type` | + | string | Value: `tax` | |   `tax` | + | object | [Data for making a VAT payout](/reference/reference-objects.mdx#tax) | |     `type` | + | string | Payout method. Always: `tax_full` | |     `uin` | + | string | UIN. Always: `0` | |     `description` | + | string | [Payout purpose](#target) | |     `tax_details` | + | object | [Tax details](/reference/reference-objects.mdx#tax_details) | |       `period` | + | string | [Tax period](#tax-period) | |       `kbk` | + | string | Budget Classification Code, 20 digits | |       `oktmo` | + | string | All-Russian Classifier of Territories of Municipal Formations, 8 or 11 digits | |       `payment_reason` | + | string | [Payment reason](#tax-reason) | |       `document_number` | + | string | [Document number](#tax-doc) | |       `document_date` | + | string | [Document date](#tax-date) | |     `payer` | + | object | [Taxpayer's data](/reference/reference-objects.mdx#payer) | |     `payee` | + | object | [Recipient's data](/reference/reference-objects.mdx#payee) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | #### Parameter values ##### `payment_reason` - `TP` – for current-period tax/contribution payment - `ZD` – for voluntary repayment of tax/contribution arrears - `TR` – for debt repayment based on a demand issued by the tax authority or the Social Security Fund (FSS) - `AP` – for debt repayment based on audit findings (before a demand is issued) ##### `period` - If the `payment_reason` parameter contains `TP` or `ZD`, the tax payment frequency established by legislation is indicated in one of the formats below: - for monthly payments: `MS.MM.YYYY`, where `MM` is the month (from 01 to 12), and `YYYY` is the year for which the payment is made (for example, when paying personal income tax for employees' salaries for February 2026, use `MS.02.2025`) - ror taxes paid quarterly: `KV.QQ.YYYY`, where `QQ` is the quarter (from 01 to 04), and `YYYY` is the year for which the tax is paid - for semi-annual taxes (e.g., `UTII`): `PL.HH.YYYY`, where `HH` is the half-year (01 or 02), and `YYYY` is the year for which the tax is remitted - for annual payments: `GD.00.YYYY`, where `YYYY` is the year for which the tax is paid (for example, when making the final calculation for corporate profit tax for 2025, use `GD.00.2025`) - If the `payment_reason` parameter contains `TR`, specify the demand date - If the `payment_reason` parameter contains `AP`, specify `0` ##### `document_number` If the `payment_reason` parameter contains: - `TP` or `ZD`, specify `0` - `TR`, specify the tax demand number - `AP`, specify the audit decision number ##### Input format for the `document_date` field If the `payment_reason` parameter contains: - `TP`, specify the declaration signing date or `0` if the date is missing - `ZD`, specify `0` - `TR`, specify the tax demand date - `AP`, specify the post-audit decision date Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "tax", "tax": { // highlight-next-line "type": "tax_full", "tax_details": { // highlight-start "period": "КВ.04.2025", "document_number": "12345", "kbk": "18210301000011000110", "oktmo": "45348000", "payment_reason": "ЗД", "document_date": "01-07-2025" }, "description": "test payment", "uin": "0", "payer": { "inn": "1234567890", "kpp": "044525416" }, "payee": { "bik": "017003983", "account": "30102810400000000001", "account_eks": "40101810045250010041", "name": "name", "kpp": "770701001", "inn": "7707500730" } // highlight-end } }, "amount_details": { "amount": 5900, "currency": "rub" }, "customer": { "reference": "lucky", "contacts": [{ "email": "user123@test.com" }] }, "metadata": { "key": "value" } }' ``` ##### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters ##### Payout purpose example `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` --- - [Payouts to accounts using our widget or by token](https://developer.131.ru/en/payouts/payout-tokenized-account): Payouts without account details on your side You can make payouts to bank accounts using a token instead of the account number. You can get the token as follows: - using our [`tokenize`](/reference/methods#tokenize) method - using our [widget](/payouts/tokenize-account-widget) #### Step 1. Get a public token The public token is needed to initialize the widget. Send a [`token`](/reference/reference-methods.mdx#token) request to create a token, specifying the `tokenize_widget` widget type. You will receive a public token in response. Request example ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` ```php showLineNumbers 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. Initialize the widget [Initialize the widget](/payouts/tokenize-account-widget) on your website using the public token you received at the previous step. After this, the recipient can enter their bank account number into the widget form. #### Step 3. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/payouts/russian-account-parameters) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers 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 '{ "metadata": "good" }' ``` ```php showLineNumbers 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() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with the [payout parameters](/payouts/russian-account-parameters). :::info You can get information on the token or account using the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Money transfer" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.102034Z", "updated_at": "2025-05-27T02:03:00.454005Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.676006Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Money transfer" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-account-parameters) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers 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 '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-account-parameters). :::info You can find information on the token or account using the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ // highlight-next-line "session_id": "ps_1694821", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Payout" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.456004Z", "updated_at": "2025-05-27T02:03:00.756005Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.355006Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Payout" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/reference-objects.mdx#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds.mdx) --- - [Payouts to cards using our widget or by token](https://developer.131.ru/en/payouts/payout-tokenized-card): Payouts to a card with a token You can make payouts to bank cards using a token or hash for a bank card. You can get a token/hash as follows: - hash: [using our widget](/payouts/tokenize-widget) - token: using the [`tokenize/elements`](/reference/methods#tokenizeelements) method - token: by [processing a recurring payment](/payments/payment-recurring) >A token does not depend on the project ([`X-PARTNER-PROJECT`](/reference/format#authentication)) within which it was created. The scope of PCI DSS requirements that you must comply with depends on which option you choose. #### Step 1. Get a public token The public token is needed to initialize the widget. Send a [token](/reference/reference-methods.mdx#token) request to create a token, specifying the `tokenize_widget` widget type. You will receive a public token in response. Request example ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` ```php showLineNumbers 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. Initialize the widget [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token you obtained in the previous step. After this, the recipient can enter their bank card details into the widget form. #### Step 3. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers 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 '{ "metadata": "good" }' ``` ```php showLineNumbers 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() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-card). :::info You can find information on the hash or card using the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\EncryptedCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $participant = new Participant(); $participant->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->startPayoutSession('session_id') ->setCard(new EncryptedCard('number_hash')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayout($request); ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.340663Z", "updated_at": "2025-05-27T02:03:00.745032Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.203301Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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) { //do your logic here } ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. In the request specify either token or hash depending on which one you use. #### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers 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 '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-card). :::info You can find information on the token, hash, or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.102599Z", "updated_at": "2025-05-27T02:03:00.560466Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.607390Z", "customer": { "reference": "user123", "contacts": [{ "email": "user123@test.ru" }] }, "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers 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) { //do your logic here } ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/reference-objects.mdx#payout_status) [View error codes >](/reference/errors) Example of how to handle a webhook using SDK ```php showLineNumbers 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 } ``` --- - [Payouts to YooMoney wallets](https://developer.131.ru/en/payouts/yoomoney): Payouts to YooMoney wallets You can make payouts from your collateral account to YooMoney wallets of individuals and self-employed people. ### Payout parameters | Name | Mandatory | Type | Description | |---------------------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payout details](/reference/reference-objects.mdx#payment_method) | |   `type` | + | string | Value: `wallet` | |   `wallet` | + | object | [Recipient's electronic wallet](/reference/reference-objects.mdx#wallet) | |     `type` | + | string | Wallet type. Value: `yoomoney` | |     `yoomoney` | + | object | [YooMoney wallet details](/reference/reference-objects.mdx#yoomoney) | |       `account` | + | string | YooMoney wallet number, 11 to 20 digits. Example: `4100175017397` | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | ### How to perform the payout Use the [payout scenario without our widget](/reference/typical) sending the parameters from the table above. YooMoney wallet payout request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { // highlight-start "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": { "account": "410012411727100" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` --- - [Widget for connecting a self-employed person to the Bank](https://developer.131.ru/en/payouts/selfemployed-widget): Connecting a self-employed person to Bank 131 --- - [Widget for getting tokenized bank account details](https://developer.131.ru/en/payouts/tokenize-account-widget): Widget for getting tokenized bank account details Use the widget to save bank account details with Bank 131. ### What the widget looks like Code example: a page with the widget ```html showLineNumbers Widget for bank account tokenization document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131BankAccountTokenizer) { return; } const bankAccountTokenizer = new Bank131BankAccountTokenizer( publicToken, { /* // An example of widget text settings texts: { // Label field Account number. The default is "Account number". bankAccountLabel: '', // BIC field label. The default is "BIC". bikLabel: '', // Account linking button. The default is "Link account". submitButtonLabel: '', validationErrors: { invalidBankAccount: '', invalidBankAccountLength: '', invalidBikLength: '', isRequired: '' }, }, styles: { bankAccountTokenizer: { // Styles for the inline input field container. inputContainer: { background: 'cornsilk' }, // Styles for the input field. inputField: { background: 'cornsilk' }, // Styles for the input field when focused. inputFieldIsFocused: { background: 'white' }, // Styles for the error input field. inputFieldIsInvalid: { background: 'red' }, // Styles for the input field placeholder. inputFieldPlaceholder: { color: 'blue' }, }, } */ } ); bankAccountTokenizer.onReady = function () { console.log('Bank account tokenizer is ready.'); }; bankAccountTokenizer.onTokenizationStart = function () { console.log('The tokenization process was started.'); }; bankAccountTokenizer.onTokenizationFail = function () { console.log( 'The tokenization process was finished with an error', error ); }; bankAccountTokenizer.onTokenizationSuccess = function (result) { console.log( 'The tokenization process was successfully finished.', result ); }; bankAccountTokenizer.render(); }); ``` ### How the widget operates You embed the widget on your website. The user enters their account details, Bank 131 stores them in its system, and returns a payout token to you. You can save this token and use it for future payouts to the same account. This is secure. :::info You can find out information about a token using the [`token/info`](/reference/reference-methods.mdx#token_info) method. ::: ### Initializing the widget #### Step 1. Get a public token Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. #### Step 2. Set up scripts and CSS styles Include the widget's script (JS) and styles (CSS). The URLs differ between testing and live operations: ```html showLineNumbers ``` ```html showLineNumbers ``` After linking the script to the page, the `Bank131BankAccountTokenizer` class will appear in the global scope. #### Step 3. Add a container Add a container with a unique ID to place the widget on the page: ```html showLineNumbers ``` #### Step 4. Create an instance of the class Pass the public token to the `Bank131BankAccountTokenizer` class constructor: ```js showLineNumbers const bankAccountTokenizer = new Bank131BankAccountTokenizer('public token'); ``` You can also pass settings for widget texts and styles for the input field to the constructor: ```js showLineNumbers const bankAccountTokenizer = new Bank131BankAccountTokenizer( 'public token', { texts: { // Label field Account number. The default is "Account number". bankAccountLabel: '', // BIC field label. The default is "BIC". bikLabel: '', // Account linking button. The default is "Link account". submitButtonLabel: '', validationErrors: { invalidBankAccount: '', invalidBankAccountLength: '', invalidBikLength: '', isRequired: '' }, }, styles: { bankAccountTokenizer: { // Styles for the inline input field container. inputContainer: { background: 'cornsilk' }, // Styles for the input field. inputField: { background: 'cornsilk' }, // Styles for the input field when focused. inputFieldIsFocused: { background: 'white' }, // Styles for the error input field. inputFieldIsInvalid: { background: 'red' }, // Styles for the input field placeholder. inputFieldPlaceholder: { color: 'blue' }, }, } ); ``` The following key event handlers can be used: ```js showLineNumbers bankAccountTokenizer.onReady = function () { // Handler for the widget's readiness event. }; bankAccountTokenizer.onTokenizationStart = function () { // Event handler that occurs when the tokenization process starts. }; bankAccountTokenizer.onTokenizationFail = function () { // Event handler that occurs when the tokenization process fails. }; bankAccountTokenizer.onTokenizationSuccess = function (result) { // Event handler for the successful completion of the tokenization process. }; ``` #### Step 5. Display the widget Call the `render()` method: ```js showLineNumbers bankAccountTokenizer.render(); ``` [How to make a payout with the widget ot by token >](/payouts/payout-tokenized-account) --- - [Widget for getting tokenized bank card details](https://developer.131.ru/en/payouts/tokenize-widget): Secure transactions with bank cards with the widget --- ## Payments - [Monthly report](https://developer.131.ru/en/payments/finance-act): Monthly payout report --- - [AFT payments](https://developer.131.ru/en/payments/payment-aft): Replenishment of an account or wallet from a bank card An AFT payment (Account Funding Transaction) is an operation to top up an account or wallet from a bank card. To enable AFT payments, please contact a manager at Bank 131. :::info When processing an AFT payment, the issuing bank may charge a commission. Note that there might be no grace period if a payment is made using a credit card. ::: The processing scenario for an AFT payment does not differ from the scenario for [processing a regular bank card payment](/payments/payment-pcidss.mdx). --- - [Payments via FPS](https://developer.131.ru/en/payments/payment-fps-qr): Payments via FPS You can receive payments using the Faster Payment System (FPS). To do this: 1. Open an account in Bank 131. 2. Register your legal entity account with the FPS. 3. Add an FPS payment link onto your payment webpage. You can accept FPS payments in two ways: * With a QR code, which works for payments made from a desktop browser (`customer_interaction.type.inform.qr.img` from the `action_required` webhook). * With a deeplink, which works for payments made from a mobile device (`customer_interaction.type.inform.qr.content` from the `action_required` webhook). To accept the FPS payments with a QR code, you should create QR code in accordance with the [NSPK guidelines](https://sbp.nspk.ru). >After an FPS payment is complete, you will receive the customer's masked phone number in the `phone` parameter of the [`contacts`](/reference/objects#contacts) array. Should you require the customer's full phone number, apply to your manager in Bank 131. [How to make recurring payments via FPS >](/payments/payment-recurring-fps) [How to get a token for recurring payments via FPS without charging >](/payments/payment-recurring-fps#no_charge) ## How to receive a payment via FPS 1. Create a payment session [`session/create`](/reference/reference-methods.mdx#sessioncreate) specifying `faster_payment_system` in the `payment_details.type` object. If required, specify the payment purpose in the `description` parameter of the [`faster_payment_system`](/reference/objects#faster_payment_system) object. Request example ```json showLineNumbers 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 '{ "payment_details": { // highlight-next-line "type": "faster_payment_system", "faster_payment_system": { // highlight-next-line "description": "Payment of services" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_123456789", "status": "created", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z" } } ``` 2. Send a payment request using the [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) method. The `payment_options.return_url` parameter contains an URL to take customer back from the issuer's mobile application. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_123456789", "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" }, "customer": { "reference": "lucky" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_123456789", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_5000", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }] } } ``` 3. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to confirm the payment with [`session/confirm`](/reference/reference-methods.mdx#sessionconfirm) or cancel the payment with [`session/cancel`](/reference/reference-methods.mdx#sessioncancel). 4. Wait for an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook. The `customer_interaction.inform.qr.content` parameter contains a deeplink which you can either display as QR code to the customer in a web browser, or forward the customer to the issuer's mobile application. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_120285623", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_94939668", "status": "pending", "created_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "95.24.204.116" }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer_interaction": { "type": "inform", "inform": { "qr": { // highlight-next-line "content": "https://qr.nspk.ru/AD1000269CKIK8M09C1RB40LB7QAM8IH?type=02&bank=100000000143&sum=1000&cur=RUB&crc=C900", "img": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAATw0lEQVR42u3deXBURR7Acba2at3aqt2tPRRh5dBFWBQUWFYBCVqIS4mCuF5EQiGHohwCyuGFHCpGRUAsISACGw5RWK6AAV3FFbkhCgQLiCEc4QhHCCEkmVy/zYxmYEIyCWHy+tdvvr+q/gOmJzPzXvfnHb/X3TWEIAjCkqjBJiAIArAIgiAAiyAIwCIIggAsgiAIwCIIArAuerFGDTWlst+v0j/8Cj7X2M4ytK2u5PuFup4T7cqJtmaqHdjYzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlqmOqakRaYdXExKmOo1bDgza+4ITvw2wAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACvswDLVgW38ftqLEx3JVDtwc7ZT076szv0GWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWEqzZpoygqb+nqbspKlsopsPjoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWOqyPpqGLWhvlJqG0tjYqbXP1wVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYzIdlFCInsn+aMqDat4upbKJbwDfVzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlo0rP1OPetSzY942wKIe9agHWIBFPeoBFmABFvWoB1iART3qUc/VYGkPTcMgtM+HpSmLZOO8aNrbn6bsX7X2ecACLMACLMACLMACLMACLMACLMACLMACLMACrHAAS/uE/6Y6g5vnBHPLfFja8dS+CIrTnwFYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgGU1WG4eXqM9q2LjECgbs8qa9pum7KRWFAELsAALsAALsAALsAALsAALsAALsAALsAALsABLQZZQO6jaF1YIdYPWnsXUhKL29uf4QQewAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACscwLIxI2PjAhvhMvyiukBwy8FME3ZOZ/QBC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7BcB5aphqWpQZv6ztqHc2iCSDsc2hdB0RqABViABViABViABViABViABViABViABViABVhhC5amDa19OIxbMLERVLcsWuKWkwbAAizAAizAAizAAizAAizAAizAAizAAizAAixXg+VE5zcFpanGa6qzakJHUyZNe9u1MUtYnZ8BWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIDlOrA0IWHjnFumtrOmrFS4rRSuvQ1p6jOABViABViABViABViABViABViABViABViABViuBsstQ1pM7STtnZoMlJ3bwNTvCHVbC3mWELAAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AASztYNnYkTSsSu2UeJDevthxukGvfLoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWGEHlo2Nw1RH15RN1D7nlo0LgJjab9rbs/r5sAALsAALsAALsAALsAALsAALsAALsAALsAALsJjTXVe2RNNnaMrWhdvqzcyH5fxQJMACLMACLMACLMACLMACLMACLMACLMACLMACLKvBcstKyDZ2JO3zZmnKIGvvwJoO/LbvD8ACLMACLMACLMACLMACLMACLMACLMACLMACLKvBMpW90p7lqs5GTugMtwwX03SQUj+BH2ABFmABFmABFgFYgAVYgEUAFmABFmABFmCFGiwbV/I1NeeRG4ddEPaAoH0OL0fmwwIswCIAC7AAC7AAC7AAC7AIwAIswAIsArBsBMvNG9VUIwIsO1HS1Pltz/4BFmARgAVYgAVYgAVYgAVYgAVYgAVYgEUAVtiC5ZZVnp0AuirvdS6K0MihDux0p64uFE0ZAViAJYWntkr2irFSlHUGeQALsABLN1hFp9fL+TmNJf2l2yV346Li/+CMC7AAC7AUg5UXX1syxjSV04MbytnJj0nBkT0oBFiABVhawbpWchY29IHlK0Mby/kl46Uo5xwaAZZ9YJnaCE58rimMtYHlLWffanoBreJy5tUI8SSsQqQQtT8nOrqNC6gAFmBVCazcJTf4zq4uRstbMqf1loLjyWgFWIAFWHrA8pZzU5pcApa3pD/fRLI/myxFebmABViABVg6wPLE1ZX04TeViZbvMnFse8nb/TVgARZgAZZ5sLwla0bjcsEqKec+GiCF6UcBC7D0gRVuwGho5Jcbc789JFmegpCAlfffppK9arLvMjAYWukjmknOFzEiBXlhA5UTnVrrHG2agAYsy8HqM/IzaTH1e4nfl37FYOV/dYvvtcITByRzaq8Kz7Yy3uwk+UmbAQuwAAuwKhcD+i2S20etlT+/uVkeX7RXDmXkXjFYJeH5Ll7OjG4XHK4hjSRrwQtSdO60Y9s1Py9fzp/PBizAAiwbwerW6xOp/dZmH1p1JmyVyRuOiKegqAqXhI0DYUg9JUe7jZf9DR4LWlI7DRVPYmifkt+1c488N/g1afX3rnJjvTvlr3UipE7NVnLdNbf7yrP9RwMWYAGWjWB1fyxW2o383AdWSbnjw52y4VDmZYLV6KfXPPmSPmmZJP0pUvZe9WC5JekP3eR09CIpyg3tvax3354hda9t7cepdPHilXr4GGABlvNgOZ2F0zhHUSjA6t5jgdR7c1MAWldHb5YBcclyIiuv0mBlf5MoKc2eDQqVt6R2eU3yUo6HHIgpk2aXC1VJeW3MFLUHJE0ZRk1zvoXKF8ByC1jFpePznwWAVVJumLhNPtqeJoVFFYC1uoHs/fW/gkKV3OBJObd0Y5X21949+2X+3GUyacJMeX/yHPlizTrxeC5gmrQvRerXvsMP023Nu8jKFV/K2YxMyc31+EthYaH/PVlZ2bJh/fZKlW1bdgIWYAGWFrCiIudKo/EbykTLWzrMSZSEo1nBwSoHqn2/fUROvhwrhedyLvs7JmxPlAc69S3zbKl5k06++1XeGP7ceP//33RjBzmSelwyirHaunmHbN2yQ06dvDQTunvXvgrPyC7+LMACLMBSApa3PDBweblgeUvN6C0ycs0BST/yTaXBOtThZfH8cKhK+yh+1Vq5/i9ty0Wk5a2dfRm/oqIiueVvHf3/P6DfKHm670tSr1Yb//9572tFPjJIkn88CFiABVhuAMtbes3ZIdcUwxQMrsYT/yfzF/YVT3ytcsFKrttLzs7/usqzKR89kiYNr7/LD4YXn75PjJDXx74vfXqO8N08/8+ieF/dQwePBOBycUawdLm1cUdJTT1eJlg3XBfhOzsrKfVqtQYswLKrXqhB1ZTZLAusH3Yf9136tZ+dGBQtb+n8wQJJXB4RCNZvHpK0QdOlIP3K5sV6J3p6AFbrv90W8Prp0xlS+PONte8Tdl96RnTzvT7c3nx9qrRoel/Aa889O65MsEa/MingMzq27xESsLQOVamu9qz1BAawXAqWNwqKL7NmbDvuu+keDK1ab22SMXNelYz4W+Rg2xGSsy0pJJ0o8uGBfix6dBsStO6unXsD4Klfu40cSDnsf/3ggdTiS8sLN+SbNvonYAEWYLkJLG/k5+TLyqnr5IERa+TqCs62mk/+UuL3hO6J9Ye69PNj8cyTLwete/JkegA87SMiL6lzd7vIgDreDCNgARZguQSslI37ZV7PWIm59wNfGRM1V5qPXVfhZWLU4n1y+KznijvRiIuyfk0a3lN8CRh8hZ42LR/017/5xg6Sl3fhkQfvcJybi/9GyesN69/JGRZgAZYbwNqyNklWj13lhyqgdI6R3gOXS51SD5mWLnUnbJUpG49KXkHVV9PZtCEhAJN2rR+RTz6Oky2bd/hutvd/6pUAxN6JjgmoP3jgWDl27ITv7GvYkNcDXuvVYxhgAVb1bnxNi0aY2nGhjtJg9Xl8rkzrElM2Vj+XmV2ny8J5cdIyZmGFZ1veIT7fHsys8vcbPnR80EcNRr30rr+u95mr25p1rvDxhAZ12xWfRSY5CpaprLImKAELsEIO1huRc4JiFT9mlWQez5Q9p7ZKnxW3StePB0n9iV8FRct776t/XLKkZV3+mMH8/AJ5Y9z7ATfMS+Nz8VnWvr0pEtHq4XKxatG0k6xfdyHbCFiABViWgtU/ap5Mv39amVDN7xnru6dVEiVgeUuv5W0k4qMJUjM6+NmWN9s4KyHNl3283PA+tR7zwTzfA6FR3QbLgKdHybTif3ufvyodnlyPfLIgzvfg6H3/fEI63fOE9Ov9osyPXSpZWecD6p45c1Y+XbjSX75L2B3w+uerv/G/tmLZF4AFWIClBawJj866BKoPiy8PN83aKPm5+QHvuxisktJzaaTcN/eHCi8T756dKN8fy5JwD8ACLMCqIlhDi8+uSmO1YuQyST9Y9mMKZYE1KL6tb8X6+TtOSKP3tgdFy/sk/bDVKZKRUwBYgGUXWG6Zi0dDNqcqYEV1i5UpD830QxXbfbYkrd0XdEhNeWCVRHp2vgyN318MU/CzrcZTEmRR4qmwRMnUwcwtfbBKvx2w7Afrxcd/etZq+v1TZX3MOvFkVfwMVUVgeaOgsECejpsjNd8eGrTUn/iCfJ3yI2ABFmABVvAY0n+xTO06QxYP/FTS9qZV+n0VgbXh0E5pNq27/GL0bUHLvXMHS9Lpw5xhARZgAVbFMXX4Mtm1fIcUFV5e5q48sE6cPyO9lo6TX45pFRSquhM7y+LdX4b1fSrAAizAuszIyaraEJqywIpaEiF/jL47KFS/GttGhq15T855siUcArAsB8tUxs3UBnR6IQ6noiywGrwXERSrdrOeksS0ZCHMtl1TfdUJUAELsCoFVteFd5QL1TVvd5R/f7dSiqQIpQALsADLLFh941pI7QntLoHKex/rmZXRkp6diU6ABViApQOse2LbXoJVi5gesjl1NyoBFmABlh6wei9vKb8ff+Fy8Hfj75JJGxdIfmEBIgGWO8EytfGd+H5Ow+Y0WK1mXji7evTTFyX1bBoSVbLtmALBFGIahqQBVhiDFbXkH3LVuNbScMrDsubHjegEWIAFWHrBajm9g4xZ+6Hk5HuQCbAAC7D0gnXifJokp6ciEmABFmDpB4sArLAFy4mdpAmd6mwIhD1wae/8Ng4nAizAIgALsAALsAALsAALsAjAAizAAiwCsABLGQimGq+mObcIZ/a19gN1qPughvYMWIBFABZgARZgARZgARZgEYAFWIAFWARghQVYTvxgTfNXVefnEnZjpulAbaq/VSdigAVYBGABFmABFmABFmABFgFYgAVYgEUAltVgacLJ1Iq1mhqgE43SiU7jxD534mBmCkVNJxJObyvAAizAAizAAizAAizAAizAAizAAizAAizAAizXgaUpC6dpjiJTHc7GzJJ2PLXDq+nA6vTvBSzAAizAAizAAizAAizAAizAAizAAizAAizAshosTUMKtGdaNHUQUx3Oxm1vKmum6QBnU/YUsAALsAALsAALsAALsAALsAALsAALsAALsADLarBMNWjtGUZTmRu3DHMx1da0Z/U0gOBkOwUswAIswAIswAIswAIswAIswAIswAIswAIswAIsF3UGJ7J62ocxadqX2r9LuAEIWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWNUAllsam/ahEZo6jakskpuzpzZms00dqAELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlhMZPO2LD5iCSHvmVRN22r+zJpxszMADFmABFmABFmABFmABFmABFmABFmABFmABFmC5BixT2TVT2GnPfGlfpCDc5q9yc+Za6xAjwAIswAIswAIswAIswAIswAIswAIswAIswAIsq8FyItOifSVaG4dp2FhPe9vQPreZjVnWqvw9wAIswAIswAIswAIswAIswAIswAIswAIswAIs14GlKYOnfaiFqU5jY4ZMawdxEg7tC2yYOmkALMACLMACLMACLMACLMACLMACLMACLMACLMByDVjaG5abV5d28+INNs4FpWneMRtXsDY2HxZgARZgARZgARZgARZgARZgARZgARZgARZgAZZ2sLQ3Sicah1t+r6kO55bQPk+Ypow5YAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYLmoITjxXk1waJ+/StOq1po+w4n3ajooq5oPC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAy81gaYdNU8My9fdCvd9YhEIXlFqzooAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWFaDpT07pH0nac8waloIwdSiEdpXv7bxt1VnuwcswAIswAIswAIswAIswAIswAIswAIswAIswHIdWJqyf6FuCNqzk6bm4bJx+7k5k6u9HajKEgIWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYNkIlo0ZmVDvOFPzPtk4p5WNbUPDAgxuy+gbyxICFmABFmABFmABFmABFmABFmABFmABFmABFmABlq5GZOPQIaezOaaznW4BWlObBCzAAizAAizAAizAAizAAizAAizAAizAAizAAqwwBEvThP9uWViBYSnuWfnZ9gAswAIswAIswAIswAIswAIswAIswAIswAIswAoLsEL+pSycD8vUkBsntoumoUM2dkyGQAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAGWug1tKvPlBDDaF6vQhI5b5h1zoj1rOsAZW/kZsAALsAALsAALsAALsAALsAALsAALsAALsABLE1gEQRCqMq5sAoIgAIsgCAKwCIIALIIgCMAiCIIALIIgAIsgCEJn/B/u92LX9SrJTQAAAABJRU5ErkJggg==" } } }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "actions": { "confirm": "2024-02-07T23:59:53.310721Z" } } }' ``` 5. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the payment result from Bank 131. The `succeeded` status indicates a successful payment. The webhook also contains the customer's phone number. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_123456789", "status": "accepted", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_12345678", // highlight-next-line "status": "succeeded", "created_at": "2024-02-07T23:59:52.977041Z", "finished_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "lucky", "contacts": [{ "phone": "7965*****85" }] }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "actions": { "confirm": "2024-02-07T23:59:52.977041Z", "capture": "2024-02-07T23:59:52.977041Z" }, "transaction_info": { "fp_message_id": "A50581324524670W0000040011450701" } } }' ``` ## How to make a refund via FPS To make refunds using the FPS, follow the [standard procedure](/payments/payment-refund.mdx). ## Payment diagram ![](/img/docs/payments/fps_en.png) --- - [Delayed capture payments](https://developer.131.ru/en/payments/payment-hold): Delayed payment deductions You can place a hold on the payment: first authorize or hold the amount of payment on the user’s card and then capture it with a separate request. There is time between the funds being put on hold and the funds being debited so you can send the order to the customer, for example. ## How it works All in all, all payments made with bank cards consist of two key phases: authorization (when the bank verifies if the needed amount is actually available and places a hold for this amount on the bank card, essentially blocking it) and capture (when the bank clears the payment and writes off the blocked or authorized amount from the bank card balance). There is almost no time gap between the two phases for the standard card payment flow, it looks immediate to the user. However, if you decide to use the delayed capture payment flow, you can decide on the timing when to capture the blocked funds. In this case the bank will not capture the amount immediately, but will do so on your command. It is possible to write off the full amount put on hold or a portion of it. :::info For MIT payments with [YooMoney wallets](/payments/p-yoomoney) you can only write off the full amount put on hold. ::: ## How to enable delayed capture Bank 131 manages the delayed capture feature. All your payments may have immediate or delayed capture. If captured immediately, the amount of payment will be cleared automatically right after the authorization. If you would like to perform delayed capture payments, please contact your Bank 131 manager. ## Hold period The money is held for up to **5 days**. If you do not debit or unblock it before the end of this period, the money will get unblocked automatically. If you need the money to be debited rather than unblocked after the hold period end, please contact your Bank 131 manager. ## Later capture payment scenario To create a delayed capture payment, complete the following steps: 1. Create a payment session that is separate from the actual payment ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) or a single combined session ([`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment)). 1. If you have created the session separately from the start of the payment, send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request. 1. Bank 131 will then send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook, which means that the Bank is ready to perform the payout and is waiting for your confirmation. 1. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). 1. If you get an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook from Bank 131, this means that you will need to take additional action to perform the payment. For instance, the user might need to go through 3D Secure. Redirect the user to the address for 3D Secure. 1. Wait for a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook from Bank 131. It means the required amount is held on the bank card successfully. It can be captured immediately or later. You can capture the full amount or a portion of it—see [`amount_details`](/reference/reference-objects.mdx#amount_details). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers 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_CAPTURE) { $session = $hook->getSession(); //do your logic here } ``` 2. Capture the full amount that is on hold, a portion of the amount ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)), or decline the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). 3. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. ## Payment diagram with holding ![Payment diagram with holding](/img/docs/payments/schema_payment_hold_en.png) 1. Complete [Steps 1–5](/payments/payment-with-form). > If you receive an `action_required` webhook, send the HTTP 200 OK in response—the user will be redirected for 3D Secure within the widget. 1. Wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook from Bank 131. It means the required amount is held on the bank card successfully. It can be captured immediately or later. You can capture the full amount or a portion of it—see [`amount_details`](/reference/objects#amount_details). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers 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_CAPTURE) { $session = $hook->getSession(); //do your logic here } ``` 2. Capture the full amount that is on hold, a portion of the amount ([`session/capture`](/reference/methods#sessioncapture)), or decline the payment ([`session/cancel`](/reference/methods#sessioncancel)). 3. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. #### Diagram of a delayed capture payments ![Payment diagram with holding](/img/docs/payments/schema_payment_with_form_en.png) --- - [About payments](https://developer.131.ru/en/payments/payment-intro): API for accepting payments by bank cards, via SBP and SberPay With our API, you can make payments and issue refunds securely and with ease. >In case your business is on the [list of restricted businesses](/documents/restricted-business), you cannot enable payments. ### API features With the Bank 131 API, you can: - accept payments via bank cards (Visa, Mastercard, and Mir), via [SberPay](/payments/payment-sber-pay), [T-Pay](/payments/payment-tpay), and [FPS](/payments/payment-fps-qr) - [accept payments from YooMoney wallets](/payments/p-yoomoney) - [make recurring payments](/payments/payment-recurring) - [send AFT payments](/payments/payment-aft) - [process two-stage payments](/payments/payment-hold)—hold funds on a card for up to 5 days, then debit them fully or partially - [issue full or partial refunds](/payments/payment-refund) ### Sending card data You can submit card data to Bank 131 either [via the payment widget](/payments/payment-widget) or [directly](/payments/payment-pcidss). Both options require PCI DSS compliance, but using the widget means fewer requirements for you. ### Card identifier A card identifier is necessary to determine which card the recipient is using and to identify cases where multiple recipients are using the same card. The identifier is generated based on the card number and its expiration date if it is available. It is passed in the `card_id` parameter of the [`card`](/reference/objects#card) object. By default, `card_id` is unique for each project but you can choose this value to be the same across all your projects. [Learn more about the project >](/before) :::info A card identifier is not a replacement for a token and cannot be used to make payments or to retrieve all cards linked to a recipient. ::: To set up the identifier, contact your manager at Bank 131. ## Tariffs and limits The tariffs are given in your agreement with the Bank. You can discuss them with your manager. --- - [Single-request payments](https://developer.131.ru/en/payments/payment-pcidss-simple): Payments with no interim steps You can send a payment as single request, with no interim steps (if they are not necessary). You will shortly get the payment result in response. This option can work if you don't use the [payment form widget](/payments/widget-payment.mdx) Here, a payment with immediate capture is described. [More about delayed capture payments >](/payments/payment-hold.mdx) ## How to enable For such payments, there is a special method, [`session/init/payment/sync`](/reference/reference-methods.mdx#sessioninitpaymentsync). Inform the Bank 131 manager that you want to use it. In this case, **you will not receive webhooks** from Bank 131. You can learn the transaction status with the [`session/status`](/reference/reference-methods.mdx#sessionstatus) request. ## How to perform a payment Send a [`session/init/payment/sync`](/reference/reference-methods.mdx#sessioninitpaymentsync) request. >Please be aware that we do not recommend implementing this method unless you have already used it before. In the `type` field of the `payment_method`/`payout_details` object, specify `card`. In the [`bank_card`](/reference/reference-objects.mdx#bankcard) object, specify user bank card details. In the `payment_options.return_url` field, specify the address to which the user should be redirected after the payment is processed (**it is required**). The payment result will be returned in response to the request in the `status` field of the `payments`/`payout_list` array: - `succeeded` – the payment has completed successfully - `failed` – the payment has not gone through because of an [error](/reference/reference-errors.mdx) - `pending` – the user needs to go through 3D Secure verification [More about the payment statuses >](/reference/reference-objects.mdx#payment_status) Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment/sync \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "card", "card": { "type": "bank_card", // highlight-start "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "123" } // highlight-end } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" } }' ``` ## If no result is returned Sometimes, the final payment status is not returned in response to a request. For instance, if a payment is being processed for a very long time or the user card requires 3D Secure. ### Too long payment If payment processing lasts more than 40 seconds, the `in_progress` intermediate [payment status](/reference/reference-objects.mdx#payment_status) will be included in the response. To learn the final payment status, send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request. ### 3D Secure card If a user card requires 3D Secure, [redirection details](/reference/reference-objects.mdx#redirect) will be returned in response to the request. Redirect the user to `customer_interaction.redirect.url`. After that, send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request to learn the final payment status. --- - [Payments by bank cards](https://developer.131.ru/en/payments/payment-pcidss): Payments by bank cards for services collecting and storing bank card details on their side This scenario describes how bank card payments are accepted and processed by services having the technical capacity to collect and store card details on their side. If you decide not to collect bank card details and not to store them on your side, [accept payments using our payment form](/payments/payment-with-form). > This scenario does not include the payment capture step. [How to make a delayed capture payment](/payments/payment-hold) 1. Create a payment session ([`session/create`](/reference/reference-methods.mdx#sessioncreate)). You will receive a payment session identifier in response. >Alternatively, you can use the [`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment) method. In this case, specify all the payment parameters right away and skip the next step. Creating a session ```json showLineNumbers 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 '{ "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }' ``` ```php showLineNumbers 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() ->createPaymentSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` 2. Send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request. - In the `session_id` parameter, pass the identifier of the session created in Step 1. - In the `type` field of the `payment_details` object, specify `card`. - In the [`bank_card`](/reference/reference-objects.mdx#bankcard) object, transmit user's bank card details. Starting a payment ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { // highlight-next-line "type": "card", "card": { "type": "bank_card", // highlight-start "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } // highlight-end } }, "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $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() ->startPaymentSession('session_id') ->setCard( new BankCard( '4242424242424242', '02', '22', '123', 'cardholder name' ) ) ->setCustomer(new Customer('lucky')) ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); ``` 3. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook—this means that the payment can be performed and the Bank is waiting for you to confirm (or cancel). The webhook body will contain all the data needed for the payment, which you need to check. You then reply with the 200 HTTP code. Webhook example ```json showLineNumbers 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", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers 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 } ``` 4. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` 5. If the user's card requires 3D Secure, Bank 131 will send you an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook with redirection details in the [`customer_interaction.redirect.url`](/reference/reference-objects.mdx#redirect) field. Redirect the user. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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::ACTION_REQUIRED) { $session = $hook->getSession(); //do your logic here } ``` 6. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook or request the payment status using the [`session/status`](/reference/reference-methods.mdx#sessionstatus) method. The result of the payment can be found in the `status` field of the `acquiring_payments/payment_list` array. If the status is `succeeded`, then the payment has been successful. If the status is `failed`, then the payment has not been completed because of an [error](/reference/reference-errors.mdx). [More about the payment statuses >](/reference/reference-objects.mdx#payment_status) ## Payment without a payment form ![Payment with PCI DSS](/img/docs/payments/schema_payment_pcidssNOHOLD_en.png) --- - [CIT recurring payments](https://developer.131.ru/en/payments/payment-recurring-cit): Payments by token with 3D Secure verification of the payer CIT (**Customer Initialized Transaction**) recurring payments allow to accept payments and debit money using a token with additional 3D Secure verification of the customer. For CIT recurring payments, it is recommended to use the [project identifier](/reference/format#authentication) eligible for 3D Secure. ## How to create a CIT recurring payment 1. Initialize a CIT recurring payment session using the [`session/init/payment`](/reference/methods#sessioninitpayment) method, with the `initiator:client` value in the [`recurrent`](/reference/objects#recurrent_token_info) object and a URL value within the `return_url` setting to redirect the customer back after the payment complete. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "recurrent", "recurrent": { "token": "token_value", // highlight-next-line "initiator": "client" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" } }' ``` 1. Wait for an [`action_required`](/reference/webhooks#action_required) webhook from Bank 131 that contains the [customer redirect data](/reference/objects#redirect). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "GET", "qs": { "foo": "bar" }, "params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` 3. Redirect the customer to the URL passed as `customer_interaction.redirect.url`. Note that the redirect method can be GET or POST. 4. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131. The webhook contains the recurring payment status information. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "recurrent": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "rub" } }] } }' ``` 5. Note that after completion of 3D Secure verification, the customer returns to the URL that was passed as `return_url`. According to the method used, POST or GET, you might be required to convert the POST format to GET to avoid possible format processing issues. ### CIT recurring payment diagram ![](/img/docs/payments/cit_en.png) --- - [Recurring payments via FPS](https://developer.131.ru/en/payments/payment-recurring-fps): Linking the payer's account and recurring token for future payments Our API offers the following options: - getting a token for recurring payments via FPS along [with charging](#with_charge) - getting a token for recurring payments via FPS [without charging](#no_charge) ## How to get a token for recurring payments along with making a payment 1. Create a payment session [`session/create`](/reference/reference-methods.mdx#sessioncreate). 2. Send a payment request using the [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) method. The `payment_options.recurrent` parameter contains the `true` value. 3. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to confirm the payment with [`session/confirm`](/reference/reference-methods.mdx#sessionconfirm) or cancel the payment with [`session/cancel`](/reference/reference-methods.mdx#sessioncancel). 4. Wait for an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook. The `customer_interaction.inform.qr.content` parameter contains a deeplink which you can either display to the customer as QR code in a web browser, or use it to forward the customer to the issuer's mobile application. 5. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the transaction result from Bank 131. In case of a successful transaction, the webhook will contain `status=accepted` (`session` object) and `status=succeeded` (`payments`/`payout_list` array) along with a recurring token within the `recurrent.token` parameter. If the transaction fails, the webhook will contain `status=cancelled` (`session` object), `status=failed` (`payments`/`payout_list` array), and no recurring token. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_713610", // highlight-next-line "status": "accepted", "created_at": "2024-08-08T08:06:51.841432Z", "updated_at": "2024-08-08T08:14:56.168219Z", "acquiring_payments": [{ "id": "pm_308906", // highlight-next-line "status": "succeeded", "created_at": "2024-08-08T08:06:51.931193Z", "finished_at": "2024-08-08T08:14:55.996273Z", "customer": { "reference": "user123", "contacts": [{ "phone": "7123*****45" }] }, "payment_details": { "type": "faster_payment_system" }, "recurrent": { // highlight-next-line "token": "6a6a29c4193a8e1049231e1497a3c5f180e120b20db81b39f53ec478029b53cf", "created_at": "2024-08-08T10:10:27+03:00", "finished_at": "2034-08-08T10:10:27+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 1000, "currency": "RUB" }, "amounts": { "net": { "amount": 1000, "currency": "RUB" }, "gross": { "amount": 1000, "currency": "RUB" } } }], "actions": { "confirm": "2024-08-08T08:06:52.184593Z", "capture": "2024-08-08T08:14:55.699095Z" } } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_713610", // highlight-next-line "status": "cancelled", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "acquiring_payments": [{ "id": "pm_308906", // highlight-next-line "status": "failed", "created_at": "2022-03-01T11:57:31.895773Z", "finished_at": "2022-03-01T11:57:31.895773Z", "customer": { "reference": "user123" }, "payment_details": { "type": "faster_payment_system" }, "amount_details": { "amount": 229600, "currency": "RUB" }, "amounts": { "fee": { "merchant_fee": { "amount": 1607, "currency": "RUB" } } }, "metadata": { "parent_session_id": "ps_1667788995" }, "error": { "description": "QR expired", "code": "qr_expired" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "error": { "description": "Session cancelled", "code": "session_cancelled" }, "actions": { "confirm": "2022-03-01T11:57:31.895773Z" } } }' ``` Diagram ![](/img/docs/payments/recurring_fps_en.png) ## How to get a token for recurring payments without charging To get a token for recurring payments via FPS without charging, you need to complete [all the standard steps required to make a payment via FPS](#with_charge). When sending a [`session/start/payment`](/reference/methods#sessionstartpayment) or [`session/init/payment`](/reference/methods#sessioninitpayment) request, specify `"type": "faster_payment_system_binding"` and `"recurrent": true`. In the `amount_details` object specify 1 ruble (the amount will not be charged). The `payment_finished` webhook will return a token for recurring payments. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "faster_payment_system_binding" }, "amount_details": { "amount": 100, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` Once you have a token, accept recurring payments in a standard way. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` ## How to create multiple FPS subscriptions for the same payer and bank Each time an SBP subscription is additionally created for the same payer and the same issuing bank, the bank may show a message saying: "You have already linked an account." This confuses the payer, who cannot tell whether a new subscription was actually created. To allow an unlimited number of unique subscriptions to be created correctly and to avoid the confusion described above, it is necessary to additionally pass the [`subscription_service_info`](/reference/objects#subscription_service_info) object containing the subscription identifier and name. To enable this functionality, please contact your manager at Bank 131. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "faster_payment_system", "faster_payment_system": { // highlight-start "subscription_service_info": { "id": "54f731a9f86b46188b7961cb933fb3ff", // subscription identifier "name": "subscription2" // subscription name } // highlight-end } }, "amount_details": { "amount": 1000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` --- - [MIT recurring payments](https://developer.131.ru/en/payments/payment-recurring): MIT recurring payments A recurring payment (or repeated payment) enables you to accept a payment and debit money in the following ways: - With a token, without involving the user, those recurring payments are called **Merchant Initialized Transaction** (MIT). - Requesting 3D Secure verification from the user, those recurring payments are called **Customer Initialized Transaction** (CIT). This page only overlooks the MIT recurring payments. [Learn more about CIT recurring payments >](/payments/payment-recurring-cit.mdx) Recurring payments are currently supported for bank cards and the methods below. Other options will be available later. [How to make recurring payments via FPS >](/payments/payment-recurring-fps) [How to make recurring payments via SberPay >](/payments/payment-sber-pay#r-payments) [How to make recurring payments via T-Pay >](/payments/payment-tpay#r-payments) [How to make recurring payments via YooMoney >](/payments/p-yoomoney#r-payments) > A new token is generated for each new payment made using the same card. This token is linked to the payment, not to the card. If you need to identify the card, you can use the [card identifier](/payments/payment-intro#cross-identifier-card). **How to create a recurring payment** 1. [Obtain the user's consent](#agreement) to recurring payments. 2. [Perform a successful payment](#first_payment) that will recur, and get a [token](#token). 3. [Perform payments using this token](#recurring_payment). ## User consent ### Why you need it Recurring payments are pre-authorized by a user and can be made without any future confirmation from them. The user only sees funds debited from their card. This is why you assume full responsibility for such payments: their amount, frequency, and user's consent to them. You need user's consent for dispute situations (e.g. if the user complaints about an unauthorized debit). ### How to obtain user's consent You can do it in any way you find convenient. The main point is that you need to verify the user had been aware of automatic debits when they made the first payment, and agreed to them. How to do it: 1. Describe the payment terms to make sure the user will read them. 2. Ask the user to confirm they understand and agree to the terms (e.g. add an unambiguous checkbox like **Save card**, **Enable automatic payments**, **Enable recurring donations**, etc.). If the user checks the box, thus verifying their consent, recurring payments become enabled. If they don't, recurring payments are not activated. The checkbox can be on your side (in this case, you will decide how it looks and where it is located) or on our side—in our [payment widget](#first_payment). ## Token for recurring payments You need to perform one payment successfully, selecting the option to save bank card details. In response to this payment, you will receive a [token](/reference/reference-objects.mdx#recurrent_token_info). This token can be saved and used to accept future payments. ### How to get a token #### When creating a payment session Send `recurrent=true` (in [`payment_options`](/reference/reference-objects.mdx#payment_options)). You can do this when [creating a payment session](/reference/reference-methods.mdx#sessioncreate) or in any payment request. If such a payment is successfully performed, you will receive a token for recurring payments with which you will be able to repeat the payment. > In this case, you need to get the user's consent on your side beforehand. #### In our payment widget If you perform a payment with the widget, you can show the **I agree to recurring payments** checkbox to the user. If the user ticks this checkbox and the payment is performed successfully, you will receive a token for recurring payments. ### Token statuses When you create a token, it becomes active (`is_active: true`) and you can perform payments with the token. If a token is inactive (`is_active: false`) or expired, the payment will not be processed and you will see an error. ### How to learn the token status Send a [`token/info`](/reference/reference-methods.mdx#token_info) request. In the `type` parameter, pass `recurrent_token`, in the `recurrent_token.token` parameter, pass the token. In return, you will get [`info`](/reference/reference-objects.mdx#info_recurrent) with the date of token expiration (`finished_at`) and status (`is_active`). The token expiration setting (`finished_at`) isn't processed by the Bank, i.e. the token will remain active even after the specified expiration date. If `is_active: true`, you can perform payments with this token. Please note that an active token won't guarantee a successful payment, since the payment can be, for some reason, rejected by the card issuer. ### How to disable a token If you don't want to use a token for payments anymore (e.g. a user disabled recurring payments), send a [`recurrent/disable`](/reference/reference-methods.mdx#recurrentdisable) request. In response, you will receive [`recurrent`](/reference/reference-objects.mdx#recurrent_token_info). If `is_active: false`, it means the token is disabled and you cannot perform payments with this token anymore. > After the token is disabled, the token expiration setting (`finished_at`) may contain a date of the year 2000. This value won't affect anything, so please disregard it. ## How to accept recurring payments ### Step 1. Successfully perform a payment with an instruction to create a token >[How to make a payment without our widget >](/payments/payment-pcidss.mdx) When creating a payment session or sending a payment request, pass `true` in the `recurrent` parameter of the [`payment_options`](/reference/reference-objects.mdx#payment_options) object. Example of a payment request with an instruction to create a token ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "087" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); // highlight-next-line $paymentOptions->setRecurrent(true); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '01', '22', '087')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayment($request); ``` >[How to make a payment with our widget >](/payments/payment-with-form.mdx) If you perform a payment with our widget, you can show the user the **I agree to recurring payments** checkbox. To do this, in the [widget token creation request](/reference/reference-methods.mdx#token), pass `true` in the `show_recurrent_checkbox` field. > This is optional. You can obtain the user's consent earlier, pass `recurrent: true` when creating a payment session, and show the user the widget with no checkboxes—the same as for one-time payments. Example of creating a token for the widget with a checkbox to agree to recurring payments ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_34851", // highlight-next-line "show_recurrent_checkbox": true } }' ``` Then, [create a payment form](/payments/widget-payment.mdx) with this token. If the user ticks the **I agree to recurring payments** checkbox (i.e. agrees to enable recurring debiting from their card), you will receive a token. Example of a widget with an option to enable or disable recurring payments ![Recurring payment widget](/img/docs/payments/payment_form_recurrent_en.png) ### Step 2. Save the token If the payment is performed successfully (and the user enables recurring debiting when paying through the form), you will get the token in the [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "recurrent": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "recurrent": true } }] } }' ``` ### Step 3. Accept payments using the token Send a request to accept a payment with the `recurrent` payment type. Instead of a bank card, pass the token you saved after the previously accepted payment. Example of a request for a recurring payment ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Customer; $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() ->initPaymentSession() // highlight-next-line ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39') ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->build(); $response = $client->session()->initPayment($request); ``` --- - [Refunds](https://developer.131.ru/en/payments/payment-refund): Total, partial refunds, and refunds from reimbursements You can return a successful payment to the sender as follows: - Within the **refund** operation – this is the most commonly encountered situation, the payment can be returned totally or partially. - Within the **chargeback** procedure – this procedure cannot be initiated by the client, a notification about it is sent by Bank 131. In this case, the amount is withdrawn from the compensation. In both cases, a record is added to the [registry](/finance/finance-payment-daily-report.mdx). ## How to perform a refund ### Step 1. Send a refund request >Please note that you can only send a request for a **refund**, not a **chargeback**. To perform a refund, send a [`session/refund`](/reference/reference-methods.mdx#sessionrefund) request. In the `session_id` field, pass the identifier of the [payment session](/reference/reference-objects.mdx#payment_session) for the payment you need to refund. In `amount_details.amount`, specify the amount of the refund. If you leave this blank, the money will be refunded in full (i.e. for the full amount of the payment in question). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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() ->refundSession('ps_3230') ->build(); $response = $client->session()->refund($request); ``` ### Step 2. Wait to be notified of the results of the refund After the refund has been issued, Bank 131 will send you a [`payment_refunded`](/reference/reference-webhooks.mdx#payment_refunded) webhook with the results. Webhook example ```json showLineNumbers curl - X POST \ https: //partner.ru \ -H 'Content-Type: application/json'\ - -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "amount_details": { "amount": 1000, "currency": "rub" } }], "transaction_info": { "fp_message_id": "A50581324524670W0000040011450701" } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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_REFUNDED) { $session = $hook->getSession(); //do your logic here } ``` --- - [SberPay with a QR code](https://developer.131.ru/en/payments/payment-sber-pay-qr): Payments via SberPay with QR codes This scenario describes how to receive payments via SberPay with QR codes. These payments do not require card details from customers. >Do not forget to generate QR codes and provide them to customers. >You should confirm a payment within 20 minutes by sending [`session/confirm`](/reference/methods#sessionconfirm). Otherwise, the session terminates within 20 minutes with the `canceled` status. ### Payment scenario 1. Create a separate session using the [`session/create`](/reference/methods#sessioncreate) method, or create a session with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) method. Both methods should pass the required settings including the payment channel within the `channel` setting and URL to forward the customer to a Sber application within the `return_url` setting. >The [`session/start/payment`](/reference/methods#sessionstartpayment) method is required to be sent after you created a separate session. 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. 3. Confirm your payment by sending a [`session/confirm`](/reference/methods#sessionconfirm) request, or cancel the payment sending a [`session/cancel`](/reference/methods#sessioncancel) request. >_You can also use the [`sberpay/push`](/reference/methods#sberpaypush) method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber)._ 4. Wait for an [`action_required`](/reference/webhooks#action_required) webhook containing a deeplink passed within the `redirect.url` parameter, generate a QR code from this deeplink, and forward the customer to a Sber mobile application (**Sberbank Online** or **SBOL**). 5. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the `return_url` parameter. 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the transaction results. You can also send requests (1 time or less in 5 seconds) to obtain the transaction status. >If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the lifetime of the customer's order ends. 7. Pass the transaction status to the customer. QR code payment request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", // highlight-next-line "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "mobile_web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://t.me/bank131" } }' ``` QR code payment response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` ![](/img/docs/payments/sberpay_qr_en.png) --- - [SberPay](https://developer.131.ru/en/payments/payment-sber-pay): Payments via SberPay This scenario describes how to receive payments via SberPay. These payments, one-time and recurring, do not require card details from customers. >You should confirm a payment within 20 minutes by sending [`session/confirm`](/reference/methods#sessionconfirm). Otherwise, the session terminates within 20 minutes with the `canceled` status. ### Payment scenario The payment scenario depends on the customer's payment channel: mobile application (app), mobile browser (mobile_web), or desktop browser (web). 1. Create a separate session using the [`session/create`](/reference/methods#sessioncreate) method, or create a session with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) method and pass all the required parameters, including the following ones: - `sber_pay` in the `type` parameter - `app` in the `channel` parameter >The [`session/start/payment`](/reference/methods#sessionstartpayment) method is required to be sent after you created a separate session. 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. 3. Confirm your payment by sending a [`session/confirm`](/reference/methods#sessionconfirm) request, or cancel the payment sending a [`session/cancel`](/reference/methods#sessioncancel) request. >_You can also use the [`sberpay/push`](/reference/methods#sberpaypush) method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber). Note that it is not recommended to use the `sberpay/push` method with `channel = app`. In this case, Bank 131 cannot guarantee a successful payment._ 4. Bank 131 will send you an [`action_required`](/reference/webhooks#action_required) webhook containing a URL within `redirect.url` to forward the customer to a Sber mobile application. 5. For iOS devices, forward the customer by the deeplink passed within the `redirect.url` parameter to a Sber mobile application. Use the algorithm below to select the proper mobile application to forward the customer: 1. Open the `onlineios-app://sbolpay/...` deeplink. 2. Wait 50ms. 3. Reload the page to hide a possible alert if the deeplink could not open properly. 4. Redirect back to your page with the new request settings. 5. Open the `startonline://sbolpay/...` deeplink. 6. Wait 50ms. 7. Reload the page to hide a possible alert if the deeplink could not open properly. 8. Redirect back to your page with the new request settings. 9. Open the `onlineappmobile://sbolpay....` deeplink. 10. Wait 50ms. 11. Reload the page to hide a possible alert if the deeplink could not open properly. 12. Redirect back to your page with the new request settings. 13. Open the `budgetonline-ios://sbolpay/...` deeplink. 14. Wait 50ms. 15. Reload the page to hide a possible alert if the deeplink could not open properly. 16. Redirect back to your page with the new request settings. 17. Open the `btripsexpenses://sbolpay/...` deeplink. 18. Wait 50ms. 19. Reload the page to hide a possible alert if the deeplink could not open properly. 20. Redirect back to your page with the new request settings. 21. Open the `ios-app-smartonline://sbolpay/...` deeplink. 22. Wait 50ms. 23. Reload the page. 24. Follow the deeplink to the Sber landing page. 6. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the `return_url` parameter. 7. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the transaction results. You can also send requests (no more than once in 5 seconds) to obtain the transaction status. >If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the customer's order expires. 8. Pass the transaction status to the customer. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "sber_pay", "sber_pay": { "phone": "71234567890", // highlight-next-line "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://t.me/bank131" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` ![](/img/docs/payments/sberpay_app_en.png) 1. Create a separate session using the [`session/create`](/reference/methods#sessioncreate) method, or create a session with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) method and pass all the required parameters, including the following ones: - `sber_pay` in the `type` parameter - `mobile_web` in the `channel` parameter >The [`session/start/payment`](/reference/methods#sessionstartpayment) method is required to be sent after you created a separate session. 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. 3. Confirm your payment by sending a [`session/confirm`](/reference/methods#sessionconfirm) request, or cancel the payment sending a [`session/cancel`](/reference/methods#sessioncancel) request. >_You can also use the [`sberpay/push`](/reference/methods#sberpaypush) method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber). 4. Bank 131 will send you an [`action_required`](/reference/webhooks#action_required) webhook containing a URL within `redirect.url` to forward the customer to a Sber mobile application. For iOS devices, forward the customer by the deeplink passed within the `redirect.url` parameter to a Sber mobile application. Use the algorithm below to select the proper mobile application to forward the customer: 1. Open the `onlineios-app://sbolpay/...` deeplink. 2. Wait 50ms. 3. Reload the page to hide a possible alert if the deeplink could not open properly. 4. Redirect back to your page with the new request settings. 5. Open the `startonline://sbolpay/...` deeplink. 6. Wait 50ms. 7. Reload the page to hide a possible alert if the deeplink could not open properly. 8. Redirect back to your page with the new request settings. 9. Open the `onlineappmobile://sbolpay....` deeplink. 10. Wait 50ms. 11. Reload the page to hide a possible alert if the deeplink could not open properly. 12. Redirect back to your page with the new request settings. 13. Open the `budgetonline-ios://sbolpay/...` deeplink. 14. Wait 50ms. 15. Reload the page to hide a possible alert if the deeplink could not open properly. 16. Redirect back to your page with the new request settings. 17. Open the `btripsexpenses://sbolpay/...` deeplink. 18. Wait 50ms. 19. Reload the page to hide a possible alert if the deeplink could not open properly. 20. Redirect back to your page with the new request settings. 21. Open the `ios-app-smartonline://sbolpay/...` deeplink. 22. Wait 50ms. 23. Reload the page. 24. Follow the deeplink to the Sber landing page. 5. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the `return_url` parameter. 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the transaction results. You can also send requests (no more than once in 5 seconds) to obtain the transaction status. >If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the customer's order expires. 7. Pass the transaction status to the customer. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "sber_pay", "sber_pay": { "phone": "71234567890", // highlight-next-line "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "mobile_web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://t.me/bank131" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` ![](/img/docs/payments/sberpay_webmobile_en.png) 1. Create a separate session using the [`session/create`](/reference/methods#sessioncreate) method, or create a session with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) and pass all the required parameters, including the following ones: - `sber_pay` in the `type` parameter - `web` in the `channel` parameter - the URL to forward the customer to in the `return_url` parameter. >The [`session/start/payment`](/reference/methods#sessionstartpayment) method is required to be sent after you created a separate session. 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. 3. Confirm your payment by sending a [`session/confirm`](/reference/methods#sessionconfirm) request, or cancel the payment sending a [`session/cancel`](/reference/methods#sessioncancel) request. >_You can also use the [`sberpay/push`](/reference/methods#sberpaypush) method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber)._ 4. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the `return_url` parameter. 5. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the transaction results. You can also send requests (no more than once in 5 seconds) to obtain the transaction status. >If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the customer's order expires. 6. Pass the transaction status to the customer. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-start "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "web" // highlight-end } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` ![](/img/docs/payments/sberpay_web_en.png) ### Selecting a proper deeplink for Sber iOS mobile applications #### Code example Code example for selection logic implementation ```c showLineNumbers const openOnlineiosApp = () => { window.location.href = "onlineios-app://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openStartOnline = () => { window.location.href = "startonline://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openAppOnline = () => { window.location.href = "onlineappmobile://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openBuget = () => { window.location.href = "budgetonline-ios://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openBtripExp = () => { window.location.href = "btripsexpenses://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openAppSmart = () => { window.location.href = "ios-app-smartonline://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openLandingpage = () => { window.location.href = "https://www.sberbank.ru/ru/person/payments/online_sberpay"; }; const clearMessage = () => { window.location.href = "./same_page.html"; }; if (platform == "android") { setTimeout(openSberpay, 100); clearMessage(); setTimeout(openLandingpage, 800); } else if (platform == "iPhone") { setTimeout(openOnlineiosApp, 50); clearMessage(); setTimeout(openStartOnline, 50); clearMessage(); setTimeout(openAppOnline, 50); clearMessage(); setTimeout(openBuget, 50); clearMessage(); setTimeout(openBtripExp, 50); clearMessage() setTimeout(openAppSmart, 50); clearMessage(); setTimeout(openLandingpage, 800); } ``` ### Recurring payments >CIT recurring payments via SberPay are not supported. To make [MIT recurring payments](/payments/payment-recurring) via SberPay: 1. Get a token by sending `recurrent=true` (in the [`payment_options`](/reference/objects#payment_options) object) in the request. If the payment is successful, you will get the token in the [`payment_finished`](/reference/webhooks#payment_finished) webhook in the `recurrent.token` parameter. Example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "return_url": "https://t.me/bank131", // highlight-next-line "recurrent": "true" } }' ``` 2. Use the token to make recurring payments. Example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", // highlight-next-line "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" } }' ``` --- - [Payment process](https://developer.131.ru/en/payments/payment-scenarios): Payments with holding, open data, and through the payment form ## How you can perform payments - through the payment form - with open parameters - with delayed capture ## The payment session All API operations are carried out within a payment session: [`session`](/reference/reference-objects.mdx#payment_session). One payment session can include several operations: for example, you can accept and then refund a payment. You can send payments using one of the two options: - initiating the payment when you start a session (as a single request [`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment)) - starting a session and then performing a payment (as two requests, [`session/create`](/reference/reference-methods.mdx#sessioncreate) and [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment)) e.g. to call the payment form widget or just to obtain the session identifier and use it to monitor what is happening with the payment. ## Main payment scenario 1. You create a payment session: - separately from the payment itself ([`session/create`](/reference/reference-methods.mdx#sessioncreate)), which is mandatory if you are going to perform the payment using the payment form widget; - or simultaneously with the payment ([`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment)). >#### These steps are necessary only when paying with the widget > >2. If you are going to connect the [payout form widget](/payments/widget-payment.mdx), you will need to send a request for token creation to access the JavaScript library. >3. Show the widget to the user and obtain their card details. 4. **If you are not using the widget** and have created the session separately from the start of the payment, you need to send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request. 5. Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook, which means that the Bank is ready to make the payment and is waiting for your confirmation. 6. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). >#### These steps are necessary only when paying without the widget >7. If you are making a payment without a payment form, Bank 131 will send you an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook. This means that you will need to take additional action to perform the payment. For instance, the user might need to go through 3D Secure. >8. Redirect the user to the address for payment confirmation (3D Secure). >#### These steps are only required for delayed capture payments >Upon a delayed capture payment, funds are frozen on the user card and debited on your command. If you don't want to perform delayed capture payments, you can skip these steps. To follow this scenario, contact a Bank 131 manager. >9. Bank 131 will send you a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook. This means the funds to be used for the payment are frozen on the user's bank card. >10. Debit the captured amount ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) or cancel the hold ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). 11. Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. ## Payment statuses The status of the payment is returned in the `status` field of the [`acquiring_payments`/`payment_list`](/reference/objects#payment_status) array. To query it, wait for a webhook from Bank 131 or send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request with the identifier of the session containing this payment. --- - [Payments via T-Pay](https://developer.131.ru/en/payments/payment-tpay): Payments via T-Pay During payments via T-Pay the payer authentication is performed through logging into the T-Bank app. Customers do not have to enter card details to make payments. You can accept T-Pay payments in two ways: * with a QR code, which works for payments made from a desktop browser (**generate and display the QR code on your own**) * with a URL to the T-Bank application, which works for payments made from a mobile device >After being redirected by the URL, the payer will have 20 minutes to complete the payment. Otherwise, the session terminates within 20 minutes with the `canceled` status. ### Payment scenario The payment scenario depends on the customer's payment channel: mobile device (mobile) or desktop browser (desktop). The client device properties in the request define the format of the payment link in the `action_required` webhook. 1. Create a session separately using the [`session/create`](/reference/methods#sessioncreate) method and then start the payment ([session/start/payment](/reference/methods#sessionstartpayment)), or create a session along with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) method. Pass all the required parameters: - Pass the `tpay` value in the `type` parameter of the [`internet_banking`](/reference/objects#internet_banking) object. - Pass the `mobile` value in the `type` parameter of the [`platform_details`](/reference/objects#platform_details) object. Specify one of the acceptable values in the `os` and `browser` parameters. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-start "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } // highlight-end } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:14:28.236854Z", "updated_at": "2025-09-05T07:14:28.298522Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-05T07:14:28.310910Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } ``` 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. 3. Confirm your payment by sending a [`session/confirm`](/reference/methods#sessionconfirm) request, or cancel the payment sending a [`session/cancel`](/reference/methods#sessioncancel) request. 4. Bank 131 will send you an [`action_required`](/reference/webhooks#action_required) webhook containing a URL within `redirect.url` to forward the customer to the T-Bank mobile application. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:49:12.513214Z", "updated_at": "2025-09-05T07:49:24.628403Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "pending", "created_at": "2025-09-05T07:49:12.605322Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://o.tbank.ru/tpay/3000000000000021275", "base_url": "https://o.tbank.ru/tpay/3000000000000021275", "method": "GET", "params": {} } } }], "actions": { "confirm": "2025-09-05T07:49:24.148058Z" } } }' ``` 5. Forward the customer by the link passed within the `redirect.url` parameter to the T-Bank mobile application. Wait until the customer approves or cancels the payment. 6. Wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook and capture the amount that is on hold in full or partially ([`session/capture`](/reference/methods#sessioncapture)), or decline the payment ([`session/cancel`](/reference/methods#sessioncancel)). >Skip this step if you do not have [delayed capture payments](/payments/payment-hold) enabled. In this case, the hold and capture will be made automatically. 7. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the payment result from Bank 131. The `succeeded` status indicates a successful payment. ![](/img/docs/payments/tpay_mobile_en.png) 1. Create a separate session using the [`session/create`](/reference/methods#sessioncreate) method and then start the payment ([session/start/payment](/reference/methods#sessionstartpayment)), or create a session along with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) method. Pass all the required parameters: - Pass the `tpay` value in the `type` parameter of the [`internet_banking`](/reference/objects#internet_banking) object. - Pass the `desktop` value in the `type` parameter of the [`platform_details`](/reference/objects#platform_details) object. Specify one of the acceptable values in the `os` and `browser` parameters. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-start "platform_details": { "type": "desktop", "os": "windows", "browser": "chrome" } // highlight-end } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:14:28.236854Z", "updated_at": "2025-09-05T07:14:28.298522Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-05T07:14:28.310910Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } ``` 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. 3. Confirm your payment by sending a [`session/confirm`](/reference/methods#sessionconfirm) request, or cancel the payment sending a [`session/cancel`](/reference/methods#sessioncancel) request. 4. Bank 131 will send you an [`action_required`](/reference/webhooks#action_required) webhook containing a URL for QR code within `redirect.url`. Generate and display the QR code to the payer on your own. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:49:12.513214Z", "updated_at": "2025-09-05T07:49:24.628403Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "pending", "created_at": "2025-09-05T07:49:12.605322Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { // highlight-next-line "url": "https://www.tinkoff.ru/tpay/3000000000000021275", "base_url": "https://www.tinkoff.ru/tpay/3000000000000021275", "method": "GET", "params": {} } } }], "actions": { "confirm": "2025-09-05T07:49:24.148058Z" } } }' ``` 5. Display the link passed within the `redirect.url` parameter as a QR code. Wait until the customer approves or cancels the payment. 6. Wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook and capture the amount that is on hold in full or partially ([`session/capture`](/reference/methods#sessioncapture)), or decline the payment ([`session/cancel`](/reference/methods#sessioncancel)). >Skip this step if you do not have [delayed capture payments](/payments/payment-hold) enabled. In this case, the hold and capture will be made automatically. 8. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the payment result from Bank 131. The `succeeded` status indicates a successful payment. ![](/img/docs/payments/tpay_desktop_en.png) ### Recurring payments To perform [MIT recurring payments](/payments/payment-recurring) or [CIT recurring payments](/payments/payment-recurring-cit) via T-Pay: 1. Get a token by sending `recurrent=true` (in the [`payment_options`](/reference/objects#payment_options) object) in the request. If the payment is successful, you will get the token in the [`payment_finished`](/reference/webhooks#payment_finished) webhook in the `recurrent.token` parameter. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { // highlight-next-line "recurrent": true, "type": "mobile", "os": "ios", "browser": "chrome" } } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3813071", "status": "in_progress", "created_at": "2025-09-05T07:24:45.996726Z", "updated_at": "2025-09-05T07:24:46.081328Z", "acquiring_payments": [{ "id": "pm_2769427", "status": "in_progress", "created_at": "2025-09-05T07:24:46.108909Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {}, "payment_options": { "recurrent": true } }] } } ``` 2. Use the token to make recurring payments. Examples ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", "initiator":"merchant" // highlight-end } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "android", "browser": "chrome" } } }' ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3812845", "status": "in_progress", "created_at": "2025-09-03T11:04:27.322539Z", "updated_at": "2025-09-03T11:04:27.381848Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-03T11:04:27.394705Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } ``` ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", "initiator":"client" // highlight-end } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } } }' ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-03T11:04:27.322539Z", "updated_at": "2025-09-03T11:04:27.381848Z", "acquiring_payments": [{ "id": "pm_2769254", "status": "in_progress", "created_at": "2025-09-03T11:04:27.394705Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } ``` ## How to make a refund To make refunds using T-Pay, follow the [standard procedure](/payments/payment-refund.mdx). --- - [Payments using our payment form](https://developer.131.ru/en/payments/payment-with-form): Payments for those who do not store card details on their side This scenario describes how to perform a payment to a bank card through the payment form. You should consider this option if you decided not to collect bank card details and not to store them on your side. You can obtain tokenized card details using the [payment form widget](/payments/widget-payment.mdx) and then perform the payment securely. > This scenario does not include the payment capture step. [How to make a delayed capture payment](/payments/payment-hold) 1. Create a payment session ([`session/create`](/reference/reference-methods.mdx#sessioncreate)). You will receive a payment session identifier in response. [More about request format >](/reference/reference-format.mdx) Creating a session ```json showLineNumbers 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 '{ "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }' ``` ```php showLineNumbers 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() ->createPaymentSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` 2. Generate a public token to work with the widget. Send a [`token`](/reference/reference-methods.mdx#token) request specifying in it the session identifier and the type of the widget you are going to call. You will receive a token in response. > If you want to add the checkbox **Enable Automatic Payments** to the payment form, specify `true` in the `show_recurrent_checkbox` field. It's required to perform [recurring debiting](/payments/payment-recurring.mdx). Request example ```json showLineNumbers 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: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_123456" } }' ``` ```php showLineNumbers 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() ->setAcquiringWidget( 'test_ps_id', 'http://success.url', 'http://failed.url', false ) ->build(); $publicTokenResponse = $client->widget()->issuePublicToken($request); $publicToken = $publicTokenResponse->getPublicToken(); ``` 3. Show the payment form to the recipient. To do this, you need to access our JavaScript library and add the payment form widget. The customer enters their card details and clicks **Pay**, and Bank 131 initiates the payment, without getting you involved. [How to add the payment form >](/payments/widget-payment.mdx) 4. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook—this means that the payment can be performed and the Bank is waiting for you to confirm (or cancel). The webhook body will contain all the data needed for the payment, which you need to check. You then reply with the 200 HTTP code. Webhook example ```json showLineNumbers 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", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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 } ``` 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. >If you receive an `action_required` webhook, send the HTTP 200 OK in response—the user will be redirected for 3D Secure within the widget. Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` 6. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The webhook body will contain all the details of the payment. The result of the payment can be found in the `status` field of the `acquiring_payments/payment_list` array. If the status is `succeeded`, then the payment has been successful. If the status is `failed`, then the payment has not been completed because of an [error](/reference/reference-errors.mdx). [More about the payment statuses >](/reference/reference-objects.mdx#payment_status) ## Diagram for payment via payment form ![Diagram for payment via payment form](/img/docs/payments/schema_payment_with_formNOHOLD_en.png) --- - [Payments with YooMoney wallets](https://developer.131.ru/en/payments/p-yoomoney): Payments with YooMoney wallets You can accept payments with YooMoney wallets, including: - [one-time payments](#yoo_payment) - [recurring payments](#r-payments) - [delayed capture payments](/payments/payment-hold) Payments made with YooMoney wallets are refunded in [a standard way](/payments/payment-refund). ## How to make a payment All parameters are passed in plain text. Do not use our widgets. 1. Send a [`/session/init/payment`](/reference/methods#sessioninitpayment) request. Optionally, you can pass a URL in `payment_options.return_url` for redirecting the payer back after the payment. >The payment amount limits depend on the [YooMoney wallet level](https://yookassa.ru/docs/support/payments/limits). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} // highlight-end } }, "amount_details": { "amount": 25420, "currency": "rub" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, // highlight-start "payment_options": { "return_url": "https://www.131.ru", "description": "description" // highlight-end } }' ``` 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:33:46.290108Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "next_action": "confirm" } }' ``` 3. Confirm ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel ([`session/cancel`](/reference/methods#sessioncancel)) the payment. 4. Wait for an [`action_required`](/reference/webhooks#action_required) webhook from Bank 131 and redirect the payer using the link from `customer_interaction.redirect.url`. :::info After the `action_required` webhook arrives, the payer has 20 minutes to confirm the payment. ::: Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:34:31.887997Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, // highlight-start "customer_interaction": { "type": "redirect", "redirect": { "url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=309d1fd7-000f-5001-8000-1e9f64506f41", "base_url": "https://yoomoney.ru/checkout/payments/v2/contract", "method": "GET", "qs": { "orderId": "309d1fd7-000f-5001-8000-1e9f64506f41" }, "params": {} } }, // highlight-end "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z" } } }' ``` 5. If you make delayed capture payments, wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook and then either confirm ([`session/capture`](/reference/methods#sessioncapture)) or cancel ([`session/cancel`](/reference/methods#sessioncancel)) the capture. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:44:33.115425Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "next_action": "capture", "actions": { "confirm": "2025-11-05T08:34:31.626530Z" } } }' ``` 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook. See the payment results in the `status` parameter of the `acquiring_payments/payment_list` array. If the status is `succeeded`, the payment was successful. If the status is `failed`, an [error](/reference/errors) occurred during the payment. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3821809", "status": "accepted", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:45:19.857746Z", "acquiring_payments": [{ "id": "pm_2775568", // highlight-next-line "status": "succeeded", "created_at": "2025-11-05T08:33:46.190121Z", "finished_at": "2025-11-05T08:45:19.781451Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 5000, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z", "capture": "2025-11-05T08:45:18.934056Z" } } }' ``` ## Recurring payments >CIT recurring payments with YooMoney wallets are not supported. To make [MIT recurring payments](/payments/payment-recurring) with YooMoney wallets: 1. Get a token by sending `recurrent=true` in the [`payment_options`](/reference/objects#payment_options) object. If the payment is successful, you will get the token in the [`payment_finished`](/reference/webhooks#payment_finished) webhook in the `recurrent.token` parameter. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} // highlight-end } }, "amount_details": { "amount": 25420, "currency": "rub" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_options": { "return_url": "https://www.131.ru", "description": "description", // highlight-start "recurrent": "true" // highlight-end } }' ``` 2. Use the token to make recurring payments. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", // highlight-next-line "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] } }' ``` ### Payment diagram ![](/img/docs/payments/yoomoney_en.png) ```plantuml @startuml autonumber "[00]" skinparam maxMessageSize 200 actor "Payer" as actor participant "Partner" as mer participant "Bank131" as 131 participant "YooMoney" as ym actor->mer: chooses YooMoney as a payment method mer->131: ""/session/init/payment"" note left URL for redirecting the payer back after the payment in ""payment_options.return_url"" end note mer131: http 200 mer->131: ""/session/confirm"" mer131: http 200 mer->actor: redirects the payer to the payment page actor->ym: follows the link, logs in actor->ym: upgrades the wallet level if required actor->ym: confirms the payment actor131: http 200 mer->131: ""/session/capture"" mer131: http 200 @enduml ``` --- - [Payment form widget](https://developer.131.ru/en/payments/payment-widget): Conducting payments with the widget You can use the payment form widget to perform payouts. You add the widget to the page, show it to the user, and the user then interacts with the widget, going through all the payment steps from beginning to end. The user first securely enters their card details, and then sees a message telling them that the payment has been successful (or an error message if anything goes wrong). You need to create a payment session, and the widget does the rest: it will send the payment request, redirect the user to the appropriate address, and show them the screen with the result of the operation. [How to perform a payment through the payment form >](/payments/payment-with-form.mdx) ## What the widget looks like Regular widget With a checkbox for enabling recurring payments With no **Cardholder** field ## Code example: a page with a widget ```html showLineNumbers Payment form widget document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131PaymentForm) { return; } const paymentForm = new Bank131PaymentForm('publicToken', { isCvcMasked: true, hideCardHolderField: false, customerInteractionRedirect: { target: "_blank", }}); paymentForm.render(); }); ``` ## How to add a widget to a page #### 1\. Link the scripts and styles ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2\. Add a container with the widget ```html showLineNumbers ``` #### 3\. Create an instance of the widget Once the script is linked to the page, the `Bank131PaymentForm` class will appear in the global scope. To create the payment form, pass the public token obtained to work with the widget to the constructor (the [`token`](/reference/reference-methods.mdx#token) method). ```js showLineNumbers const paymentForm = new Bank131PaymentForm('public token'); ``` To display the payment form, call the `render()` method: ```js showLineNumbers paymentForm.render(); ``` ## Widget API ### `Bank131PaymentForm` Payment form class constructor. ```js showLineNumbers const paymentForm = new Bank131PaymentForm(publicToken[, options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------- | | `publicToken` | string | Mandatory. Public token | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the form will be inserted. Default value: ``| ### Method: `paymentForm.render()` The method displays the form on the page, in the container defined by the `options.container` parameter. ```js showLineNumbers paymentForm.render([options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------- | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the form will be inserted. Default value: ``| ### Event handler: `paymentForm.onReady` Handles the event of the form becoming ready for work. ```js showLineNumbers paymentForm.onReady = function () { /* handler */ } ``` ### Event handler: `paymentForm.onPaymentStart` Handles the event occurring at the start of the payment process. ```js showLineNumbers paymentForm.onPaymentStart = function () { /* handler */ } ``` ### Event handler: `paymentForm.onPaymentSuccess` Handles the event occurring when the payment process finishes successfully. ```js showLineNumbers paymentForm.onPaymentSuccess = function () { /* handler */ }; ``` ### Event handler: `paymentForm.onPaymentFail` Handles the event occurring when the payment process finishes unsuccessfully. ```js showLineNumbers paymentForm.onPaymentFail = function (error) { /* handler */ } ``` ### Event handler: `paymentForm.onDestroy` Handles the event of the widget getting closed. ```js showLineNumbers paymentForm.onDestroy = () => { /* handler */ } ``` ## Widget customization ### Hide CVV/CVC details You can customize the CVV/CVC field of the widget to make it display only the latest digit entered by customers and mask the others entered before with *. To do this, add the `isCvcMasked` flag into the widget constructor, as follows: ``` js showLineNumbers const paymentForm = new Bank131PaymentForm('publicToken', { isCvcMasked: true, }); ``` ### Open the 3D Secure window as required You can choose how to open the 3D Secure window for the user. Use the `target` parameter of the `customerInteractionRedirect ` object with the following options: - `_blank` — in a new tab - `_self` — in the same frame - `_parent` — in the next-level frame if the frames are nested in one another - `_top` — outside of all the frames as the top window Default: `_top`. >Note that: >- We do not recommend using the `_self` option for security reasons. >- If you use the `_blank` option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget. ### Hide the cardholder name To hide the **Cardholder** filed, pass `hideCardHolderField: true`. By default, the field is shown. ### Appearance You can link your own styles after the library ones and override them, like this: ``` html showLineNumbers ``` Or this: ```css showLineNumbers /* custom-styles.css */ .bank131-Field__label { color: green; } ``` > You cannot yet change the appearance of the values entered inside the iframe. This functionality will be added later. Also, you can modify texts of the widget UI elements. Here are what you can change: - labels - placeholders - error messages - prompt texts - button names - footer texts To do that, you should pass the `Options` object with UI elements parameters within the [Bank131PaymentForm](#bank131paymentform) widget constructor. | Widget UI element | Parameter name | Type | Default value | | ---------------------------------------------------------------------------------- | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------- | | Widget text settings | `texts` | object | | | Failed payment message | `failedPaymentScreen` | string | `Ошибка` | | Payment form | `paymentForm` | object | | | Payment button name | `buttonPayLabel` | string | `Оплатить` | | Cardholder name text | `cardholderLabel` | string | `Владелец карты` | | Cardholder name prompt text | `cardholderNote` | string | None | | Cardholder name placeholder | `cardholderPlaceholder` | string | `ИМЯ ФАМИЛИЯ` | | Card number | `cardNumberLabel` | string | `Номер карты` | | Card number prompt text | `cardNumberNote` | string | None | | Card number placeholder | `cardNumberPlaceholder` | string | `0000 0000 0000 0000` | | CVV/CVC number | `cvvLabel` | string | `CVC` | | CVV/CVC number prompt text | `cvvNote` | string | None | | CVV/CVC number placeholder | `cvvPlaceholder` | string | `CVC` | | Card expiration date | `expireDateLabel` | string | `Срок действия` | | Card expiration date prompt text | `expireDateNote` | string | `Как на карте` | | Card expiration date placeholder | `expireDatePlaceholder` | string | `ММ/ГГ` | | Recurring payment checkbox | `recurrentLabel` | string | `Соглашаюсь на автоплатежи` | | Terms of agreement | | | | | Terms of agreement. The text within the mandatory `{{#link}}{{/link}}` tags is used as a link to the terms of agreement source. | `termsAgreement` | string | `Нажимая кнопку «Оплатить» вы соглашаетесь с условиями {{#link}}пользовательского соглашения{{/link}}` | | Field validation error messages | `validationErrors` | object | | | Invalid card number | `INVALID_CARD_NUMBER` | string | `Неверный номер карты` | | Invalid CVV/CVC | `INVALID_CVV` | string | `Код должен содержать 3 цифры` | | Invalid card expiration date | `INVALID_EXPIRY_DATE` | string | `Неверная дата` | | Required field value is missing | `IS_REQUIRED` | string | `Обязательное поле` | | Payment process page | `paymentProcessScreen` | object | | | Payment processing page text | `description` | string | `Это займет совсем немного времени` | | Payment process screen heading | `title` | string | `Происходит оплата...` | | Redirecting page (3D Secure) | `redirectionScreen` | object | | | Invitation message to proceed with redirection in case of automatic redirection failure. The text within the mandatory `{{#link}}{{/link}}` tags is used as a link. | `followTheLink` | string | `Если этого не произошло, перейдите {{#link}}по ссылке{{/link}}.` | | Payment processing page header | `title` | string | `Происходит оплата...` | | Automatic redirection warning, includes 3 seconds countdown timer. The `{{countdown}}` value is mandatory and will be replaced with the timer.Use the `{{#strong}}{{/strong}}` tags to emphasize the timer in bold. | `waitForRedirectToBanksPage` | string | `Через {{#strong}}{{countdown}} сек.{{/strong}} Вы будете перенаправлены на страницу банка-эмитента.` | | Successful payment page | `successPaymentScreen` | object | | | Successful payment page header | `title` | string | `Успешно` | | Transaction data | `transactionData` | object | | | Transaction amount label | `amountLabel` | string | `Сумма` | | Payment type data (card type and masked card number) label | `creditCardLabel` | string | `Карта` | | Transaction ID label | `transactionIdLabel` | string | `ID транзакции` | | Unknown error message | `unknownError` | string | `Что-то пошло не так...` | An example of code to modify texts: ```javascript showLineNumbers const paymentForm = new Bank131PaymentForm('', { isCvcMasked: true, hideCardHolderField: false, texts: { failedPaymentScreen: { title: 'Error', }, paymentForm: { buttonPayLabel: 'Pay', cardholderLabel: 'Cardholder', cardholderNote: '', cardholderPlaceholder: 'Full name', cardNumberLabel: 'Card number', cardNumberNote: '', cardNumberPlaceholder: '0000 0000 0000 0000', cvvLabel: 'CVC', cvvNote: '', cvvPlaceholder: 'CVC', expireDateLabel: 'Expiration date', expireDateNote: '', expireDatePlaceholder: 'As stated on the card', recurrentLabel: 'I agree to recurring payments', termsAgreement: 'By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}', validationErrors: { INVALID_CARD_NUMBER: 'Invalid card number', INVALID_CVV: 'CVV/CVC has 3 digits', INVALID_EXPIRY_DATE: 'Invalid date', IS_REQUIRED: 'Required field', }, }, paymentProcessScreen: { description: 'Just a moment', title: 'Payment processing...', }, redirectionScreen: { followTheLink: 'If you haven`t been redirected automatically, use {{#link}}this link{{/link}}.', title: 'Payment processing...', waitForRedirectToBanksPage: 'You will be redirected to the issuer bank`s page in {{#strong}}{{count}} seconds.{{/strong}}', }, successPaymentScreen: { title: 'Payment success', }, transactionData: { amountLabel: 'Amount', creditCardLabel: 'Card', transactionIdLabel: 'Transaction ID', }, unknownError: 'Something went wrong...', }, }); ``` ### End user errors While interacting with our widget, end users may receive the errors stated below. >If you choose to translate the widget texts into other languages, for example, Spanish, note that for now end users will receive error descriptions still in English. | Error code | Error description | |------------|-------------------| | `3DS_error` | To complete the transaction successfully, 3DS authentication is required | | `activity_count_exceeded` | The activity/amount limit for the card is exceeded | | `bank_card_expired` | The bank card is past its expiration date | | `declined_by_issuer_bank` | The operation was declined by the emitting bank | | `insufficient_funds` | The card does not have enough funds | --- - [Widget for getting tokenized bank card details](https://developer.131.ru/en/payments/tokenize-widget): Secure transactions with bank cards with the widget --- ## Money Transfers - [Money transfers without opening an account](https://developer.131.ru/en/transfers/transfer-start): Transfers from Russia abroad without opening an account With this feature, individuals can transfer money from Russia abroad without opening an account. ## Countries to which you can make a transfer | Country | Country code | Transfer method | Transfer currency | Limitations | |------------|--------------|-----------------|----------------------|--------------------------| | Kazakhstan | KAZ | Bank card | Tenge (KZT) | No limitations | | Kyrgyzstan | KGZ | Bank card | Som (KGS) | Transfers to Elcart only | | Tajikistan | TJK | Bank card | Somoni (TJS) | No limitations | | Uzbekistan | UZB | Bank card | Uzbekistan sum (UZS) | No limitations | ## Money transfer features :::info - Money transfer operations are only available for individuals 18 years old or older. - When filling in information on the recipient, make sure the data you specify matches the passport the recipient will use to receive the money. ::: Money transfers are processed within multisessions. One multisession combines multiple transactions: write-off (debiting the sender) and payout (crediting to the recipient). The exchange rate is reserved for a limited time (up to 5 minutes). The following terms are used in the documentation: - **Payment partner** – an entity that accepts, transfers, and pays out funds. - **Sender** – an individual who transfers funds. - **Recipient** – an individual who receives the funds transferred from the sender. Note that the sender can be the recipient too in case of a refund or transfer to self. - **Payment** – a transaction within which funds are accepted from the sender. - **Payout** – a transaction within which funds are paid out to the recipient. --- - [Transfers without the card tokenization widget](https://developer.131.ru/en/transfers/transfer-without-widget): Transfers from Russia abroad without card tokenization This scenario describes initiating a money transfer if you decided to obtain and store bank card details on your side (you must comply with the additional PCI DSS requirements). ## Sequence diagram of a money transfer ![Sequence diagram of a money transfer](/img/docs/transfers/money_transfer_new_en.png) ### Step 1. Preliminary rate calculation (optional) Before initiating the transfer, you can request the currency exchange rate using the [`calculate`](/reference/reference-methods.mdx#calculate) method. The conversion may use either a direct or inverse rate, depending on the transfer direction and currencies involved. The response will include the current exchange rate, total debit amount, and payout amount. The rate is provided for reference only and may change. The rate is reserved only after a multisession is started. Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" } } }' ``` Response examples ```json showLineNumbers { "amounts": { "source": { "amount": 357913, "currency": "RUB" }, "destination": { "amount": 131426, "currency": "TRY" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 5400, "currency": "RUB" } }, "exchanges": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" }, "rate": { "fx_rate": 2.7233, "quantity": 1 } } } ``` ```json showLineNumbers { "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 9193, "currency": "RUB" } }, "exchanges": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "rate": { "fx_rate": 76.2433, "quantity": 10000 } } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ### Step 2. Starting the transfer Start the transfer using the [`session/multi/init`](/reference/reference-methods.mdx#session_multi_init) method. Once the multisession is created, the system will perform verifications on the sender, validate the recipient's payout eligibility, calculate and reserve the final exchange rate with the exact debit and payout amounts. The exchange rate is reserved for a maximum of **5 minutes**. If you attempt to complete the transaction after this period, the session will terminate with the `rate_has_changed` [error code](/reference/errors). Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 37700, "currency": "TJS" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "TRY", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TJK", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2204320396205389" } } } }] }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 1000, "currency": "TRY" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "RUS", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "issued_by": "ОВД ПО Кировскому району", "division_code": "123-543" }, "contacts": { "phone": { "full_number": "+992910011020" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 1000, "currency": "TRY" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TRY", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } } }] }' ``` Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808365", "status": "in_progress", "created_at": "2025-08-08T12:39:15.668563Z", "updated_at": "2025-08-08T12:39:16.388348Z", "payout_list": [{ "id": "po_955259", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439833Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765898", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439730Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808544", "status": "in_progress", "created_at": "2025-08-11T07:39:00.076932Z", "updated_at": "2025-08-11T07:39:00.476548Z", "payout_list": [{ "id": "po_955266", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528662Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TRY", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2766065", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528558Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "division_code": "123-543", "issued_by": "ОВД ПО Кировскому району" }, "citizenship_country_iso3": "RUS", "contacts": { "phone": { "full_number": "+992910011020" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook confirming the transfer is ready to process at the specified exchange rate with the final debit and payout amounts. In the webhook, the [`confirm_information`](/reference/reference-objects.mdx#confirm_information).[`exchanges`](/reference/reference-objects.mdx#exchanges) object will contain the current exchange rate and the debit and payout amounts. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_3808364", "status": "in_progress", "created_at": "2025-08-08T12:30:02.616632Z", "updated_at": "2025-08-08T12:30:04.489651Z", "payout_list": [{ "id": "po_955258", "status": "pending", "created_at": "2025-08-08T12:30:03.401467Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765897", "status": "pending", "created_at": "2025-08-08T12:30:03.401320Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "exchanges": [{ "id": "pm_2765897", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 306237, "currency": "RUB" } }, { "id": "po_955258", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }] // highlight-end } }' ``` ### Step 3. Confirming the transfer Check the transfer details and confirm the transfer using the [`session/confirm`](/reference/reference-methods.mdx#sessionconfirm) method. You need to confirm the session within 5 minutes. You can cancel the transfer using the `session/cancel` method. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3808364", "confirm_information": { "exchanges": [{ "id": "pm_2765897", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }, { "id": "po_955258", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }] } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808364", "status": "in_progress", "created_at": "2025-08-08T12:30:02.616632Z", "updated_at": "2025-08-08T12:32:05.891206Z", "payments": [{ "id": "po_955258", "status": "pending", "created_at": "2025-08-08T12:30:03.401467Z", "payment_method": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "acquiring_payments": [{ "id": "pm_2765897", "status": "in_progress", "created_at": "2025-08-08T12:30:03.401320Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }], "actions": { "confirm": "2025-08-08T12:32:05.949621Z" } } } ``` After the session is confirmed, the sender's funds will be frozen for debit, and the debit must be confirmed via 3D Secure: - Wait for an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook with a 3D Secure link and redirect the user to complete 3D Secure. - After successful 3D Secure completion, the funds will be frozen on the sender's card. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", // highlight-start "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", // highlight-end "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ### Step 4. Canceling the transfer (optional) If required, you can cancel the transfer using the [`session/cancel`](/reference/reference-methods.mdx#sessioncancel) method. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3808365" }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3809232", "status": "in_progress", "created_at": "2025-08-11T10:14:54.779728Z", "updated_at": "2025-08-11T10:14:58.370629Z", "payout_list": [{ "id": "po_955280", "status": "pending", "created_at": "2025-08-11T10:14:55.586736Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "citizenship_country_iso3": "TJK" } } }], "payment_list": [{ "id": "pm_2766741", "status": "pending", "created_at": "2025-08-11T10:14:55.586645Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` Wait for a `payment_finished` webhook with `status` = `cancelled`. The session is canceled. Create a new session if you need to restart the transfer. ### Step 5. Payout to the recipient Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook with `status` = `accepted`. Upon successful payout, the frozen amount will be debited from the sender. If an error occurs during the transfer process, the `payment_finished` webhook will contain an error code. [View error codes >](/reference/errors) Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", // highlight-next-line "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [ { "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 } ], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` --- ## Escrow Account - [Escrow account API](https://developer.131.ru/en/escrow-account/escrow-intro): Escrow account for operations with beneficiaries' funds If you use an escrow account, you regularly make payouts, check balances, monitor incoming payments, and more. Use the Bank 131 API to automate these operations. ### Features - Beneficiary identification. [Identify individual beneficiaries](/escrow-account/verification-intro) before payouts. - Payouts. To bank cards ([by card number](/escrow-account/escrow-payout-cards), [with our widget or by token](/escrow-account/escrow-payout-tokenized-card)), to Russian bank accounts ([by account number](/escrow-account/escrow-payout-accounts), [with our widget or by token](/escrow-account/escrow-payout-tokenized-accounts)), and also [by phone number via FPS](/payouts/payout-fps-phone#payout-nominal). - Balance info. Check your escrow account balance using the [`account_balance`](/statements/statements-balance) method. - Account statements. Request a statement on all transactions for any particular day using the [`report/account_statement`](/statements/statements-escrow) method. - Top-up notifications. Enable the [`nominal_topup`](/reference/webhooks#nominal_topup) webhook to receive instant notifications on your escrow account top-ups. ### Accounts for payouts Accounts allowed for payouts from escrow accounts ### General scenario on how to work with an escrow account Working with an escrow account via the API generally involves the following steps: 1. Verify beneficiaries. 2. Replenish your escrow account. 3. Make a payout. Note that the scenario may vary in some steps depending on the escrow account agreement. --- - [Payouts from an escrow account by account number](https://developer.131.ru/en/escrow-account/escrow-payout-accounts): Sending payments to legal entities, individuals and self-employed individuals to accounts in Russian banks You can make payouts to bank accounts from an escrow account as follows: - [as a standard payout](#payout_account)—the money will be credited within a period from 2 hours to 3 banking days (this depends on the recipient's bank) - [as a speedy payout through the BESP system](/payouts/payout-account-sistema-besp)—the money will be credited within an hour Before initiating a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) ### Making a standard payout #### Step 1. Create a payment session Create a session using the [`session/create/nominal`](/reference/methods#sessioncreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/escrow-account/russian-account-parameters) and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Send the payout Send a [`session/start/payout/nominal`](/reference/methods#sessionstartpayoutnominal) request, specifying the session identifier alongside the [payout parameters](/escrow-account/russian-card). Example of a payout by account number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "inn": "1111111111", "kpp": "156605101", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt", "is_fast": false, "kpp": "156605101", "inn": "1111111111" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } }, "payment_options": { "recurrent": false, "is_subsequent": false } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156605101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers 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", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers 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_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to know if a payout is returned >](/payouts/payout-refunds) --- - [Payouts from an escrow account by card number](https://developer.131.ru/en/escrow-account/escrow-payout-cards): Payouts to bank cards of the self-employed, sole proprietors, and individuals To make payouts by card number, you must comply with the PCI DSS standard. Before a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) ### Step 1. Create a payment session Create a session using the [`session/multi/create/nominal`](/reference/reference-methods.mdx#sessionmulticreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/nominal`](/reference/reference-methods.mdx#sessionmultiinitpaymentnominal) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/escrow-account/russian-card) and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ### Step 2. Send the payout Send a [`session/multi/start/payment/nominal`](/reference/reference-methods.mdx#sessionmultistartpaymentnominal) request, specifying the session identifier alongside the [payout parameters](/escrow-account/russian-card). Example of a payout by card number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "5536********8371" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` ### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers 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": "2025-09-14T09:32:19.891392Z", "updated_at": "2025-09-14T09:32:20.494410Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-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" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-09-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) Handling the webhook using SDK ```php showLineNumbers 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 } ``` --- - [Parameters for payouts to Russian bank accounts](https://developer.131.ru/en/escrow-account/russian-account-parameters): Payouts to the self-employed, sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `account` | + | string | Bank escrow account to send the payout from | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `beneficiary_id` | + | string | INN of the beneficiary | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#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` | | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#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](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `full_name` | - (mandatory if the sender is an individual) | string | Sender's 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 (ISO-3166-1 alpha-3) | |       `city` | + | string | City | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters #### Payout purpose example `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ### What next [Payouts by bank account number >](/escrow-account/escrow-payout-accounts) [Payouts using our widget or by token >](/escrow-account/escrow-payout-tokenized-accounts) --- - [Parameters for payouts to Russian bank cards](https://developer.131.ru/en/escrow-account/russian-card): Payouts to Visa, MasterCard, and Mir Which parameters to specify depends on how you send data. Mandatory parameters for payouts to a Russian bank card by token, hash, or via the Bank 131 widget. | Name | Mandatory | Type | Description | |-----------------------------------------------|-------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Values: `encrypted_card` or `tokenized_card` | |       `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Encrypted card details](/reference/reference-objects.mdx#encrypted_card) | |          `number_hash` | + | string | Card number hash | |       `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | |          `token` | + | string | Card number token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (тип, описание) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_nominal_account` | |       `transfer_from_nominal_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_nominal_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | Mandatory parameters for payouts to a Russian bank card by its number. | Name | Mandatory | Type | Description | |-----------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, account, etc.) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Value: `bank_card` | |       `bank_card` | + | object | [Card details](/reference/reference-objects.mdx#bankcard) | |          `number` | + | string | Card number | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (type, description) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_nominal_account` | |       `transfer_from_nominal_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_nominal_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | ### What next [Payouts by card number >](/escrow-account/escrow-payout-cards) [Payouts using our widget or by token >](/escrow-account/escrow-payout-tokenized-card) --- - [Payouts to accounts with our widget or by token](https://developer.131.ru/en/escrow-account/escrow-payout-tokenized-accounts): Payouts in rubles to bank accounts of the self-employed, sole proprietors, and individuals You can make payouts from an escrow account to bank accounts using a token instead of the account number. You can get the token as follows: - using our [`tokenize`](/reference/methods#tokenize) method - using our [widget](/payouts/tokenize-account-widget) Before making a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/create/nominal`](/reference/methods#sessioncreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout/nominal`](/reference/methods#sessionstartpayoutnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Step 1. Create a payment session Create a session using the [`session/create/nominal`](/reference/methods#sessioncreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout/nominal`](/reference/methods#sessionstartpayoutnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Example of a payout by token ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to know if a payout is returned >](/payouts/payout-refunds) --- - [Payouts to cards with our widget or by token](https://developer.131.ru/en/escrow-account/escrow-payout-tokenized-card): Payouts to bank cards of the self-employed, sole proprietors, and individuals You can make payouts from an escrow account to bank cards using a token or a hash instead of the card number. You can get a token/hash as follows: - hash: [using our widget](/payouts/tokenize-widget) - token: using the [`tokenize/elements`](/reference/methods#tokenizeelements) method - token: by [processing a recurring payment](/payments/payment-recurring) The scope of PCI DSS requirements you must comply with depends on the method you choose. Before making a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/multi/create/nominal`](/reference/reference-methods.mdx#sessionmulticreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/nominal`](/reference/reference-methods.mdx#sessionmultiinitpaymentnominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/multi/start/payment/nominal`](/reference/reference-methods.mdx#sessionmultistartpaymentnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-card). :::info You can find information on the hash or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers 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": "2025-05-14T09:32:20.099952Z", "updated_at": "2025-05-14T09:32:20.099911Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-14T09:32:20.099944Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-05-14T09:32:20.099966Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Payout requests require either a token or a hash, depending on what you use. #### Step 1. Create a payment session Create a session using the [`session/multi/create/nominal`](/reference/reference-methods.mdx#sessionmulticreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/nominal`](/reference/reference-methods.mdx#sessionmultiinitpaymentnominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/multi/start/payment/nominal`](/reference/reference-methods.mdx#sessionmultistartpaymentnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-card). :::info You can find information on the token, hash, or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Example of a payout with tokenized data ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers 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": "2025-05-14T09:32:20.094952Z", "updated_at": "2025-05-14T09:32:20.095952Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-14T09:32:20.029952Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": " ", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) --- - [Verification of beneficiaries before payouts](https://developer.131.ru/en/escrow-account/verification-intro): Beneficiary verification For security purposes, Bank 131 is required to identify the beneficiaries associated with an escrow account. The API only supports verification for individual beneficiaries who are resident recipients. To verify other beneficiaries, submit the data to the Bank in an Excel file by any convenient means. ### Verification via the API #### Server address For testing: `https://kyc-stage.bank131.ru/` For live transactions: `https://kyc.bank131.ru/` [Learn more about the request format >](/reference/format) #### Request signature First set up your EECDS: 1. Get the enhanced encrypted and certified digital signature (EECDS) from any verification center. Non-resident individuals can sign their requests using [RSA Keys](/reference/format#request-signature). >For testing, you can create a certificate in the [CryptoPro Test Verification Center](https://www.cryptopro.ru/certsrv). 2. Install [CryptoPro CSP](https://cryptopro.ru/products/csp) and add your certificate to the vault (for example, check this [guide for Windows](https://support.cryptopro.ru/index.php?/Knowledgebase/Article/View/259/0/kk-ustnovit-sertifikt-v-khrnilishhe-lichnoe-s-privjazkojj-k-zkrytomu-kljuchu)). 3. Provide Bank 131 with the list of IP addresses you will use to send requests from. 4. Send the public signature key to your Bank 131 manager so we can identify your requests. You can now sign your requests as follows: 1. Take the `payload` content, sort by key alphabetically, and write to the file using the UTF-8 encoding. Example of writing payload content to a file ```python showLineNumbers import json payload = {...} payload_bytes = bytes(json.dumps(payload, sort_keys=True) + '\r\n', encoding='utf-8') with open('payload_bytes.jsonb', 'wb') as f: f.write(payload_bytes) ``` 2. Sign the file with CryptoPro. You can use the [cryptcp](https://www.cryptopro.ru/products/other/cryptcp) utility. Example of file signing ```js showLineNumbers cryptcp -sign -display -thumbprint -detached payload_json.json payload_json.sig ``` 3. Pass the signature from payload_json.sig in the `signature` field of the request. #### Sending data for verification Send a `check` request with the individual's data. You will get a request ID in the response. Use it [to see the verification result](#errors). #### Request parameters | Name | Mandatory | Type | Description | |---------------------------|-----------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Recipient type: `FL_RESIDENT` | | `last_name` | + | string | Last name | | `first_name` | + | string | First Name | | `patronymic` | - | string | Patronymic | | `birthday` | + | string | Date of birth in the following format: `DD.MM.YYYY`. Should be 18 years old or older | | `birthplace` | + | string | Place of birth | | `citizenship` | + | string | Citizenship in **ISO 3166-1 alpha-2** format | | `inn` | + | string | INN: 12 digits | | `phone_number` | + | string | Phone number (any format) | | `email` | + | string | Valid email address | | `documents` | + | array | Russian passport: `PASSPORT_RF` | |   `type` | + | string | Document type: `PASSPORT_RF` for Russian passport | |   `number` | + | string | Passport series and number in the following format: `1234567890` | |   `issuer` | + | string |Issuing division | |   `issuer_date` | + | string | Date of issue in the following format: `DD.MM.YYYY` | |   `issuer_code` | + | string | Subdivision code | | `address` | + | string | Address of registration | | `postcode` | - | string | ZIP code | | `agent_contract_number` | + | string | Number of the agency agreement with the recipient | | `agent_contract_date` | + | string | Date of the agency agreement with the recipient in the following format: `DD.MM.YYYY`. Must be less than or equal to the current date | | `beneficial_owners` | + | string | Information on beneficiary owners. Always: `No BO` | | `public_officials` | + | string | Status as a public official. Always: `No` | Request example ```json showLineNumbers curl -X POST \ https://kyc.bank131.ru/api/v2/check \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "FL_RESIDENT", "last_name": "Dmitriev", "first_name": "Ivan", "patronymic": "Ivanovich", "birthday": "01.01.1970", "birthplace": "Novgorod", "citizenship": "RU", "inn": "065553161159", "phone_number": "+79000000000", "email": "name@email.com", "documents": [{ "type": "PASSPORT_RF ", "number": "0234567890", "issuer": "UFMS Russia", "issuer_date": "01.01.2010", "issuer_code": "123-000" }], "address": "Novgorod, Pribrezhnaya str., 53", "postcode": "365826", "agent_contract_number": "123456789-0", "agent_contract_date": "01.01.2020", "beneficial_owners": "No BO", "public_officials": "No" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|--------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", "description": "request added to queue" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "partner_project_not_found", "description": "partner project not found" } } ``` Response example for a test request For testing, the value of the `status` field sent in the response strictly depends on the last digit in ID number of the `passport_number` field sent in the request. | Last digit in `passport_number` | `status` value | |---------------------------------|----------------| | Even, including 0 | `ok` | | Odd | `error` | #### Request parameters | Name | Mandatory | Type | Description | |---------------------------|-----------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `last_name` | + | string | Last name | | `first_name` | + | string | First Name | | `patronymic` | - | string | Patronymic | | `birthday` | + | string | Date of birth in the following format:` DD.MM.YYYY`. Should be 18 years old or older | | `birthplace` | + | string | Place of birth | | `inn` | + | string | INN: 12 digits | | `phone_number` | + | string | Phone number (any format) | | `email` | + | string | Valid email address | | `identity_document` | + | string | Document type: `Паспорт гражданина РФ` | | `passport_number` | + | string | Passport series and number in the following format: `1234567890` | | `issuer` | + | string |Issuing division | |   `issuer_date` | + | string | Date of issue in the following format: `DD.MM.YYYY` | |   `issuer_code` | + | string | Subdivision code | | `citizenship` | + | string | Citizenship: `РФ` | | `address` | + | string | Address of registration | | `postcode` | - | string | ZIP code | | `agent_contract_number` | + | string | Number of the agency agreement with the recipient | | `agent_contract_date` | + | string | Date of the agency agreement with the recipient in the following format: `DD.MM.YYYY` | | `beneficial_owners` | + | string | Information on beneficiary owners. Always: `No BO` | | `public_officials` | + | string | Status as a public official. Always: `No` | | `migration_card` | + | string | Always: `-` | | `right_to_stay_in_rf` | + | string | Always: `-` | Request example ```json showLineNumbers curl -X POST \ https://kyc.bank131.ru/api/v1/check \ -H 'x-partner-project: test-partner-project' \ -H 'Content-Type: application/json' \ -H 'accept: application/json' \ -d '{ "payload": { "inn": "065553161159", "email": "name@email.com", "issuer": "UFMS Russia", "address": "53, Pribrezhnaya Alley, Bldg. 9, Bobruisk, 365826", "birthday": "01.01.1970", "postcode": "365826", "birthplace": "Bobruisk", "last_name": "Ivanov", "first_name": "Ivan", "patronymic": "Ivanovich", "citizenship": "РФ", "issuer_code": "123-000", "issuer_date": "01.01.2010", "phone_number": "+79000000000", "migration_card": "-", "passport_number": "0234567890", "public_officials": "No", "beneficial_owners": "No BO", "identity_document": "Паспорт гражданина РФ", "agent_contract_date": "01.01.2020", "right_to_stay_in_rf": "-", "agent_contract_number": "123456789-0" }, "signature": "dkQzYwTExRc0RFWk1CY0dBMVVFQnd3UTBMTXVJTkNjMEw3Ug0NCmd..." }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|--------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", "description": "request added to queue" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "partner_project_not_found", "description": "partner project not found" } } ``` Response example for a test request For testing, the value of the `status` field sent in the response strictly depends on the last digit in ID number of the `passport_number` field sent in the request. | Last digit in `passport_number` | `status` value | |---------------------------------|----------------| | Even, including 0 | `ok` | | Odd | `error` | ### Verification results To get the verification result, use the `check/{id}` method. In the request, specify the ID you received in the response to the `check` request. Result processing may take anywhere from 10 minutes to 2 days. #### Request parameters The request body is empty. Request example ```json showLineNumbers curl -X GET \ https://kyc.bank131.ru/api/v2/check/7 \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|-------------------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `pending`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", // check request ID "description": "valid" } } ``` ```json showLineNumbers { "status": "pending", "data": { "id": "7", "description": "Check in progress" } } ``` Data already verified. ```json showLineNumbers { "status": "error", "error": { "code": "already_exists", "description": "Request with the same data already exists" }, "data": { "id": "7" } } ``` #### Request parameters The request body is empty. Request example ```json showLineNumbers curl -X GET \ https://kyc.bank131.ru/api/v1/check/7 \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|-------------------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `pending`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", // check request ID "description": "valid" } } ``` Send another `check/{id}` request with the same data later. ```json showLineNumbers { "status": "pending", "data": { "id": "7", "description": "Check in progress" } } ``` Data already verified. ```json showLineNumbers { "status": "error", "error": { "code": "already_exists", "description": "Request with the same data already exists" }, "data": { "id": "7" } } ``` ### Error codes and statuses #### HTTP response codes | Code | Description | What you can do | |-------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `200` | Correct request | Check `status` | | `422` | Request error | See `error.description` for details:- `request_body_validation_error` — error in the request body- `request_header_validation_error` — `x-partner-project` header missing | | `500` | Error on Bank 131's side | Try again later | #### Response statuses Response statuses are passed in the `status` field. | Status | Description | Решение | |-----------|--------------------------------|-------------------------------------------------| | `ok` | Request processed successfully | Check `data` | | `pending` | Request is being processed | To find out the result, retry the request later | | `error` | Request processing error | Check `error` | #### Error codes Errors are passed in the `error` object: - `code` — error code - `description` — error description | Code | Description | What you can do | |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `invalid_sign` | `Запрос с указанным идентификатором подписан некорректно` | Verify the request signature is properly generated | | `passport_validation_failure` | `По данным МДВ предоставленный паспорт признан недействительным ` | The passport is invalid. Check the passport data | | `passport_validation_failure` | `В базе данных МВД отсутствуют сведения о предоставленном паспорте` | No information about the passport was found. Check the passport data | | `inn_validation_failure` | `По данным ФНС предоставленный паспорт не соответствует предоставленному ИНН` | The INN value is not linked to the passport specified. Check the INN | | `already_exists` | `Запрос на проверку с теми же данными был направлен ранее` | You have already submitted these data for identification. To see the result, send a `check{id}` request with the previous verification's ID that you received in the `data.id` field | | `request_not_found` | `Не найден запрос с указанным идентификатором` | The request with the given ID was not found. Check the ID | | `partner_project_not_found` | `Не найден проект с указанным в заголовке идентификатором` | The project ID sent in the `X-PARTNER-PROJECT` header does not exist. Check the ID | | `birthday_validation_failure` | `Возраст проверяемого лица ниже допустимого порога` | The verified subject must be an adult. If you receive this error when working with a nominal account, contact your manager | | `validation_error` | Request validation error. Example: `1 validation error for Request.body → payload → documents → 2 → expire_date. Document MIGRATION_CARD is expired (type=value_error)` | Invalid formats and/or controls in values. For detailed information see the `description` field | Response examples ```json showLineNumbers { "status": "error", "error": { "code": "passport_validation_failure", "description": "По данным МДВ предоставленный паспорт признан недействительным" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "passport_validation_failure", "description": "В базе данных МВД отсутствуют сведения о предоставленном паспорте" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "inn_validation_failure", "description": "По данным ФНС предоставленный паспорт не соответствует предоставленному ИНН" } } ``` --- ## Settlement Account - [Settlement account API](https://developer.131.ru/en/settlement-account/settlement-intro): All about working with a settlement account at Bank 131 You can manage your settlement account with Bank 131 API. ### Features - Payouts. To bank cards ([by card number](/settlement-account/settlement-payout-cards), [with our widget or by token](/settlement-account/settlement-payout-tokenized-card)), to Russian bank accounts ([by account number](/settlement-account/settlement-payout-accounts), [with our widget or by token](/settlement-account/settlement-payout-tokenized-accounts)), and also [by phone number via FPS](/payouts/payout-fps-phone). - Balance info. Check your settlement account balance using the [`account_balance`](/statements/statements-balance) method. - Account statements. Request a statement on all transactions for any particular day using the [`report/account_statement`](/statements/statements-escrow) method. ### Accounts for payouts Accounts allowed for payouts from settlement accounts --- - [Payouts from a settlement account by account number](https://developer.131.ru/en/settlement-account/settlement-payout-accounts): Payouts from a settlement account to bank accounts You can make payouts to bank accounts from a settlement account as follows: - [as a standard payout](#payout_account)—the money will be credited within a period from 2 hours to 3 banking days (this depends on the recipient's bank) - [as a speedy payout through the BESP system](/payouts/payout-account-sistema-besp)—the money will be credited within an hour ### Making a standard payout #### Step 1. Create a payment session Create a session using the [`session/create/rko`](/reference/methods#sessioncreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/rko`](/reference/reference-methods.mdx#payout-rko) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/settlement-account/russian-account-parameters) and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Send the payout Send a [`session/start/payout/rko`](/reference/methods#sessionstartpayoutrko) request, specifying the session identifier alongside the [payout parameters](/settlement-account/russian-account-parameters). Example of a payout by account number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Transfer of funds under the agreement for December 2025. VAT exempt." }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 350000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "inn": "1111111111", "kpp": "156605101", "description": "Transfer of funds under the agreement for December 2025. VAT exempt." }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 350000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` #### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt.", "is_fast": false, "kpp": "156605101", "inn": "1111111111" } } }, "amount_details": { "amount": 350000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } }, "payment_options": { "recurrent": false, "is_subsequent": false } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156605101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822029205974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers 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", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers 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_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to know if a payout is returned >](/payouts/payout-refunds) --- - [Payouts from a settlement account by card number](https://developer.131.ru/en/settlement-account/settlement-payout-cards): Payouts from a settlement account to bank cards To make payouts from a settlement account, you must comply with the PCI DSS standard. ### Step 1. Create a payment session Create a session using the [`session/multi/create/rko`](/reference/reference-methods.mdx#sessionmulticreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/rko`](/reference/methods#sessionmultiinitpaymentrko) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/settlement-account/russian-card) and skip the next step. This option is not recommended. Request example ```json showLineNumbers 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: signature' \ -d '{ "metadata": "good" }' ``` ### Step 2. Send the payout Send a [`session/multi/start/payment/rko`](/reference/reference-methods.mdx#sessionmultistartpaymentrko) request, specifying the session identifier alongside the [payout parameters](/settlement-account/russian-card). Example of a payout by card number ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "5536********8371" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` ### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers 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": "2025-09-14T09:32:19.891392Z", "updated_at": "2025-09-14T09:32:20.494410Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-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" }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-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": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) Handling the webhook using SDK ```php showLineNumbers 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 } ``` --- - [Parameters for payouts to Russian bank accounts](https://developer.131.ru/en/settlement-account/russian-account-parameters): Payouts to the self-employed, sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `account` | + | string | Bank escrow account to send the payout from | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#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` | | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#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](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `full_name` | - (mandatory if the sender is an individual) | string | Sender's 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 (ISO-3166-1 alpha-3) | |       `city` | + | string | City | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters #### Payout purpose example `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ### What next [Payouts by bank account number >](/settlement-account/settlement-payout-accounts) [Payouts using our widget or by token >](/settlement-account/settlement-payout-tokenized-accounts) --- - [Parameters for payouts to Russian bank cards](https://developer.131.ru/en/settlement-account/russian-card): Payouts to Visa, MasterCard, and Mir Which parameters to specify depends on how you send data. Mandatory parameters for payouts to a Russian bank card by token, hash, or via the Bank 131 widget. | Name | Mandatory | Type | Description | |-----------------------------------------------|-------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Values: `encrypted_card` or `tokenized_card` | |       `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Encrypted card details](/reference/reference-objects.mdx#encrypted_card) | |          `number_hash` | + | string | Card number hash | |       `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | |          `token` | + | string | Card number token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (тип, описание) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_nominal_account` | |       `transfer_from_nominal_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_nominal_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | Mandatory parameters for payouts to a Russian bank card by its number. | Name | Mandatory | Type | Description | |--------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, account, etc.) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Value: `bank_card` | |       `bank_card` | + | object | [Card details](/reference/reference-objects.mdx#bankcard) | |          `number` | + | string | Card number | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (type, description) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_bank_account` | |       `transfer_from_bank_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_bank_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | ### What next [Payouts by card number >](/settlement-account/settlement-payout-cards) [Payouts using our widget or by token >](/settlement-account/settlement-payout-tokenized-card) --- - [Payouts from a settlement account with our widget or by token](https://developer.131.ru/en/settlement-account/settlement-payout-tokenized-accounts): Payouts in rubles to bank accounts of the self-employed, sole proprietors, and individuals You can make payouts from a settlement account to bank accounts using a token instead of the account number. You can get the token as follows: - using our [`tokenize`](/reference/methods#tokenize) method - using our [widget](/payouts/tokenize-account-widget) #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/create/rko`](/reference/methods#sessioncreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/rko`](/reference/reference-methods.mdx#payout-rko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout/rko`](/reference/methods#sessionstartpayoutrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https:// api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` ```json showLineNumbers curl -X POST \ https:// api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` object. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Step 1. Create a payment session Create a session using the [`session/create/rko`](/reference/methods#sessioncreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/rko`](/reference/reference-methods.mdx#payout-rko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout/rko`](/reference/methods#sessionstartpayoutrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Example of a payout by token ```json showLineNumbers curl -X POST \ https:// api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` ```json showLineNumbers curl -X POST \ https:// api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to know if a payout is returned >](/payouts/payout-refunds) --- - [Payouts from a settlement account with our widget or by token](https://developer.131.ru/en/settlement-account/settlement-payout-tokenized-card): Payouts to bank cards of the self-employed, sole proprietors, and individuals You can make payouts from a settlement account to bank cards using a token or a hash instead of the card number. You can get a token/hash as follows: - hash: [using our widget](/payouts/tokenize-widget) - token: using the [`tokenize/elements`](/reference/methods#tokenizeelements) method - token: by [processing a recurring payment](/payments/payment-recurring) The scope of PCI DSS requirements you must comply with depends on the method you choose. #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/multi/create/rko`](/reference/reference-methods.mdx#sessionmulticreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/rko`](/reference/methods#sessionmultiinitpaymentrko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-card) and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers 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: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/multi/start/payment/rko`](/reference/reference-methods.mdx#sessionmultistartpaymentrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-card). :::info You can find information on the hash or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Payout example with the widget ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.109901Z", "updated_at": "2025-05-27T02:03:00.987002Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-27T02:03:00.456003Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-05-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` object. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Payout requests require either a token or a hash, depending on what you use. #### Step 1. Create a payment session Create a session using the [`session/multi/create/rko`](/reference/reference-methods.mdx#sessionmulticreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/rko`](/reference/methods#sessionmultiinitpaymentrko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers 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: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/multi/start/payment/rko`](/reference/reference-methods.mdx#sessionmultistartpaymentrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-card). :::info You can find information on the token, hash, or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Example of a payout with tokenized data ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.302206Z", "updated_at": "2025-05-27T02:03:00.863207Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-27T02:03:00.211108Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-05-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC", }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers 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", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) --- ## Self-Employed - [Connecting the self-employed to Bank 131](https://developer.131.ru/en/selfemployed/selfemployed-binding): Connecting self-employed people to Bank 131 for payments with fiscalization It is necessary to connect the self-employed person to Bank 131 to process payouts with fiscalization. This can be done using our special widget. ### How to connect a self-employed person to Bank 131 1. **You** place our [self-employed person connection widget](/payouts/widget-selfemployed.mdx) on your website. 2. **The self-employed person** enters their INN or phone number, agrees to the personal data processing terms, and clicks the button to submit the request in the widget. 3. **Bank 131** sends the Federal Tax Service a self-employed person connection request and notifies you that the self-employed person's confirmation is expected. 4. **The self-employed person** enters Moy Nalog (My Tax) and in the **Partners** section confirms the connection to Bank 131. After that, the self-employed person clicks the completion button in the widget. 5. **Bank 131** sends a request to the Federal Tax Service to check the connection status and receives a reply confirming that the connection has been successful. :::info If the self-employed person confirmed the connection but did not click the completion button in the widget, Bank 131 will not be notified of the confirmation. ::: After the connection is completed, make sure [the self-employed person's data available in the Federal Tax Service is up to date](/selfemployed/selfemployed-verification). --- - [Registering payouts with the Federal Tax Service](https://developer.131.ru/en/selfemployed/selfemployed-fiscalization): Registering payouts to a self-employed person with the tax authority and receipt issuance If a payout to a self-employed person was made without fiscalization, a receipt must be issued within 9 calendar days of receiving the money. If you issued a receipt by mistake, the fiscalization can be [canceled](#cancel). To use this functionality, contact your account manager at Bank 131. ### How to perform fiscalization #### Step 1. Create a payment session Send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request leaving the request body empty. You will get the session identifier in response. Request example ```json showLineNumbers 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' \ // highlight-start -d '{ }' // highlight-end ``` ```php showLineNumbers 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() ->createPayoutSession() ->build(); $response = $client->session()->create($request); ``` #### Step 2. Send a fiscalization request Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2704", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "123456789012", "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }, // highlight-end { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }] } } }' ``` Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_2704", "status": "in_progress", "created_at": "2025-05-27T08:13:33.736384Z", "updated_at": "2025-05-27T08:13:33.871729Z", "payments": [{ "id": "po_2705", "status": "in_progress", "created_at": "2025-05-27T08:13:33.860754Z", "amount_details": { "amount": 15000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 2 }, { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "123456789012", "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC" } } }] } } ``` #### Step 3. Wait to be notified of the results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the fiscalization was successful. The link to the receipt from the FTS is returned in the `fiscalization_details.receipt` object. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_2704", "status": "accepted", "created_at": "2025-06-08T09:07:34.689353Z", "updated_at": "2025-06-08T09:07:53.491653Z", "payments": [{ "id": "po_23695", // highlight-next-line "status": "succeeded", "created_at": "2025-06-08T09:07:42.591416Z", "finished_at": "2025-06-08T09:07:53.319963Z", "amount_details": { "amount": 15000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 2 }, { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "123456789012", // highlight-start "receipt": { "id": "203zpt6nu5", "link": "https://himself-ktr.nalog.ru/api/v1/receipt/645493572846/203zpt6nu5/print" }, // highlight-end "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC" } } }] } }' ``` ### How to cancel fiscalization Occasionally it's necessary to cancel fiscalization and annul the issued receipt. For example, if the payout failed or the receipt was issued by mistake. #### Step 1. Send a fiscalization cancellation request Send a [`session/refund`](/reference/reference-methods.mdx#sessionrefund) request specifying the session identifier from the fiscalization request that you are canceling in the `session_id` parameter and the receipt amount in the `amount` parameter. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/refund \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2704", // highlight-start "amount_details": { "amount": 15000, "currency": "rub" } // highlight-end }' ``` #### Step 2. Wait to be notified of the results Bank 131 will send you a [`payment_refunded`](/reference/reference-webhooks.mdx#payment_refunded) webhook with a link to the annulled receipt. :::info When fiscalization is canceled, Bank 131 specifies that the receipt was generated by mistake as a cancellation reason. ::: Webhook example ```json showLineNumbers curl - X POST \ https: //partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_2704", "status": "accepted", "created_at": "2025-06-08T09:07:34.689353Z", "updated_at": "2025-06-08T09:16:48.624196Z", "payments": [{ "id": "po_2705", "status": "succeeded", "created_at": "2025-06-08T09:07:42.591416Z", "finished_at": "2025-06-08T09:07:53.319963Z", "amount_details": { "amount": 15000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 2 }, { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "123456789012", // highlight-start "receipt": { "id": "203zpt6nu5", "link": "https://himself-ktr.nalog.ru/api/v1/receipt/645493572846/203zpt6nu5/print" }, // highlight-end "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC" } }, "refunds": [{ "id": "rf_249", "status": "accepted", "created_at": "2025-06-08T09:16:42.897606Z", "finished_at": "2025-06-08T09:16:48.517040Z", "amount_details": { "amount": 15000, "currency": "rub" } }] }] } }' ``` --- - [API features](https://developer.131.ru/en/selfemployed/intro): General information about payouts to self-employed individuals Self-employed individuals are people who work for themselves and pay the professional income tax. For example, tutors. Every payout to a self-employed person is considered their income and must be recorded with the Federal Tax Service (FTS). Through our API, you can process payouts with fiscalization, i.e. with automatic receipt registration at the FTS. Before making the first payout, make sure the self-employed person is [connected to Bank 131](/selfemployed/selfemployed-binding). [How to make a payout with fiscalization >](/selfemployed/selfemployed-payout) ### Notifications from the Federal Tax Service Through your website's interface, you can inform self-employed people about accrued taxes, bonuses, and other important information from the Federal Tax Service (FTS). [How to work with notifications from the FTS >](/selfemployed/selfemployed-notification) --- - [Notifications from the Federal Tax Service](https://developer.131.ru/en/selfemployed/selfemployed-notification): Information about alerts from the Federal Tax Service via website or mobile app You can inform self-employed people about accrued tax, bonuses, and other important information directly through your website's interface. ### Getting the number of unread notifications 1. Send an [`npd/notifications/count`](/reference/reference-methods.mdx#count) request to get the number of unread notifications for a selected self-employed person. 2. Show the number from the `count` parameter to the self-employed person on your website. 3. Send an [`npd/notifications/read`](/reference/reference-methods.mdx#read) request to get the list of unread notifications. 4. Show the notifications to the self-employed person. 5. Send an [`npd/notifications/mark_as_delivered`](/reference/reference-methods.mdx#mark_as_delivered) request to inform the FTS that the notifications have been delivered to the self-employed person. 6. Send an [`npd/notifications/update`](/reference/reference-methods.mdx#update) request to inform the FTS that the self-employed person has read the notifications. ### Getting information about tax accruals and bonuses To get information about the bonus account balance, amount of unpaid bills, and current debt, use the [`npd/account_status`](/reference/reference-methods.mdx#account_status) method. To get more details, use the [`npd/accruals`](/reference/reference-methods.mdx#accruals) method. --- - [Payouts to a self-employed person with a fiscal receipt](https://developer.131.ru/en/selfemployed/selfemployed-payout): Sending payouts to a self-employed person with fiscalization To avoid accounting issues for you and problems with the Federal Tax Service for the self-employed person, payouts must be fiscalized. To do this, you will need: the payer's INN, the self-employed person's INN, and receipt details (description and cost of services). Before making a payout, verify the following: - the recipient has an active self-employed status - the recipient is connected to Bank 131 - the recipient's annual income, including the current payout, does not exceed 2.4 million rubles (otherwise, the recipient will lose their self-employed status) If at least one condition is not met, the payout will not go through. ### How to make a payout :::info When working with bank cards, you must comply with the PCI DSS requirements depending on the selected payout option. ::: The steps depend on whether or not you use our widget. #### Step 1. Get a public token A public token is required to initialize the widget. Send a token creation request ([`token`](/reference/reference-methods.mdx#token)) specifying `tokenize_widget` as the widget type. In the response you will get a public token. Example ```json showLineNumbers 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: signature' \ -d '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` ```php showLineNumbers 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. Initialize the widget Initialize the widget on your website using the public token you received in the previous step. After that, the payee can enter their bank card or account details into the widget form. [How to initialize our card tokenization widget >](/payouts/tokenize-widget) [How to initialize our account tokenization widget >](/payouts/tokenize-account-widget) #### Step 3. Create a payment session Send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization) method to create a session and a payout at the same time. In this case, specify all the [data for fiscalization](/reference/objects#fiscalization_details), parameters for a payout to a [card](/payouts/russian-card) or [account](/payouts/russian-account-parameters) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers 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 '{ "metadata": "good" }' ``` ```php showLineNumbers 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() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 4. Start the payout Send a [`session/start/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization) request specifying the session identifier, [data for fiscalization](/reference/objects#fiscalization_details), and parameters for a payout to a [card](/payouts/russian-card) or [account](/payouts/russian-account-parameters). Request example for a payout to a card with fiscalization using our widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { // highlight-next-line "number_hash": "3589c9cad4c0e939f6e01a91710b1bef2db5a7a0a9dca274981511120268d420" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.102445Z", "updated_at": "2025-05-27T02:03:00.986650Z", "next_action": "confirm", "payments": [{ "id": "po_2909", "status": "pending", "created_at": "2025-05-27T02:03:00.808800Z", "payment_method": { "type": "card", "card": { "brand": "mir", "last4": "4940", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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 6. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` parameter of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Also, the webhook will return the `receipt` object containing the FTS receipt identifier and a link to it. Follow the link to download the receipt. Receipt example Handling the webhook using SDK ```php showLineNumbers 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 } ``` You can make payouts: to a card—by card number, token or hash; to an account—by account number or token; to a YooMoney wallet—by wallet number only. Create a token for a card using the [`tokenize/elements`](/reference/methods#tokenizeelements) method or for an account using the [`tokenize`](/reference/methods#tokenize) method. Alternatively, you can get a hashed number for a card using our [card tokenization widget](/payouts/tokenize-widget) or a token for an account using our [account tokenization widget](/payouts/tokenize-account-widget). #### Step 1. Create a payment session Send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization) method to create a session and a payout at the same time. In this case, specify all the [data for fiscalization](/reference/objects#fiscalization_details), parameters for a payout to a [card](/payouts/russian-card), [account](/payouts/russian-account-parameters) or [YooMoney wallet](/payouts/yoomoney) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers 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 '{ "metadata": "good" }' ``` ```php showLineNumbers 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() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 2. Start the payout Send a [`session/start/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization) request specifying the session identifier, [data for fiscalization](/reference/objects#fiscalization_details), and parameters for a payout to a [card](/payouts/russian-card), [account](/payouts/russian-account-parameters) or [YooMoney wallet](/payouts/yoomoney). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\Participant; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Goods delivery', new Amount(10000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590613976192' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('3316004710'); $recipient = new Participant(); $recipient->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230') ->setIncomeInformation($incomeInformation) ->setCard(new BankCard('2200********4940')) ->setAmount(10000, 'rub') ->setRecipient($recipient) ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { // highlight-next-line "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": { "account": "410012411727100" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers 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": "2025-05-27T02:03:00.705430Z", "updated_at": "2025-05-27T02:03:00.613000Z", "next_action": "confirm", "payments": [{ "id": "po_2909", "status": "pending", "created_at": "2025-05-27T02:03:00.578000Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers 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 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` parameter of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Also, the webhook will return the `receipt` object containing the FTS receipt identifier and a link to it. Follow the link to download the receipt. Receipt example Handling the webhook using SDK ```php showLineNumbers 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 } ``` [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds) --- - [Verifying data of a self-employed person](https://developer.131.ru/en/selfemployed/selfemployed-verification): Method for verifying self-employed person data Before making a payout with fiscalization, ensure that the self-employed person's details match those in the Federal Tax Service (FTS) database. Otherwise, the payout will not go through. To verify the details: 1. Send an [`npd/taxpayer/check_personal_info`](/reference/reference-methods.mdx#selfemployed_check) request specifying the self-employed person's INN, full name, and phone number. You will get a request identifier within the `request_id` parameter in the response. 2. Send an [`npd/request/status`](/reference/reference-methods.mdx#selfemployed_check) request specifying the request identifier. The response will show if there is a data mismatch. In case a data mismatch was found, notify the self-employed person so they can update their details with the Federal Tax Service. --- ## API Reference - [Error codes](https://developer.131.ru/en/reference/errors): Errors for all products of Bank 131 :::info * The error codes may be changed without prior notice. * Below are all the errors you can encounter when making either payments or payouts. * The table below provides general descriptions for error codes (`code`), one error code can correlate with different values in the `description` field. * The [`error`](/reference/objects#payment-session-statuses-status) status of the payment session is not final. Please contact Bank 131's support team and wait for a final transaction status. ::: | Error code (`code`) | Error description | What you can do | | ------------------------------------ | ------------------------------------- |--------------------| | `3DS_error` | 3DS authentication failed | 3DS authentication have failed. Retry the operation | | `account_not_found` | Account not found | Check the account number for correctness. If the account number is correct and the account belongs to you, but you receive this error anyway, contact our support team | | `activity_count_exceeded` | The activity limit for the card has been exceeded | Check if the used card has any restrictions and retry the operation. If the error persists, contact our support team | | `amount_is_large` | The transaction amount is too large | Reduce the amount to be received | | `amount_is_small` | The transaction amount is too small | Increase the amount to be received | | `amount_less_allowed_provider` | The payment amount is less than acceptable | Change the payment amount | | `authentication_error` | Authentication error | Check the [`X-PARTNER-SIGN`](/reference/format#authentication) signature | | `authorization_error` | Authorization error | You do not have enough privileges for the operation. Check your projects (`X-PARTNER-PROJECT`). Contact our support team | | `bank_card_expired` | The bank card is past its expiration date | Check the input data for correctness and retry the attempt | | `binding_is_deactivated` | The card is not verified for this agent | Binding is disabled. Contact the support team of the emitting bank | | `capture_timeout` | The transaction was canceled due to the confirmation timeout | No response came from you. Check the transaction status and the session status. If these statuses are unsuccessful and final, retry the operation | | `card_number_does_not_exist` | Invalid card number | Check the card number for correctness and retry the attempt | | `check_error` | Verification error | Retry the request later | | `confirm_timeout` | Transaction canceled due to timeout | Retry the transaction | | `contact_support` | Contact support | Contact our support team | | `declined_by_issuer_bank` | The operation was canceled by the emitting bank | Contact the support team of the emitting bank | | `format_error_amount` | (FPS) Invalid format – amount to pay | Check the amount format and retry the attempt | | `format_error_description` | (FPS) Invalid format – purpose of payout | Check the payout purpose format and retry the attempt | | `format_error_full_name` | (FPS) Invalid format – recipient's full name | Check the recipient's full name format and retry the attempt | | `format_error_phone_number` | (FPS) Invalid format – recipient's phone number | Check the recipient's phone number format and retry the attempt | | `format_error_recipient_bank_id` | (FPS) Invalid format – recipient's bank ID in FPS | Check the recipient's bank ID format and retry the attempt | | `idempotency_key_already_exists` | The previous request with the same key is still in progress | Wait till the previous request is processed | | `idempotency_key_not_supported` | This method cannot be used with an idempotency key | Do not use an idempotency key for this method. Check the list of [methods supporting the idempotency key feature](/reference/format#idempotency-key) | | `idempotency_key_params_mismatch` | The key has already been used for another session | Use another idempotency key | | `identification_error` | Partner identification error | Check that the data is correct and retry the attempt | | `incorrect_amount` | Incorrect amount | Change the amount ot be received | | `incorrect_card_data` | Incorrect card data | Retry the operation with correct card data | | `incorrect_phone_number` | Incorrect phone number | The phone number should contain a country code and 10 digits. For example: 71234567890 | | `insufficient_funds` | The card does not have enough funds | The buyer does not have enough funds, retry the operation later | | `insufficient_wallet_balance` | The wallet does not have enough funds. You will get this error until the balance is replenished | Top up the balance and retry the operation | | `internal_error` | Internal error | Retry the operation later. If the error persists, contact our support team | | `invalid_account` | Invalid account/Inactive account | Check whether the account is on the list of accounts allowed for payouts from the [settlement](/settlement-account/settlement-intro#list_of_accounts), [escrow](/escrow-account/escrow-intro#list_of_accounts), or [collateral account](/payouts/collateral-intro#list_of_accounts) respectively, and retry.If the account is inactive, it either does not exist or has been blocked. Provide a different account | | `invalid_recipient_full_name` | (FPS) Incorrect recipient's full name details | Check the recipient's full name for correctness and retry the attempt | | `invalid_request` | Invalid request | Check your request and retry the attempt (see [Methods](/reference/methods)) | | `invalid_transaction` | Invalid transaction | Check the data and retry the operation later. If the error persists, contact our support team | | `limits_exceeded` | The allowed recipient's limits have been exceeded | Change the amount or abandon the operation | | `not_permitted_by_issuer_bank` | The operation was not permitted by the emitting bank | Contact the support team of the emitting bank | | `not_permitted_to_card` | The transaction is not permitted to the card holder | Contact the support team of the emitting bank | | `npd_service_internal_error` | Self-employed service error | Retry the operation later. If the error persists, contact our support team | | `operation_rejected` | The operation has been rejected for security reasons | Contact our support team | | `phone_number_is_not_associated` | The phone number is not linked to this card | Link the card to the phone number of abandon the operation | | `phone_number_not_belong_card` | Phone number check failed |The operation was canceled by the emitting bank. Contact the support team of the emitting bank | | `provider_exceeds_amount_limit` | Exceeds the one-time deposit limit or the maximum amount of deposits (per day or per month) | Specify a smaller amount or a different period and retry the attempt | | `provider_foreign_transfer_prohibited` | Transfer to a foreign card for this provider is prohibited | Select another card and retry the attempt | | `provider_internal_error` | Provider error | Retry the operation later. If the error persists, contact our support team | | `provider_issuer_unavailable` | The provider issuer is unavailable | Retry the operation later. If the error persists, contact our support team | | `provider_timeout` | Provider response timeout, transaction canceled | Retry the operation later. If the error persists, contact our support team | | `provider_wallet_invalid_account` | An account (wallet) with this ID does not exist or is closed | Check the account ID for correctness | | `provider_wallet_is_blocked` | The wallet is blocked | Contact the support team of the emitting bank | | `provider_wallet_not_identified` | The wallet is not identified. Anonymous wallets cannot be topped up | Choose an identified wallet and retry the attempt | | `qr_expired` | (FPS) QR code expired | Start the operation again | |`rate_has_changed`|The conversion rate has changed |Retry the operation| |`recipient_account_not_found`|The recipient's account is inactive|The account is not found or blocked. Specify another account| |`recipient_activity_count_exceeded`|The allowed recipient's balance has been exceeded |Abandon the operation or decrease the amount to be received | | `recipient_full_name_not_specified` | Missing payee's full name | [Specify a payee's full name](/reference/reference-objects.mdx#participant_details_recipient) | |`recipient_is_blocked` |Recipient blocked|Abandon the operation| |`recipient_not_found`|Recipient not found | Make sure the recipient's details are correct | | `refund_amount_too_large` | The refund amount exceeds the maximum permitted amount | Correct the refund amount and retry the operation | | `routing_internal_error` | Payment condition determination error | Contact our support team | | `sender_account_not_found` |Payer's account not found | Make sure the payer's account is correct| |`sender_is_blocked`|Payer blocked|Abandon the operation| |`sender_not_found` | Payer not found | Make sure the payer's details are correct | | `session_cancelled` | The session has been canceled | If you did not canceled the session, contact our support team | | `session_cancelled_by_partner` | The session has been cancelled by the partner | If you canceled the session, start it again.If you did not canceled the session, contact our support team | | `session_lock_failed` | Operation canceled for security reasons | Abandon your transaction or contact the support team | | `session_wrong_state` | Cannot perform a transaction in this status | Check the [session status](/reference/objects#payment-session-statuses-status). If the session status is `error`, you cannot cancel it. To learn the reasons, contact our support team | | `suspected_fraud` | Suspicious transaction | The operation cannot be performed, contact our support team | | `taxpayer_already_bound` | The self-employed person is already linked to Bank 131 | Check the input data for correctness | | `taxpayer_income_exceeds_amount_limit` | This ticket cannot be registered, it would exceed the self-employed annual amount limit (2,4 mln rubles) | Check the input data for correctness | | `taxpayer_not_bound` | The self-employed person is not linked to Bank 131 | [Link](/selfemployed/selfemployed-binding) the self-employed person to Bank 131 | | `taxpayer_unknown` | The person with this INN is not self-employed | Check the self-employed person's INN and status for correctness. Retry the attempt | | `wallet_internal_error` | Balance operation error | Retry the operation later. If the error persists, contact our support team | --- - [Methods](https://developer.131.ru/en/reference/methods): Commands, addresses, and parameters When processing requests, the system checks for valid input parameters, the presence of the [necessary headers](/reference/reference-format.mdx), and rights to perform operations. :::info In the documentation, the mandatory status of parameters is specified for each transaction, but you are not required to pass them in the body of this particular request. You can pass them in advance—when creating a session. Example of sending a payout request: - If the `session/create` request was sent empty, the payout request (`session/start/payout`) must contain all the mandatory parameters. - If the `session/create` request contained all the mandatory parameters specified for the transaction, the payout request (`session/start/payout`) can be empty or contain only those parameters the values of which you want to override. - If the `session/create` request contained some of the mandatory parameters, the payout request (`session/start/payout`) must contain the remaining ones. - If you create a session and a payout in a single request (`session/init/payout`), pass all required parameters right away. ::: ## Performing operations ### `recurrent/disable` #### Disable token for recurring payments You can disable a token with this request. Send the token in the request, in the response you will get `is_active: false`. This means you cannot perform recurring payments with this token. > After the token has disabled, the token expiration setting `finished_at` may contain a weird date of the year 2000. This value won't affect anything, so please disregard it. #### Endpoint `/api/v1/recurrent/disable` #### Request parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|------------------------------------------------------------------------| | `recurrent` | + | object | [Token information](/reference/reference-objects.mdx#recurrent) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/recurrent/disable \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427" } }' ``` ```php showLineNumbers 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() ->disableRecurrentRequestBuilder() ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39') ->build(); $response = $client->recurrent()->disable($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|----------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `recurrent` | + | object | [Token information](/reference/reference-objects.mdx#recurrent_token_info) | Response example ```json showLineNumbers { "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": false, "type": "recurrent_token" }, "status": "ok" } ``` ### `session/cancel` #### Operation cancellation This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a `ready_to_confirm` or a `ready_to_capture` webhook. If you do not want to perform the operation, you can cancel it by sending a `session/cancel`. If everything looks good, send a request to confirm the operation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or a request to debit the amount being put on hold ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)). #### Endpoint `/api/v1/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "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" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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); $response = $client->session()->cancel('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/capture` #### Debiting amounts put on hold This request can be used if you are sending delayed capture payments. These payments are performed in two stages: first, the money is put on hold (for example, on the user's bank card), and then it is debited in response to your request. The request can be sent when Bank 131 is ready to debit the money and has sent you a `ready_to_capture` webhook. If you want to debit the amount put on hold, send a `session/capture`. You can debit the full amount on hold, or a portion of it. To cancel the debit, send a ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). #### Endpoint `/api/v1/session/capture` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------- | | `session_id` | + | string | Bank 131 session identifier | | `amount_details` | - | object | Amount to be debited. Can be less than the amount on hold, but greater than 0. If not specified, the full amount of the payment will be debited | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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); $response = $client->session()->capture('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/capture` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------- | | `session_id` | + | string | Bank 131 session identifier | | `amount_details` | - | object | Amount to be debited. Can be less than the amount on hold, but greater than 0. If not specified, the full amount of the payment will be debited | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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); $response = $client->session()->capture('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/confirm` #### Operation confirmation This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a `ready_to_confirm` webhook. You'll need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a `session/confirm` request. The confirmation window is 4 hours from the moment of transaction creation. Failure to submit the request on time will result in a `confirm_timeout` error. If something is not right, cancel the operation by sending a [`session/cancel`](/reference/reference-methods.mdx#sessioncancel) request. #### Endpoint `/api/v1/session/confirm` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | | `confirm_information` | - (mandatory for the transactions with an escrow account or when `requier_confirm_information = true`) | object | [Transaction confirmation information](/reference/reference-objects.mdx#confirm_information) | Request example ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "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" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/confirm` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | | `confirm_information` | - (mandatory for money transfers, for the transactions with an escrow account or when `requier_confirm_information = true`) | object | [Transaction confirmation information](/reference/reference-objects.mdx#confirm_information) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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); $response = $client->session()->confirm('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/create` #### Payment session creation Creates a payment session on Bank 131's side. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund). Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. > If you are ready to provide all the data needed to perform the operation in the request, you can use the method whereby the payout (`session/start/payout`) or the payment (`session/start/payment`) starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. #### Endpoint `/api/v1/session/create` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------| | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `amount_details` | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - (mandatory for payouts) | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - (mandatory for payments) | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers 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" }' ``` ```php showLineNumbers 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() ->createPaymentSession() //OR ->createPayoutSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z" } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/create` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------| | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `amount_details` | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - (mandatory for payouts) | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - (mandatory for payments) | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/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" }' ``` ```php showLineNumbers 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() ->createPaymentSession() //OR ->createPayoutSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z" } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment` #### Session creation with simultaneous payout initiation Can be used if you are ready to pass all the parameters needed for the payment at once. The response contains the parameters of the session created and an array with information about the payment (`acquiring_payments`/`payment_list`). #### Endpoint `/api/v1/session/init/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Client data in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('http://bank131.ru'); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '05', '22', '123')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Client data in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('http://bank131.ru'); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '05', '22', '123')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment/sync` >Please be aware that we do not recommend implementing this method unless you have already used it before. #### One-request payment This method allows sending a payment request and getting a response right away. Use it if you are ready to submit all payment parameters in this request. The response contains the parameters of the session created and the [`acquiring_payments`/`payment_list`](/reference/objects#acquiring_payments) array with the payment result and information. #### Endpoint `/api/v1/session/init/payment/sync` #### Request parameters Only required request parameters are listed here. You can find additional parameters by following the links in the object descriptions. | Name | Mandatory | Type | Description | |--------------------------------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | |   `type` | + | string | Payment method type. Possible values: `card` | |   `card` | + | object | [Bank card details](/reference/reference-objects.mdx#card) | |     `type` | + | string | Method of card information transmission. Value: `bank_card` | |     `bank_card` | + | object | [Card information](/reference/reference-objects.mdx#bankcard) | |       `number` | + | string | Card number | |       `expiration_month` | + | string | Month of card expiration, `MM`. Example: `01` | |       `expiration_year` | + | string | Year of card expiration, `YY`. Example: `22` | |       `security_code` | + | string | CVC/CVV code | | `amount_details` | + | object | [Payment amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To pay 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Information about payment sender on your side](/reference/reference-objects.mdx#customer) | |   `reference` | + | string | Payment sender ID in your system | | `payment_options` | + | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | |   `return_url` | + | string | URL to which the user is redirected after the payment has been performed. The URL must be valid | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment/sync \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_203", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payment/sync` #### Request parameters Only required request parameters are listed here. You can find additional parameters by following the links in the object descriptions. | Name | Mandatory | Type | Description | |--------------------------------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | |   `type` | + | string | Payment method type. Possible values: `card` | |   `card` | + | object | [Bank card details](/reference/reference-objects.mdx#card) | |     `type` | + | string | Method of card information transmission. Value: `bank_card` | |     `bank_card` | + | object | [Card information](/reference/reference-objects.mdx#bankcard) | |       `number` | + | string | Card number | |       `expiration_month` | + | string | Month of card expiration, `MM`. Example: `01` | |       `expiration_year` | + | string | Year of card expiration, `YY`. Example: `22` | |       `security_code` | + | string | CVC/CVV code | | `amount_details` | + | object | [Payment amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To pay 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Information about payment sender on your side](/reference/reference-objects.mdx#customer) | |   `reference` | + | string | Payment sender ID in your system | | `payment_options` | + | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | |   `return_url` | + | string | URL to which the user is redirected after the payment has been performed. The URL must be valid | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v2/session/init/payment/sync \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_203", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payout` #### Session creation with simultaneous payout initiation This request can be used if you are ready to pass all the parameters needed for the payout at once, for example when transferring a payout to a Russian bank account. The response contains the parameters of the session created and an array with the information about the payout (`payments`/`payout_list`). #### Endpoint `/api/v1/session/init/payout` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 1000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $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() ->initPayoutSession() ->setCard(new BankCard('4242424242424242')) ->setAmount(1000, 'rub') ->build(); $response = $client->session()->initPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "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" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/init/payout` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 1000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $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() ->initPayoutSession() ->setCard(new BankCard('4242424242424242')) ->setAmount(1000, 'rub') ->build(); $response = $client->session()->initPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/fiscalization` #### Session creation and payout start, with additional check that all the fiscalization data has been provided Can be used for payouts to self-employed people if you are ready to provide all the information about the self-employed person and the details necessary to create the payout at once, for example when transferring a payout to a Russian bank account. The response contains the parameters of the session created and an array with the information about the payout (`payments`/`payout_list`) with the data necessary to send the receipt. #### Endpoint `/api/v1/session/init/payout/fiscalization` | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "3300000000", "payer_name": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\Participant; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; use Bank131\SDK\DTO\Amount; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $recipient = new Participant(); $recipient->setFullName('Ivanov Ivan'); $request = RequestBuilderFactory::create() ->initPayoutSessionWithFiscalization() ->setIncomeInformation($incomeInformation) ->setCard(new BankCard('4242424242424242')) ->setAmount(5000, 'rub') ->setRecipient($recipient) ->setMetadata('good') ->build(); $response = $client->session()->initPayoutWithFiscalization($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "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": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "participant_details.recipient.full_name.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payout/fiscalization` | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v2/session/init/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "3300000000", "payer_name": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\Participant; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; use Bank131\SDK\DTO\Amount; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $recipient = new Participant(); $recipient->setFullName('Ivanov Ivan'); $request = RequestBuilderFactory::create() ->initPayoutSessionWithFiscalization() ->setIncomeInformation($incomeInformation) ->setCard(new BankCard('4242424242424242')) ->setAmount(5000, 'rub') ->setRecipient($recipient) ->setMetadata('good') ->build(); $response = $client->session()->initPayoutWithFiscalization($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2909", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payout_details": { "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": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "participant_details.recipient.full_name.not_blank" }, "status": "error" } ``` ### `session/refund` #### Refund You can use this request to return money to the user after a successful payment. After completing the refund, Bank 131 will send you a `payment_refunded` webhook. #### Endpoint `/api/v1/session/refund` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Identifier of a successful payment session which needs to be refunded | | `amount_details` | - | object | [Amount of the refund](/reference/reference-objects.mdx#amount_details). If not specified, the refund will be made for the full amount of the payment | | `metadata` | - | \* | Additional information | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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() ->refundSession('ps_3230') ->build(); $response = $client->session()->refund($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/refund` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Identifier of a successful payment session which needs to be refunded | | `amount_details` | - | object | [Amount of the refund](/reference/reference-objects.mdx#amount_details). If not specified, the refund will be made for the full amount of the payment | | `metadata` | - | \* | Additional information | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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() ->refundSession('ps_3230') ->build(); $response = $client->session()->refund($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/start/payment` #### Payment start This request can be used to start a payment within an existing session. In the parameters, you can pass the data necessary to perform the payment or change pieces of data that have already been passed. #### Endpoint `/api/v1/session/start/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | - | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the payer and the recipient) | | `customer` | - | object | [Payment sender information in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment settings](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('return_url'); $request = RequestBuilderFactory::create() ->startPaymentSession('session_id') ->setCard( new BankCard( 'number', 'expiration_month', 'expiration_year', 'security_code' ) ) ->setCustomer( new Customer('reference') ) ->setPaymentOptions($paymentOptions) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "acquiring_payments": [{ "id": "pm_3232", "status": "in_progress", "created_at": "2024-08-21T06:21:56.846204Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` #### Endpoint `/api/v2/session/start/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | - | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the payer and the recipient) | | `customer` | - | object | [Payment sender information in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment settings](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('return_url'); $request = RequestBuilderFactory::create() ->startPaymentSession('session_id') ->setCard( new BankCard( 'number', 'expiration_month', 'expiration_year', 'security_code' ) ) ->setCustomer( new Customer('reference') ) ->setPaymentOptions($paymentOptions) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "payment_list": [{ "id": "pm_3232", "status": "in_progress", "created_at": "2024-08-21T06:21:56.846204Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` ### `session/start/payout` #### Payout start This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. #### Endpoint `/api/v1/session/start/payout` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payment_method` | - | object | [Payout details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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() ->startPayoutSession('session_id') ->build(); $response = $client->session()->startPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "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" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payout_details` | - | object | [Payout details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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() ->startPayoutSession('session_id') ->build(); $response = $client->session()->startPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/start/payout/fiscalization` #### Payout start, with check that all fiscalization data has been provided This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. #### Endpoint `/api/v1/session/start/payout/fiscalization` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object |[Amount](/reference/reference-objects.mdx#amount_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "330000000000", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }] } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230', $incomeInformation) ->build(); $response = $client->session()->create($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout/fiscalization` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object |[Amount](/reference/reference-objects.mdx#amount_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "330000000000", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }] } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230', $incomeInformation) ->build(); $response = $client->session()->create($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `token` #### Getting a token to work with widgets The token is needed to access Bank 131's JavaScript library. You can get it using this request. The token is valid for 24 hours and can be used for a single operation only. When sending a request, specify the widget you are going to work with. #### Endpoint `/api/v1/token` #### Request parameters | Name | Mandatory | Type | Description | |------------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------------| | `tokenize_widget` | - | object | [Data required by the tokenization widget](/reference/reference-objects.mdx#tokenize_widget) | | `self_employed_widget` | - | object | [Data required by the self-employed registration widget](/reference/reference-objects.mdx#selfemployedwidget) | | `acquiring_widget` | - | object | [Data required by the payment form widget](/reference/reference-objects.mdx#acquiring_widget) | An example of how to get a token to perform a payout that involves obtaining card details via the widget and connecting a self-employed person ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tokenize_widget": { "access": true }, "self_employed_widget": { "tax_reference": "111111111111" } }' ``` ```php showLineNumbers 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() ->setSelfEmployedWidget('111111111111') ->setAcquiringWidget( 'test_ps_id', 'http://success.url', 'http://failed.url', false ) ->build(); $response = $client->widget()->issuePublicToken($request); $publicToken = $response->getPublicToken(); ``` An example of how to get a token to perform a payment through a payment form ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_123456" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | | ------------- | --------- | ------- | -------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok` | | `public_token` | - | string | Public token | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539" } ``` ```json showLineNumbers { "status": "error", "error": { "description": "acquiring_widget.session_id.not_unique", "code": "invalid_request" } } ``` ### `tokenize` #### Tokenizing a bank account number This method is used for tokenizing a bank account (payout). Use it to get a token and a masked account number. The token received in the response does not expire. You can tokenize any account that passes verification against a specified range of accounts. Otherwise, the “Enter a different account number” error will be returned. #### Endpoint `/api/v1/tokenize` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|---------------------------------------------------------------------------------| | `type` | + | string | Bank account type | | `bank_account_ru` | + | object | [Russian bank account details](/reference/reference-objects.mdx#bank_account_ru) | |   `bik` | + | string | Bank BIK | |   `account` | + | string | Account number | Request example ```json showLineNumbers curl -X POST \ https://proxy-stage.bank131.ru/api/v1/tokenize \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "bank_account_ru", "bank_account_ru": { "bik": "044525974", "account": "40817810400003869535" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | | ------------------ | --------- |-------- | -------------------------------- | | `status` | + | string | Bank account type | | `token` | - | string | Token | | `data` | - | object | [Masked user account data object](/reference/reference-objects.mdx#data) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "token": "2c6ebe1368407b922057efee0fed58360dae1d28af50fa6734bb54c61a763c24", "data": { "masked_account": "40817***9535" } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "The public token is not found", "code": "public_token_invalid" } } ``` ### `tokenize/elements` #### Tokenizing a card number A method for tokenizing a bank card number. As a result, the card number is stored in the Bank 131 system, and you receive a token for making multiple payouts to this card. The token has no expiration date. >To start using this method, please contact your manager in Bank 131. #### Endpoint `/api/v1/tokenize/elements` #### Request parameters | Name | Mandatory | Type | Description | | ------------------ |---------- | ------ | ------------------------------------------------------------------------------ | | `card_elements` | + | object | [Card number](/reference/reference-objects.mdx#card_elements) | Request example ```json showLineNumbers curl -X POST \ https://proxy-stage.bank131.ru/api/v1/tokenize/elements \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "card_elements": [ { "ref": "number", "type": "card_number", "card_number": "4242424242424242" } ] }' ``` #### Response parameters | Name | Mandatory | Type | Description | |--------|-----------|--------|------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `data` | + | object | [Card data](/reference/objects#tokenize_data) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "data": { "number": { "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919", "info": { "masked_card_number": "424242******4242", "card_network": "visa", "card_type": "visa" } } } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Information ### `fps/banks` You can use this request to get a list of names and identifiers of banks-recipients of the Faster Payment System. >The method can be used for payouts only. #### Endpoint `/api/v1/fps/banks` Request example ```json showLineNumbers curl -X GET \ https://demo.bank131.ru/api/v1/fps/banks \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{}' ``` ```php showLineNumbers use Bank131\SDK\Client; $response = $client->fps()->getBanks(); foreach ($response->getBanks() as $bank) { echo $bank->getId(), ' ', $bank->getRuName(), ' ', $bank->getEngName(), PHP_EOL; } ``` Response example ```json showLineNumbers { "banks": [{ "id": "100000000243", "eng_name": "National Standard Bank", "ru_name": "Национальный стандарт" }, { "id": "100000000056", "eng_name": "Khlynov", "ru_name": "Хлынов" },...] } ``` ### `fps/customer_verification` You can use this request to check whether a recipient is registered in the Faster Payment System (FPS). If the user is found in the FPS, the session will have a successful status, otherwise the session will be canceled. This operation is free of charge and is confirmed automatically (`ready_to_confirm` is not sent). #### Endpoint `/api/v1/fps/customer_verification` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------| | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/fps/customer_verification \ -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": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_109941", "status": "in_progress", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "payments": [{ "id": "po_31668", "status": "in_progress", "created_at": "2022-03-01T11:57:31.895773Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/fps/customer_verification` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------| | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/fps/customer_verification \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_109941", "status": "in_progress", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "payout_list": [{ "id": "po_31668", "status": "in_progress", "created_at": "2022-03-01T11:57:31.895773Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `report/account_balance` Use this method to get your settlement or escrow account balance. [More on account balance ](/statements/statements-balance). #### Endpoint `/api/v1/report/account_balance` #### Request parameters | Name | Mandatory | Type | Description | | ---------------- | -------------- | ------ | ----------------------------------------------------------------------------------------------------- | | `account_number` | + | string | Account number. The account number must start as follows: `40702`, `40703`, `40802`, `40807`, `40701` | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/report/account_balance \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "account_number": "40702810400000000333" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `account_number` | - | string | Account number | | `account_currency` | - | string | Account currency according to ISO 4217. Example: `RUB` | | `balance` | - | object | [Balance details](/reference/reference-objects.mdx#balance) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { "current_balance": 20900 } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "Error code", "description": "Error description" } } ``` ### `report/account_statement` Use this method to get bank statements for your settlement or escrow account opened in rubles. Statements can only be generated for a day. To learn more, click [here](/statements/statements-escrow). #### Endpoint `/api/v1/report/account_statement` #### Request parameters | Name | Mandatory | Type | Description | |----------------|-----------|--------|--------------------------------------------------------------| | `account_number` | + | string | Account number (20 digits) for which you request a statement | | `date_to` | + | date | Statement end date. Example: 2023-06-01 | | `date_from` | + | date | Statement start date. Example: 2023-06-01 | > The `date_from` and `date_to` values must match. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/report/account_statement \ -H 'Content-Type: application/json; charset=utf-8' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "account_number": "40702810600200000014", "date_to": "2023-06-01", "date_from": "2023-06-01" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |------------------------------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `method` | + | object | [Method data](/reference/reference-objects.mdx#method) | |   `name` | + | string | Method name (`account_statement`) | |   `account_statement` | + | object | [Statement details](/reference/reference-objects.mdx#account_statement) | |     `date_from` | + | date | Statement start date | |     `date_to` | + | date | Statement end date | |     `account_number` | + | string | Account number (20 digits) for which the statement is generated | |     `total_turnover` | + | object | [Information on funds movement](/reference/reference-objects.mdx#total_turnover) | |       `debet` | + | int | Total debits over the period covered by the statement | |       `credit` | + | int | Total credits over the period covered by the statement | |     `total_balance` | + | object | [Balance information](/reference/reference-objects.mdx#total_balance) | |       `opening` | + | int | Opening balance on the statement start date | |       `closing` | + | int | Closing balance on the statement end date | |     `transactions` | + | array | [Information on transactions](/reference/reference-objects.mdx#transactions) | |       `amount` | + | int | Top-up amount (non-negative values only) | |       `base_amount` | - | int | Transaction amount in the currency. Should be filled out only for transactions in currencies other than Russian rubles. When using the base currency (RUB), the parameter is optional | |       `currency` | + | string | Transaction currency | |       `payment_date` | + | date | Transaction date | |       `bank_system_id` | + | string | Payment identifier. It is specified for all kinds of payments:- for payments sent via the API - for transfers from another bank- for payments made through online banking | |         `transaction_id` | - | string | Transaction identifier. It is specified for payments sent via the API | |       `session_id` | - | string | Session identifier. It is specified for payments sent via the API | |       `purpose` | + | string | Payment purpose | |       `counter_party` | + | object | [Counterparty details](/reference/reference-objects.mdx#counterparty) | |         `kpp` | - | string | Counterparty's KPP | |         `inn` | - | string | Counterparty's INN | |         `name` | + | string | Counterparty's name | |         `account_number` | + | string | Counterparty's account number | |         `bank_code` | + | string | Counterparty's bank BIK | |       `type` | + | string | Transaction type. Possible values: `credit` (for replenishment operations), `debet` (for write-off operations) values | Successful response example ```json showLineNumbers { "status": "ok", "method": { "name": "account_statement", "account_statement": { "date_from": "2022-11-12T18:19:32.487+0000", "date_to": "2022-11-13T18:19:32.487+0000", "account_number": "40703810500000000025", "total_turnover": { "debet": 0, "debet_base": null, "credit": 100, "credit_base": null }, "total_balance": { "opening": 0, "opening_base": null, "closing": 100, "closing_base": null }, "transactions": [{ "amount": 10000, "base_amount": null, "currency": "RUB", "payment_date": "2022-11-13", "bank_system_id": "2080040097819020", "transaction_id": "c7b923ec-844f-4d98-ad02-795d62fe1989", "session_id": "ps_3230", "purpose": "Account replenishment", "counter_party": { "kpp": "165501001", "inn": "1655415696", "name": "Fee for money transfer processing services", "account_number": "70606810600004710401", "bank_code": "049205131" }, "type": "credit" }] } } } ``` Unsuccessful response examples `date_from` does not match `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (max interval is 1 day)", "code": "invalid_request" } } ``` `date_from` is greater than `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (date_to must be greater than date_from); (max interval is 1 day)", "code": "invalid_request" } } ``` Invalid date in `date_from` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_from", "code": "invalid_request" } } ``` Invalid date in `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_to", "code": "invalid_request" } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` This response is returned in the following cases: - the account number is specified incorrectly - the specified account does not exist - the specified account does not belong to the user who initiated the request ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` ### `session/status` #### Obtaining session information You can send this request if you want to obtain full information about the payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment. The response contains the payment session with details about all the operations performed during it. #### Endpoint `/api/v1/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ 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_3230" }' ``` ```php showLineNumbers 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); $response = $client->session()->status('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "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": "in_progress", "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", "bin": "220220" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers 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); $response = $client->session()->status('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "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", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "bin": "220220" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `token/info` #### Receiving information via token Operations with bank cards are often carried out with tokenized values. For payouts and payments through widgets, a public token is created. A token ca also be created for recurring payments. For any payment token you can get information: - About the bank card for which that token was created – this will be the hidden card number and payment system. - About the token itself – type of token, time of creation, expiration date, active or inactive at the moment of inquiry. This method can be used, for example, to learn the hidden card number and show the user which card the funds will be debited from. Or if you need to check the token expiration date. #### Endpoint `/api/v1/token/info` #### Request parameters | Name | Mandatory | Type | Description | |-----------------|---------------------------------------------|--------|----------------------------------------------------------------------------------------| | `type` | + | string | Type of request. Options: `card`, `public_token`, `recurrent_token`, `bank_account_ru` | | `card` | - (mandatory for `type = card`) | object | [Bank card details](/reference/reference-objects.mdx#card) | | `public_token` | - (mandatory for `type = public_token`) | object | [Token details](/reference/reference-objects.mdx#public_token) | | `recurrent_token` | - (mandatory for `type = recurrent_token`) | object | [Token details](/reference/reference-objects.mdx#recurrent_token) | | `bank_account_ru` | - (mandatory for `type = bank_account_ru`) | object | [Bank account details](/reference/reference-objects.mdx#bank_account_ru) | Information request examples You send a card number hash and receive information about it. ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "card_number_hash (token)" } } }' ``` You send a public token and receive information about it. ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "public_token", "public_token": { "token": "your_token" } }' ``` You send a token and receive information about it. ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "recurrent_token", "recurrent_token": { "token": "your_token" } }' ``` You send a token and receive information about it. ```json showLineNumbers curl -X POST \ https://proxy-stage.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "bank_account_ru", "bank_account_ru": { "token": "4371c4633033d3e7f468c8ca5f50f7dd10c00fe8655563c3da759c16b505ba93" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | | ------ | --------- | ------------ | ------------------------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok` | | `info` | - | object | Information about the token, depending on the type of request (`type`): [tokenized bank card](/reference/reference-objects.mdx#card_token_info), [public token](/reference/reference-objects.mdx#public_token_info), [token for recurring payments or payouts](/reference/reference-objects.mdx#info_recurrent), or [bank account token](/reference/reference-objects.mdx#bank_account_ru_info) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "info": { "number_hash": "card_number_hash", "brand": "visa", "last4": "4242", "type": "card" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2021-03-17T14:10:56+03:00", "finished_at": "2021-03-18T14:10:56+03:00", "is_active": true, "type": "public_token" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2021-03-17T14:19:05+03:00", "finished_at": "2021-04-17T14:19:05+03:00", "is_active": true, "type": "recurrent_token" } } ``` ```json showLineNumbers { "status": "ok", "info": { "masked_account": "40817***9535", "created_at": "2024-02-08T17:17:44+03:00", "finished_at": "2124-02-08T17:17:44+03:00", "type": "bank_account_ru" } } ``` ### `wallet/balance` You can use this request to check your current Bank 131 deposit balance. :::note This method can be used for payouts only. You can find your acquiring balance information in your remote banking service account in the [Statements](https://manual.131.ru/en/statements) section, provided that compensations are paid to your Bank 131 account. ::: This is necessary in order to make sure there is enough money on the balance: - for payouts - for returns If the amount is insufficient, you can top up your deposit. > The request does not return the information about your escrow account balance. You may find this information in your remote banking service account in the [Accounts](https://manual.131.ru/en/accounts) section or use the [`report/account_balance`](/reference/methods#reportaccount_balance) method. #### Endpoint `/api/v1/wallet/balance` #### Request parameters | Name | Mandatory | Type | Description | | ----------------- | --------- | ------ | ---------------------------- | | `request_datetime` | + | string | Timestamp of the request in ISO 8601 | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/wallet/balance \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_datetime": "2019-10-14T19:53:00+03:00" }' ``` ```php showLineNumbers 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); $walletBalanceResponse = $client->wallet()->balance(); $wallets = $walletBalanceResponse->getWallets(); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `wallets` | - | object | [List of guarantee payment accounts available at Bank 131](/reference/reference-objects.mdx#wallets) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "wallets": [{ "id": "131", "amount_details": { "amount": 13100, "currency": "rub" } }] } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Self-employed people ### `npd/accruals` and `npd/request/status` The method allows to obtain detailed information about tax accruals and bonus amount for the self-employed. The request consists of two parts: 1. Send an `npd/accruals` request, passing a self-employed person's details, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive detailed information about tax accruals and bonus amount for the self-employed. #### The endpoint to send the `npd/accruals` request `/api/v1/npd/accruals` #### Request parameters for `npd/accruals` | Name | Mandatory | Type | Description | | --------------------- | -------------- | ------ | --------------------------------------------------------------------------- | | `tax_reference_list` | + | array | List of tax reference numbers (INN). Limited to 100 INNs per single request| Request example for npd/accruals ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/accruals \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference_list": [ "111111111111" ] }' ``` #### Response parameters for `npd/accruals` | Name | Mandatory | Type | Description | |--------------|-----------|--------|---------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | - | string | Identifier | Response example for npd/accruals ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/accruals` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `accruals` | - | jagged array | | |   `tax_charge_list`| - | array | List of various taxes accrued | |     `amount` | - | string | Accrued amount | |     `due_date` | - | string | Payment due date | |     `tax_period_id` | - | string | Tax period identifier. The value format: YYYYMM | |     `oktmo` | - |string | Russian National Classification of Municipal Territories (OKTMO) of the activity region | |     `kbk` | - | string | Budgetary classification code | |     `paid_amount` | - |string | Amount of payments received in Automated Information System (AIS) Tax 3 by this accrual | |     `create_time` | - | string | Date and time of the tax accrual | |     `id` | - | string | Internal identifier of the tax accrual in the Self-employment tax (NPD) Payment order (PP) | |   `krsb_list` | - | array | Debt data by the fiscal compliance card | |     `debt` | - | string | Debt amount by the fiscal compliance card | |     `penalty` | - | string | Penalty amount by the fiscal compliance card | |     `overpayment` | - |string | Overpayment amount by the fiscal compliance card | |     `oktmo` | - | string | Russian National Classification of Municipal Territories (OKTMO) of the activity region related to the fiscal compliance card (KRSB) | |     `kbk` | - | string | Budgetary classification code related to the fiscal compliance card (KRSB) | |     `tax_organ_code` | - | string | Code of the tax authority related to the fiscal compliance card (KRSB) | |     `update_time` | - | string | Date / Time of card revision in the Self-employment tax (NPD) Payment order (PP) | |     `id` | - | string | Internal identifier of the card in the Self-employment tax (NPD) Payment order (PP) | |   `inn` | - | string | Tax reference number (INN) | Response example for npd/request/status ```json showLineNumbers { "status": "ok", "accruals": [{ "tax_charge_list": [{ "amount": "", "due_date": "", "tax_period_id": "", "oktmo": "", "kbk": "", "paid_amount": "", "create_time": "", "id": "" }], "krsb_list": [{ "debt": "", "penalty": "", "overpayment": "", "oktmo": "", "kbk": "", "tax_organ_code": "", "update_time": "", "id": "" }], "inn": "111111111111" }] } ``` ### `npd/notifications/count` and `npd/request/status` The method allows to obtain the number of unread notifications the Federal Tax Service sent to the self-employed. The request consists of two parts: 1. Send an `npd/notifications/count` request, passing a self-employed person's details, and receive the `request_id` identifier in response. 2. Periodically send an `npd/request/status` request with this identifier. In response, you will receive the number of unread notifications. The `pending` status indicates that you must repeat the request. #### The endpoint to send the `npd/notifications/count` request `/api/v1/npd/notifications/count` #### Request parameters for `npd/notifications/count` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `tax_reference_list` | + | array | List of tax reference numbers (INN) (limited to 1000 per single request) | Request example for npd/notifications/count ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/count \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference_list": [ "123456789012" ] }' ``` #### Response parameters for `npd/notifications/count` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | + | string | Identifier | Response example for npd/notifications/count ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/count` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | --------- | --------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `info` | - | array | [Number of notifications](/reference/reference-objects.mdx#notification_count_info) | Response example for npd/request/status ```json showLineNumbers { "status": "ok", "info": [{ "tax_reference": "123456789012", "count": 0 }] } ``` ### `npd/notifications/mark_as_delivered` and `npd/request/status` The method allows to inform the Federal Tax Service that notifications were delivered to a self-employed person. This method must be used after the [`notifications/read`](/reference/methods#read) method. The request consists of two parts: 1. Send an `npd/notifications/mark_as_delivered` request, passing a self-employed person's details, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive the status of the delivery. #### The endpoint to send the `npd/notifications/mark_as_delivered` request `/api/v1/npd/notifications/mark_as_delivered` #### Request parameters for `npd/notifications/mark_as_delivered` | Name | Mandatory | Type | Description | | ------------------ | ----------| ----- | --------------------------------- | | `notification_list` | + | array | [Information about notifications](/reference/reference-objects.mdx#notification_list) | Request example for npd/notifications/mark_as_delivered ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/mark_as_delivered \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "notification_list": [{ "message_id_list": [ "123", "234" ], "tax_reference": "123456789012" }] }' ``` #### Response parameters for `npd/notifications/mark_as_delivered` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier | Response example for npd/notifications/mark_as_delivered ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/read` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | Response example for npd/request/status ```json showLineNumbers { "status": "ok" } ``` ### `npd/notifications/read` and `npd/request/status` The method allows to obtain the detailed information about unread notifications the Federal Tax Service sent to the self-employed. The request consists of two parts: 1. Send an `npd/notifications/read` request, passing a self-employed person's details, and receive the `request_id` identifier in response. 2. Periodically send an `npd/request/status` request with this identifier. In response, you will receive detailed information about unread notifications. The `pending` status indicates that you must repeat the request. #### The endpoint to send the `npd/notifications/read` request `/api/v1/npd/notifications/read` #### Request parameters for `npd/notifications/read` | Name | Mandatory | Type | Description | |----------------------|-----------|---------|---------------------------------------------------------------------------------------------------------| | `tax_reference_list` | + | array | List of tax reference numbers (INN) | | `get_read` | + | boolean | Send the already read notifications in response. Possible values: `true` – send; `false` – do not send | | `get_archived` | + | boolean | Send the archived notifications in response. Possible values: `true` – send; `false` – do not send | Request example for npd/notifications/read ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/read \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference_list": [ "123456789012" ], "get_read": false, "get_archived": false }' ``` #### Response parameters for `npd/notifications/read` | Name | Mandatory | Type | Description | |--------------|-----------|--------|---------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | + | string | Identifier | Response example for npd/notifications/read ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/read` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `info` | - | array |[ List of parameters for each tax reference number (INN)](/reference/reference-objects.mdx#notification_info)| Response example for npd/request/status ```json showLineNumbers { "status": "ok", "info": [{ "tax_reference": "123456789012", "notifications": [{ "id": "132313", "title": "131.ru is asking for permission to act on your behalf", "message": "131.ru has asked you for permission to perform certain operations on your behalf. You can view the list of the operations and grant the permission by clicking Allow, or deny by clicking Deny", "status": "NEW", "created_at": "2023-03-22T13:29:55+00:00" }] }] } ``` ### `npd/notifications/update` and `npd/request/status` The method allows to inform the Federal Tax Service that notifications were read by the self-employed. The method must be used after the [`notifications/mark_as_delivered`](/reference/methods#mark_as_delivered) method. The request consists of two parts: 1. Send an `npd/notifications/update` request, passing a self-employed person's details, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive the status of the request. #### The endpoint to send the `npd/notifications/update` request `/api/v1/npd/notifications/update` #### Request parameters for `npd/notifications/update` | Name | Mandatory | Type | Description | | ------------------ | --------- | ------ | ------------------------------ | | `notification_list` | + | array | [Information about notifications](/reference/reference-objects.mdx#notification_list) | Request example for npd/notifications/update ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/update \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "notification_list": [{ "tax_reference": "123456789012" }] }' ``` #### Response parameters for `npd/notifications/update` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | - | string | Identifier | Response example for npd/notifications/update ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/update` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | Response example for npd/request/status ```json showLineNumbers { "status": "ok" } ``` ### `npd/taxpayer/account_status` and `npd/request/status` The method allows to obtain general information about tax accruals and bonus amount for the self-employed. The request consists of two parts: 1. Send an `npd/taxpayer/account_status` request, passing a self-employed person's details, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive general information about tax accruals and bonus amount for the self-employed. #### The endpoint to send the `npd/taxpayer/account_status` request `/api/v1/npd/taxpayer/account_status` #### Request parameters for `npd/taxpayer/account_status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `tax_reference` | + |string | Tax reference number (INN). Limited to 1 INN per single request | Request example for npd/taxpayer/account_status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/taxpayer/account_status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference": "123456789012" }' ``` #### Response parameters for `npd/taxpayer/account_status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | - | string | Identifier | Response example for npd/taxpayer/account_status ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/taxpayer/account_status` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `bonus_amount`| - | string | Bonus amount | | `unpaid_amount` | - | string | Total unpaid amount | | `debt_amount`| - | string | Unpaid debt, included into total unpaid amount| Response example for npd/request/status ```json showLineNumbers { "status": "ok", "bonus_amount": "9972.3624", "unpaid_amount": "0", "debt_amount": "0" } ``` ### `npd/taxpayer/check_personal_info` and `npd/request/status` #### Verification of the self-employed data This request allows to verify with the Federal Tax Service if there is any inconsistency in data (INN, full name, phone number) provided by a self-employed person. The request consists of two parts: 1. Send an `npd/taxpayer/check_personal_info` request, passing a self-employed person's INN, full name, and phone number, and receive the `request_id` identifier in response. 2. Periodically send an `npd/request/status` request with this identifier. In response, you will receive a list of inconsistent parameters, if there is any. The `pending` status indicates that you must repeat the request. #### The endpoint to send the `npd/taxpayer/check_personal_info` request `/api/v1/npd/taxpayer/check_personal_info` #### Request parameters for `npd/taxpayer/check_personal_info` | Name | Mandatory | Type | Description | | ------------- | -------------- | ------ | ----------- | | `first_name` | + | string | First name | | `second_name` | + | string | Family name | | `patronymic` | + | string | Patronymic name | | `tax_reference` | + | string | Tax reference number (INN) | | `phone` | + | string | Phone number in the "7ХХХХХХХХХХ" format | Request example for npd/taxpayer/check_personal_info ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/taxpayer/check_personal_info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "bonus_amount": "9972.3624", "unpaid_amount": "0", "debt_amount": "0" }' ``` #### Response parameters for `npd/taxpayer/check_personal_info` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier | Response example for npd/taxpayer/check_personal_info ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### The endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/taxpayer/check_personal_info` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ------------------------------- | -------------- | ------------ | ---------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `success` | - | bool | Inconsistency in data. `true` - consistent data; `false` - inconsistent data | | `violations` | - | array[string] | Parameters with inconsistent data. Possible values: "first_name", "second_name", "patronymic", "tax_reference", "phone"| | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response example for npd/request/status ```json showLineNumbers { "status": "ok", "success": false, "violations": [ "first_name", "second_name", "phone" ] } ``` ## Escrow account ### `session/create/nominal` #### Creating a payment session This request creates a payment session on Bank 131's side. Payment operations can only be performed within a session. Use this request if you need to request the data necessary to perform a payout from the user. For example, call the tokenization widget, show it to the user and get tokenized account details, and then send the payout request with those details. >If you are ready to provide all the data needed to perform the operation in the request, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. #### Endpoint `/api/v1/session/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/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": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payments": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payout_list": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/nominal` #### Creating a session with a simultaneous payout to a bank account You can use this request to send payouts from an escrow account to a bank account, including via [FPS](/payouts/payout-fps-phone#payout-nominal). #### Endpoint `/api/v1/session/init/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/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": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/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": "Funds transfer according to the contract for December of 2022 VAT exempt." }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payments": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/init/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payout_list": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/multi/create/nominal` #### Creating a payment session Creates a payment session on Bank 131's side. Payment operations can only be performed within a session. One or more operations can be performed within the session. Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. > If you are ready to provide all the data needed to perform the operation in the request, you can use the [`session/multi/init/payment/nominal`](/reference/methods#sessionmultiinitpaymentnominal) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. #### Endpoint `/api/v1/session/multi/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/init/payment/nominal` #### Creating a session with a simultaneous payout to a bank card This request can be used if you are ready to pass all the parameters needed for the payout at once. The response contains the parameters of the session created and an array with information about the payout (`acquiring_payment`/`payment_list`). #### Endpoint `/api/v1/session/multi/init/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/init/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/init/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/start/payment/nominal` #### Starting a payout to bank card This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed. If you are using the widget for getting the user's tokenized bank card details, you can pass them using this request. #### Endpoint `/api/v1/session/multi/start/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/start/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | + | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/start/payout/nominal` #### Starting a payout to a bank account You can use this request to send payouts from an escrow account to a bank account, including via [FPS](/payouts/payout-fps-phone#payout-nominal). This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed. If you are using the widget for getting the user's tokenized bank account details, you can pass them using this request. #### Endpoint `/api/v1/session/start/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payment_method": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payments": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `session_id` | + | string | Payment session identifier | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payout_details": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payout_list": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Settlement account ### `session/create/rko` #### Creating a payment session This request creates a payment session on Bank 131's side. Payment operations can only be performed within a session. Use this request if you need to request the data necessary to perform a payout from the user. For example, call the tokenization widget, show it to the user and get tokenized account details, and then send the payout request with those details. >If you are ready to provide all the data needed to perform the operation in the request, you can use the [`session/init/payout/rko`](/reference/methods#payout-rko) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. #### Endpoint `/api/v1/session/create/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/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": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/create/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/rko` #### Creating a session with a simultaneous payout to a bank account You can use this request to send payouts from a settlement account to a bank account. #### Endpoint `/api/v1/session/init/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers 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": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/init/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/multi/create/rko` Creates a payment session on Bank 131's side. Payment operations can only be performed within a session. One or more operations can be performed within the session. Use this request if you need to request the data necessary to perform a payout from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. > If you are ready to provide all the data needed to perform the operation in the request, you can use the ([`session/multi/init/payment/rko`](/reference/methods#sessionmultiinitpaymentrko)) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. #### Endpoint `/api/v1/session/multi/create/rko` | Name | Mandatory | Type | Description | |-----------------------|-----------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transaction details](/reference/objects#payment_details) | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory for payouts to bank cards) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers 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: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "****************" } } }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/create/rko` | Name | Mandatory | Type | Description | |-----------------------|-----------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transaction details](/reference/objects#payment_details) | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory for payouts to bank cards) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "****************" } } }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/init/payment/rko` #### Creating a session with a simultaneous payout to a bank card This request can be used if you are ready to pass all the parameters needed for the payout right away. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. #### Endpoint `/api/v1/session/multi/init/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/init/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/init/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/start/payment/rko` #### Starting a payout to a bank card This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Either, you can change pieces of data that have already been passed. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. #### Endpoint `/api/v1/session/multi/start/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session id | | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers 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: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/start/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session id | | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/start/payout/rko` #### Starting a payout to a bank account This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed. If you are using the widget for getting the user's tokenized bank account details, you can pass them using this request. #### Endpoint `/api/v1/session/start/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Money transfers ### `calculate` This method is used to calculate currency exchange rates for money transfers. There are two ways to calculate the currency exchange rate for a money transfer: - Direct rate: specify the amount to be sent in rubles and calculate the amount to be received in the target currency. - Inverse rate: specify the amount to be received in the target currency and calculate the amount to be sent in rubles. #### Endpoint `/api/v1/calculate` #### Request parameters | Name | Mandatory | Type | Description | |----------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amounts` | + | object | [Exchange amount and currency](/reference/reference-objects.mdx#amounts_transfers) | |   `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | |     `amount` | + | number | Amount in decimal format (kopecks) to calculate the direct exchange rate, or the `null` value to calculate the inverse exchange rate | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. The `rub` value is mandatory in either of the following objects: `source.currency` or `destination.currency` | |   `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | |     `amount` | + | number | Amount in decimal format (kopecks) to calculate the inverse exchange rate, or the `null` value to calculate the direct exchange rate | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. The `rub` value is mandatory in either of the following objects: `source.currency` or `destination.currency` | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |----------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amounts` | + | object | [Exchange rate calculation](/reference/reference-objects.mdx#amounts_transfers) | |   `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | |     `amount` | + | number | Amount calculated in the sender's currency (rubles) | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | |     `amount` | + | number | Calculated amount to be received | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `transfer_fee` | + | object | [Sender's fee for money transfer](/reference/reference-objects.mdx#transfer_fee) | |     `amount` | + | number | Fee amount to be paid by the sender for the money transfer | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub` | |   `sms_fee` | + | object | [Sender's fee for SMS notification to the recipient](/reference/reference-objects.mdx#sms_fee) | |     `amount` | + | number | Fee amount to be paid for SMS notification to the recipient | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub` | |   `payment` | + | object | [Total amount to write off of the sender](/reference/reference-objects.mdx#payment) | |     `amount` | + | number | Total amount to be written off the sender including all fees. Calculated as `source` + `transfer_fee` + `sms_fee` | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub` | | `exchanges` | + | object | [Exchange rate data](/reference/reference-objects.mdx#exchanges) | |   `source` | + | object | [Amount and currency to write off of the sender (passed in the request)](/reference/reference-objects.mdx#source) | |     `amount` | + | number | Amount in decimal format (kopecks) to calculate the direct exchange rate, or the `null` value to calculate the inverse exchange rate | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `destination` | + | object | [Amount and currency to be paid to the recipient (passed in the request)](/reference/reference-objects.mdx#destination) | |     `amount` | + | number | Amount in decimal format (kopecks) to calculate the inverse exchange rate, or the `null` value to calculate the direct exchange rate | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `rate` | + | object | [Exchange rate](/reference/reference-objects.mdx#rate) | |     `fx_rate` | + | number | Ratio of the currency to ruble (of the target currency to the write-off currency), displayed to 4 decimals. Example: `75.0145` | |     `quantity` | + | number | Quantity of currency units. Some currencies are calculated in tens, hundreds or thousands of units, [the current rates are available on the Bank of Russia website](https://cbr.ru/currency_base/daily) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "amounts": { "source": { "amount": 357913, "currency": "RUB" }, "destination": { "amount": 131426, "currency": "TRY" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 5400, "currency": "RUB" } }, "exchanges": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" }, "rate": { "fx_rate": 2.7233, "quantity": 1 } } } ``` ```json showLineNumbers { "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 9193, "currency": "RUB" } }, "exchanges": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "rate": { "fx_rate": 76.2433, "quantity": 10000 } } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ### `session/multi/init` This method is designed to initiate a cross-border transfer. #### Endpoint `/api/v2/session/multi/init` #### Request parameters | Name | Mandatory | Type | Description | |---------------------------------------------------------------------------|----------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `payment_list` | + | array | List of outgoing transactions from the sender | |   `amount_details` | + | object | [Payout amount details](/reference/reference-objects.mdx#amount_details). This value mirrors `payout_list.amount_details` | |     `amount` | + | number | Amount in decimal format (kopecks). To send 100 rubles, specify `10000` | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `customer` | + | object | [Data about the user (payout recipient or payment sender) in your system](/reference/reference-objects.mdx#customer) | |     `reference` | + | string | Identifier of the user (payout recipient or payment sender) in your system | |   `participant_details` | + | object | Information on transfer participants | |     `sender` | + | object | Sender details | |       `first_name` | + | string | First name | |       `last_name` | + | string | Last name | |       `middle_name` | - | string | Patronymic name | |       `tax_reference` | + | string | Sender's INN (12 digits) | |       `date_of_birth` | + | string | Sender's date of birth in the *YYYY-MM-DD* format. Make sure the sender is 18 years old or older | |       `identity_document` | + | object | [Sender's identity document](/reference/reference-objects.mdx#identity_document) | |         `id_type` | + | string | Type of the sender's identity document. Possible values:- `Passport of a citizen of the Russian Federation`- `Non-resident ID` | |         `id_number` | + | string | Sender's identity document series and number (without spaces) | |         `issue_date` | + | string | Sender's identity document issue date in the *YYYY-MM-DD* format | |         `id_expiration_date` | - | string | Sender's non-resident identity document expiration date in the *YYYY-MM-DD* format | |         `division_code` | - | string | Code of the division that issued the sender's identity document. **Required if available in the document** | |         `issued_by` | - | string | Name of the division that issued the sender's identity document. **Required if available in the document** | |       `citizenship_country_iso3` | + | string | Sender's country of citizenship according to ISO 3166-1 alpha-3 | |       `contacts` | + | array | [Sender's contacts](/reference/reference-objects.mdx#contactsObject) | |         `email` | - | string | Sender's email | |         `phone` | + | object | [Sender's phone number details](/reference/reference-objects.mdx#phone) | |           `full_number` | + | string | Sender's full phone number in the `+` format | |           `country_iso3` | - | string | Sender's phone number country code (ISO 3166-1 alpha-3). Only for transfers to Turkey with cash pick-up | |           `operator_code` | - | string | Operator's code of the phone number. Only for transfers to Turkey with cash pick-up | |           `short_number` | - | string | Phone number without the operator's code. Only for transfers to Turkey with cash pick-up | |       `country_iso3` | + | string | Country code (ISO 3166-1 alpha-3) | |       `postal_code` | - | string | Postal code of the sender's place of registration | |       `state` | - | string | State or region of the sender's place of registration | |       `city` | + | string | Locality of the sender's place of registration | |       `street` | - | string | Street of the sender's place of registration | |       `building` | + | string | Building number of the sender's place of registration | |       `flat` | - | string | Apartment of the sender's place of registration | |   `payment_options` | - | object | [Payment parameters](/reference/reference-objects.mdx#payment_options) | |     `return_url` | - | string | URL to redirect the user after payment completion. The URL must be valid | |     `recurrent` | - | bool | Whether to make the payment using a saved token. Pass the bank card token in `payment_details` | |   `payment_details` | + | object | [Write-off details](/reference/reference-objects.mdx#payment_details) | |     `type` | + | string | Type of payment method. Possible values:- `card` — bank card- `recurrent` — transaction with previously saved card details | |     `card` | - | object | [Bank card details](/reference/reference-objects.mdx#card) для `type` = `card` | |     `recurrent` | - | object | [Bank card token data](/reference/reference-objects.mdx#recurrent_token_info) для `type` = `recurrent` | | `payout_list` | + | array | List of incoming transactions to the recipient | |   `amount_details` | + | object | [Payout amount details](/reference/reference-objects.mdx#amount_details). This value mirrors `payment_list.amount_details` | |     `amount` | + | number | Amount in decimal format (kopecks). To send 100 rubles, specify `10000` | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `participant_details` | + | object | Information on transfer participants | |     `recipient` | + | object | Recipient details | |       `first_name` | + | string | First name | |       `last_name` | + | string | Last name | |       `middle_name` | - | string | Patronymic name | |       `tax_reference` | - | string | Recipients's INN (12 digits) | |       `date_of_birth` | - | string | Recipients's date of birth in the *YYYY-MM-DD* format. Make sure the recipient is 18 years old or older | |       `identity_document` | - | object | [Recipient's identity document](/reference/reference-objects.mdx#identity_document) | |         `id_type` | + | string | Type of the recipient's identity document. Possible values:- `Passport of a citizen of the Russian Federation`- `Non-resident ID` | |         `id_number` | + | string | Recipient's identity document series and number (without spaces) | |         `issue_date` | + | string | Recipient's identity document issue date in the *YYYY-MM-DD* format | |         `id_expiration_date` | - | string | Recipient's non-resident identity document expiration date in the *YYYY-MM-DD* format | |         `division_code` | - | string | Code of the division that issued the recipient's identity document. **Required if available in the document** | |         `issued_by` | - | string | Name of the division that issued the recipient's identity document. **Required if available in the document** | |       `citizenship_country_iso3` | + | string | Recipient's country of citizenship according to ISO 3166-1 alpha-3 | |       `contacts` | + | array | [Recipient's contacts](/reference/reference-objects.mdx#contactsObject) | |         `email` | - | string | Recipient's email | |         `phone` | + | object | [Recipient's phone number details](/reference/reference-objects.mdx#phone) | |           `full_number` | + | string | Recipient's full phone number in the `+` format | |           `country_iso3` | - | string | Recipient's phone number country code (ISO 3166-1 alpha-3). Only for transfers to Turkey with cash pick-up | |           `operator_code` | - | string | Operator's code of the phone number. Only for transfers to Turkey with cash pick-up | |           `short_number` | - | string | Phone number without the operator's code. Only for transfers to Turkey with cash pick-up | |       `purpose` | - | string | Transfer purpose. If `recipient.country_iso3` = `AZE`:- `gift`- `donation`- `support`- `education`- `other` | |       `country_iso3` | - | string | Country code (ISO 3166-1 alpha-3) | |       `postal_code` | - | string | Postal code of the recipient's place of registration | |       `state` | - | string | State or region of the recipient's place of registration | |       `city` | - | string | Locality of the recipient's place of registration | |       `street` | - | string | Street of the recipient's place of registration | |       `building` | - | string | Building number of the recipient's place of registration | |       `flat` | - | string | Apartment of the recipient's place of registration | |   `payout_details` | + | object | [Payout details](/reference/reference-objects.mdx#payment_method) | |     `type` | + | string | Transfer receiving options. Options: - `card` (to a bank card) - `bank_account` (IBAN) - `tokenized_card` (to previously saved card details) - `moneysend` (in cash) | |     `card` | - | object | [Bank card details](/reference/reference-objects.mdx#card) for `type` = `card` | |     `bank_account` | - | object | [IBAN](/reference/reference-objects.mdx#bank_account) for `type` = `bank_account` | |     `tokenized_card` | - | object | [Bank card token data](/reference/reference-objects.mdx#tokenized_card) for `type` = `tokenized_card` | |     `moneysend` | - | object | Pass the object for cash transfers, always empty: `{}` | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 37700, "currency": "TJS" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "TRY", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "contacts": { "phone": { "full_number": "+79376151530", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TJK", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2204320396205389" } } } }] }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 1000, "currency": "TRY" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "RUS", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "issued_by": "ОВД ПО Кировскому району", "division_code": "123-543" }, "contacts": { "phone": { "full_number": "+79376151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 1000, "currency": "TRY" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TRY", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } } }] }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | + | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808365", "status": "in_progress", "created_at": "2025-08-08T12:39:15.668563Z", "updated_at": "2025-08-08T12:39:16.388348Z", "payout_list": [{ "id": "po_955259", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439833Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765898", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439730Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+79376151530", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808544", "status": "in_progress", "created_at": "2025-08-11T07:39:00.076932Z", "updated_at": "2025-08-11T07:39:00.476548Z", "payout_list": [{ "id": "po_955266", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528662Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TRY", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2766065", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528558Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "division_code": "123-543", "issued_by": "ОВД ПО Кировскому району" }, "citizenship_country_iso3": "RUS", "contacts": { "phone": { "full_number": "+79376151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ## Other methods ### `sberpay/push` Method to send PUSH/SMS notifications to customers for SberPay transactions. #### Endpoint `/api/v1/sberpay/push` #### Request parameters | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------- | | `session_id` | + | string | Session ID | | `phone` | + | string | Phone number to send PUSH or SMS | Request example ```json showLineNumbers curl -X GET \ https://proxy.bank131.ru/api/v1/sberpay/push \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_75459435", "phone": "+79638594ххх" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|----------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `error` | - | object | [Error description](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok" } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` --- - [Objects](https://developer.131.ru/en/reference/objects): List of objects ## `accept_code` Data for sending a code. | Name | Mandatory | Type | Description | |------------------|----------------|--------|---------------------------------------------------| | `rest_of_attempts` | + | string | Number of code sending attempts | | `active_to` | + | string | Code lifetime | | `callback_url` | + | string | Address to which to send the code | ## `account_details` Information about the sender and recipient accounts. | Name | Mandatory | Type | Description | | ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------ | | `sender` | + | object | [Information about the sender account](/reference/reference-objects.mdx#nominal_payment_sender) | | `recipient` | + | object | [Information about the recipient account](/reference/reference-objects.mdx#nominal_payment_recipient) | ## `account_statement` Statement details. | Name | Mandatory | Type | Description | | -------------- | --------- | ------ | --------------------------------------------------------------- | | `date_from` | + | date | Statement start date | | `date_to` | + | date | Statement end date | | `account_number` | + | string | Account number (20 digits) for which the statement is generated | | `total_turnover` | - | object | [Information on funds movement](/reference/reference-objects.mdx#total_turnover) | | `total_balance` | - | object | [Balance information](/reference/reference-objects.mdx#total_balance) | | `transactions` | - | array | [Information on transactions](/reference/reference-objects.mdx#transactions) | ## `acquiring_payments` = `payment_list` >Use `acquiring_payments` for API v1, and `payment_list` for API v2. An array with all the payment details. | Name | Mandatory | Type | Description | |----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `id` | + | string | Unique payment identifier | | `status` | + | string | Payment status Possible values: `succeeded`, `in_progress`, `pending`, `failed` | | `created_at` | + | string | Creation date in ISO 8601 format | | `payment_details` | + | object | [Payment data](/reference/reference-objects.mdx#payment_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `amounts` | - | object | [Transaction fee](/reference/reference-objects.mdx#amounts) | | `finished_at` | - | string | Completion date in ISO 8601 format | | `customer` | + | object | [User (payer) details](/reference/reference-objects.mdx#customer) | | `recurrent` | - | object | [Details needed to perform recurring payments](/reference/reference-objects.mdx#recurrent_token_info) | | `participant_details` | - | object | [Participants' details](/reference/reference-objects.mdx#participant_details) | | `refunds` | - | array | [Refund list](/reference/reference-objects.mdx#refunds) | | `customer_interaction` | - | object | [Data needed for user interaction](/reference/reference-objects.mdx#customer_interaction) | | `transaction_info` | - | object | [Transaction details](/reference/reference-objects.mdx#transaction_info) | | `metadata` | - | object | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | | `error` | - | object | [Error description](/reference/reference-objects.mdx#error) |   #### Payment statuses (`status`) - `in_progress` – the payment is being processed. - `pending` – awaiting your confirmation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancellation ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). - `succeeded` – the payment has been completed successfully. - `failed` – the payment has not gone through due to an error. ## `acquiring_widget` Settings for the payout form widget (for performing bank card payments). | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Identifies the payment session for which the payment will be performed | | `show_recurrent_checkbox` | - | bool | Whether to display the **Enable automatic payments** checkbox in the widget interface | | `success_return_url` | - | string | URL to which the user is redirected after the payment has been successfully completed | | `failure_return_url` | - | string | URL to which the user is redirected when an error occurs during the payment | | `success_on_hold` | - | bool | Whether to show a message about a successful payment to a payer when holding. By default, `false` and the widget shows a loading screen until the end of the hold | | `redirect_target` | - | string | Redirect link open options: - `top` — outside of all the frames as the top window - `self` — in the same frame - `parent` — in the next-level frame if the frames are nested in one another. Default: `top` | ## `actions` Information about actions taken. | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------| | `confirm` | - | string | Confirmation date in ISO 8601 format | | `capture` | - | string | Capture date in ISO 8601 format | ## `amount` Amount object. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub`, `eur` | ## `amount_details` Amount object. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub`, `eur` | ## `amounts` Information on the transaction fee. | Name | Mandatory | Type | Description | | ---- | --------- | ------ | --------------------------------------------------------------------------------- | | `fee` | - | object | [Information on the applicable fee](/reference/reference-objects.mdx#fee) | ## `amounts` (for money transfers) The exchange amount, currency, and fees for money transfers. | Name | Mandatory | Type | Description | |--------------|-----------|--------|----------------------------------------------------------------------------------------------------| | `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | | `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | | `transfer_fee` | - | object | [Sender's fee for money transfer](/reference/reference-objects.mdx#transfer_fee) | | `sms_fee` | - | object | [Sender's fee for SMS notification to the recipient](/reference/reference-objects.mdx#sms_fee) | | `payment` | - | object | [Total amount to write off of the sender](/reference/reference-objects.mdx#payment) | ## `balance` Account balance details. | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | --------------------------- | | `current_balance` | - | string | Current account balance (the value can be positive or equal to 0). The value is specified in minor currency units (ruble decimal format). For 100 rubles, the value is `10000` | ## `bank_account` The payout recipient's account description. | Name | Mandatory | Type | Description | |------------------------------------|----------------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `system_type` | + | string | Bank payment system. Options: `ru`, `faster_payment_system`, `faster_payment_system_verification` | | `ru` | - (mandatory for `system_type = ru`) | object | [Recipient's Russian bank account (region: ru)](/reference/reference-objects.mdx#ru) | | `faster_payment_system` | - (mandatory for `system_type = faster_payment_system`) | object | [Recipient's data in the Faster Payment System](/reference/reference-objects.mdx#faster_payment_system) | | `faster_payment_system_verification` | - (mandatory for `system_type = faster_payment_system_verification`) | object | [Data for the recipient verification in the Faster Payment System](/reference/reference-objects.mdx#faster_payment_system_verification) | | `iban` | - | object | [Money transfer recipient's IBAN](/reference/reference-objects.mdx#iban) | ## `bank_account_ru` Bank account details. | Name | Mandatory | Type | Description | | ----------- | --------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `bik` | - (mandatory for the `tokenize` method) | string | Recipient’s Bank Identification Code | | `account` | - (mandatory for the `tokenize` method) | string | Recipient's bank account | | `token` | - (mandatory for the `token/info` method) | string | Bank account token | ## `bank_card` An unencrypted card object. | Name | Mandatory | Type | Description | |------------------|------------------------------------------|--------|---------------------| | `number` | + | string | Card number | | `expiration_month` | - (mandatory for payments if available) | string | Month | | `expiration_year` | - (mandatory for payments if available) | string | Year | | `security_code` | - (mandatory for payments if available) | string | CVC (security code) | | `cardholder_name` | - | string | Cardholder's name | ## `card` The payout recipient's bank card details. | Name | Mandatory | Type | Description | |----------------|-------------------------------------------|--------|--------------------------------------------------------------------------------------------------| | `type` | + (not returned in responses) | string | Card details transmission type. Possible values: `bank_card`, `encrypted_card`, `tokenized_card` | | `bank_card` | - (mandatory for `type = bank_card`) | object | [Unencrypted card](/reference/reference-objects.mdx#bankcard) | | `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Card with encrypted fields (tokenized)](/reference/reference-objects.mdx#encrypted_card) | | `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/reference-objects.mdx#tokenized_card) | | `brand` | - | string | Card information. Returned in notifications, needed for user display | | `last4` | - | string | Card information. Returned in notifications, needed for user display | | `bin` | - | string | Bank Identification Number (BIN) (the first 6 digits of a card number). To start getting this parameter, contact your account manager at Bank 131 | | `card_id` | - | string | [Card identifier](/payments/payment-intro#cross-identifier-card) | | `country_iso3` | - | string | Country code (ISO 3166-1 alpha-3) | ## `card_elements` The number of a card for tokenizing. | Name | Mandatory | Type | Description | |-------------|-----------|--------|-----------------------------------| | `ref` | + | string | Fixed value, always `number` | | `type` | + | string | Fixed value, always `card_number` | | `card_number` | + | string | Card number | ## `commission` The amount and currency of the commission for money transfers. | Name | Required | Type | Description | |----------|----------|--------|---------------------------------------------------------| | `amount` | + | number | Amount in decimal format to calculate the exchange rate | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `confirm_information` Confirmation information for a transaction. | Name | Mandatory | Type | Description | |------------------|----------------------------------|--------|--------------------------------------------------------------------------------------------------------| | `transfer_details` | + (for payouts to cards) | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_details) | | `account_details` | + (for payouts to bank accounts) | object | [Information about the sender and recipient accounts](/reference/reference-objects.mdx#account_details) | | `exchanges` | + (for money transfers) | object | [Information about exchange rates](/reference/reference-objects.mdx#exchanges) | ## `contacts` An array with the contacts of a user (payout recipient or payment sender). Parent objects: [`customer`](/reference/objects#customer). | Name | Mandatory | Type | Description | | ------ | --------- | ------ | ------------------- | | `email` | - | string | User's email | | `phone` | - | string | User's phone number | ## `contacts` (for money transfers) Contacts of a user (money transfer sender or recipient). Parent objects: [sender](/reference/objects#participant_details_sender), [recipient](/reference/objects#participant_details_recipient). | Name | Mandatory | Type | Description | |--------|-----------|--------|--------------------------------------------------------------| | `email` | - | string | User's email | | `phone` | - | object | [User's phone number](/reference/reference-objects.mdx#phone) | ## `counter_party` Counterparty details. | Name | Mandatory | Type | Description | |----------------|-----------|--------|-------------------------------| | `kpp` | - | string | Counterparty's KPP | | `inn` | - | string | Counterparty's INN | | `name` | + | string | Counterparty's name | | `account_number` | + | string | Counterparty's account number | | `bank_code` | + | string | Counterparty's bank BIK | ## `customer` (user in your system) Data about the user (payout recipient or payment sender) in your system, E.g. the login that lets you identify the user. Also includes their contact details. Parent arrays: [`acquiring_payments`/`payment_list`](/reference/reference-objects.mdx#acquiring_payments), [`payments`/`payout_list`](/reference/reference-objects.mdx#payments). | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------------------------------------------| | `reference` | + | string | Identifier of the user (payout recipient or payment sender) in your system (up to 128 characters) | | `contacts` | - | array | [User contacts](/reference/reference-objects.mdx#contacts) | ## `customer` (payer) Information about the payer of a payout from an escrow account. Parent objects: [`transfer_details`](/reference/reference-objects.mdx#transfer_details). | Name | Mandatory | Type | Description | | ---------------------------- | --------- | ------ | ---------------------------------------------------------- | | `account_number` | - | string | Account number | | `name` | - | string | Name | | `bank_name` | - | string | Bank's name | | `bik` | - | string | Bank's BIC | | `correspondent_account_number` | - | string | Correspondent account number | | `inn` | - | string | Bank's INN (for cash and settlement only) | | `kpp` | - | string | Bank's KPP (for cash and settlement only) | ## `customer_authorization` Information required for payments by Uzcard or Humo cards. | Name | Mandatory | Type | Description | |-------------|----------------|--------|--------------------------------------------------------------------------------------------------| | `type` | + | string | Authentication type. Always: `sms` | | `suspend_key` | + | string | Confirmation key required when sending a code | | `accept_code` | + | object | [Data for sending a code](/reference/reference-objects.mdx#accept_code) | | `resend_sms` | + | object | [Data for requesting a new code](/reference/reference-objects.mdx#resend_sms) | ## `customer_interaction` An object describing customer interaction. | Name | Mandatory | Type | Description | |----------|-------------------------------------|--------|------------------------------------------------------------------| | `type` | + | string | Customer interaction type. Possible values: `redirect`, `inform` | | `redirect` | - (mandatory for `type = redirect`) | object | [User redirect data](/reference/reference-objects.mdx#redirect) | | `inform` | - (mandatory for `type = inform`) | object | [Payment option data](/reference/reference-objects.mdx#inform) | ## `data` (user account) Masked user account data. | Name | Mandatory | Type | Description | | -------------- | -------------- | ------------------ | ------------------------------------------------- | | `masked_account` | + | string | First 5 and last 4 digits of an account | ## `data` (token and card number) Token and tokenized card details. Returns in response to the [`tokenize/elements`](/reference/reference-methods.mdx#tokenizeelements) request. | Name | Required | Type | Description | |--------|----------|--------|--------------------------------------------------------------| | `number` | + | object | [Token information](/reference/reference-objects.mdx#number) | ## `destination` The amount and currency to be paid to the recipient for money transfers. | Name | Required | Type | Description | |----------|----------|--------|---------------------------------------------------------| | `amount` | + | number | Amount in decimal format to calculate the exchange rate | | `currency` | + | string | ISO 4217 currency code. Case insensitive | Additional money transfer data. | Name | Required | Type | Description | |--------------------|-----------|--------|-------------------------------------------------------- | | `tcn_code_encoded` | + | string | Money transfer reference number. BASE64-encoded | */} ## `encrypted_card` Card with encrypted fields (tokenized). Transmitted during payouts or payments through the widget. | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ---------------------- | | `number_hash` | + | string | Card number hash | | `expiration_date_hash` | - | string | Expiration date hash | | `security_code_hash` | - | string | CVC code hash | | `cardholder_name_hash` | - | string | Cardholder's name hash | ## `error` Error description object. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------------- | | `code` | - | string | Error code | | `description` | - | string | Error description | [View error codes ](/reference/reference-errors.mdx) ## `exchanges` The exchange rate data for money transfers. | Name | Mandatory | Type | Description | |-------------|-----------|--------|--------------------------------------------------------------------------------------------------| | `id` | + | string | ID of the transaction (payout/payment) where the exchange rate was applied | | `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | | `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | | `fx_rate` | + | number | Exchange rate, displayed to 4 decimals | | `commission` | + | object | [Amount and currency of the commission for transfer](/reference/reference-objects.mdx#commission) | ## `faster_payment_system` Data of a user of the Faster Payment System for payouts and payments. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------------------------------------------------------------------------- | | `phone` | - (mandatory for payouts) | string | Recipient's phone number | | `bank_id` | - (mandatory for payouts) | string | Identifier of the recipient's bank in the FPS. To get the identifier, use the [`fps/banks`](/reference/reference-methods.mdx#banks_fps) method | | `description` | - (mandatory for payouts) | string | Payout or payment purpose | | `subscription_service_info` | - | object | [Subscription details](/reference/objects#subscription_service_info) | ## `faster_payment_system_verification` Data for the recipient verification in the Faster Payment System. | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `phone` | + | string | Recipient's phone number | | `bank_id` | + | string | Identifier of the recipient's bank in the FPS. To get the identifier, use the [`fps/banks`](/reference/reference-methods.mdx#banks_fps) method | ## `fee` Information on the applicable fee. The number of objects matches the number of applicable fees. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub`, `eur` | ## `fiscalization_details` Fiscalization details. | Name | Mandatory | Type | Description | |------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------| | `professional_income_taxpayer` | + | object | [Fiscalization details for the self-employed](/reference/reference-objects.mdx#professional_income_taxpayer) | ## `iban` Recipient's IBAN for a money transfer. | Name | Mandatory | Type | Description | |----------|----------------|--------|--------------------------------| | `account` | + | string | IBAN of a money transfer recipient | ## `identity_document` Identity document of a money transfer participant. | Name | Mandatory | Type | Description | |--------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `id_type` | + | string | Type of the recipient's identity document. Valid values:- Passport of a foreign citizen- Passport of a citizen of the Russian Federation | | `id_number` | + | string | Recipient's identity document series and number (without spaces) | | `issue_date` | + | string | Recipient's identity document issue date in the *YYYY-MM-DD* format | | `id_expiration_date` | - | string | Recipient's identity document expiry date in the *YYYY-MM-DD* format. **Required if available in the document. Otherwise, do not send this field** | | `division_code` | - | string | Code of the division that issued the recipient's identity document. **Required if available in the document** | | `issued_by` | - | string | Name of the division that issued the recipient's identity document. **Required if available in the document** | ## `info` (bank account token) Bank account token details. | Name | Mandatory | Type | Description | |----------------|-----------|--------|---------------------------------------| | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format | | `masked_account` | + | string | Masked bank account | | `type` | + | string | Token type. Always: `bank_account_ru` | ## `info` (tokenized bank card) Details of a tokenized bank card. Returns in response to the [`token/info`](/reference/reference-methods.mdx#token_info) request. | Name | Mandatory | Type | Description | |-------------|-----------|--------|-----------------------------| | `number_hash` | + | string | Token (tokenized bank card) | | `brand` | + | string | Payment system, i.e. `visa` | | `last4` | + | string | Last 4 card numbers | | `type` | + | string | Token type. Always: `card` | ## `info` (notifications number) The number of unread notifications for a self-employed person's tax reference number (INN). | Name | Mandatory | Type | Description | | ------------- | --------- | ------ | ------------------------------------------------------------- | | `tax_reference` | + | string | Tax reference number (INN) | | `count` | - | int | Number of unread notifications per each `tax_reference` value | ## `info` (notifications information) Detailed information about notifications for a self-employed person's tax reference number (INN). | Name | Mandatory | Type | Description | |---------------|-----------|--------|----------------------------------------------------------------------------------------------------| | `tax_reference` | + | string | Tax reference number (INN) | | `notifications` | - | array | [Notifications](/reference/reference-objects.mdx#notifications) for the value from `tax_reference` | ## `info` (public token) Information about a public token. Returns in response to the `token/info` request. | Name | Mandatory | Type | Description | |-------------|-----------|--------|--------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format | | `is_active` | + | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `type` | + | string | Token type. Always: `public_token` | ## `info` (token for recurring payments or payouts) Information about a token for recurring payments or payouts. [More information about recurring payments and token settings](/payments/payment-recurring.mdx). Returns in response to the `token/info` request. | Name | Mandatory | Type | Description | |-------------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format. The setting isn't processed by the Bank | | `is_active` | + | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | | `type` | + | string | Token type. Always: `recurrent_token` | ## `info` (tokenized card details) Tokenized card details. Returns in response to the [`tokenize/elements`](/reference/reference-methods.mdx#tokenizeelements) request. Parent objects: [`number`](/reference/reference-objects.mdx#number). | Name | Required | Type | Description | |--------------------|----------|--------|---------------------| | `masked_card_number` | + | string | Masked card number | | `card_network` | + | string | Card payment system | | `card_type` | + | string | Card type | ## `inform` Payment option data. | Name | Mandatory | Type | Description | |------|-----------|--------|---------------------------------------------------------------------| | `qr` | - | object | [QR code for payments via FPS](/reference/reference-objects.mdx#qr) | ## `internal_transfer` Information about an internal transfer | Name | Mandatory | Type | Description | |-------------------------------|----------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Transfer type. Possible values: `transfer_from_nominal_account`, `transfer_from_bank_account` | | `transfer_from_nominal_account` | - (mandatory for `type = transfer_from_nominal_account`) | object | [Information about a transfer from an escrow account](/reference/reference-objects.mdx#transfer_from_nominal_account) | | `transfer_from_bank_account` | - (mandatory for `type = transfer_from_bank_account`) | object | [Information about a transfer from a settlement account](/reference/reference-objects.mdx#transfer_from_bank_account) | ## `internet_banking` Details on payments via payment systems. | Name | Mandatory | Type | Description | |----------|-------------------------------------|--------|---------------------------------------------------------------------------------------| | `type` | + | string | Payment system. Possible values: `sber_pay`, `tpay` | | `sber_pay` | - (mandatory for `type = sber_pay`) | object | [SberPay payment system transaction details](/reference/reference-objects.mdx#sberpay) | ## `method` Method details. | Name | Mandatory | Type | Description | |-------------------|-----------|--------|------------------------------------------------------------------------| | `name` | + | string | Method name (`account_statement`) | | `account_statement` | + | object | [Statement details](/reference/reference-objects.mdx#account_statement) | | ## `notification_list` The array contains data for informing the Federal Tax Service about statuses of notifications sent to the self-employed. | Name | Mandatory | Type | Description | | --------------- | --------- | --------------- | -------------------------- | | `message_id_list` | - | array[string] | Array with message IDs | | `tax_reference` | + | string | Tax reference number (INN) | ## `notifications` The array contains detailed information about notifications the Federal Tax Service sends to a self-employed person. | Name | Mandatory | Type | Description | |------------|-----------|----------|--------------------------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Identifier | | `title` | + | string | Notification header | | `message` | + | string | Notification body | | `status` | + | string | Status. Possible values:`NEW` – new and unread notification`ACKNOWLEDGED` – read notification`ARCHIVED` – archived notification | | `created_at` | + | dateTime | Notification date | ## `number` Token and tokenized card details. | Name | Required | Type | Description | |-------|----------|--------|-----------------------------------------------------| | `token` | + | string | Token | | `info` | + | object | [Card information](/reference/objects#tokenize_info) | ## `participant_details` Payout participant details. | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------------------------------------| | `sender` | - | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | | `recipient` | - | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | ## `payee` Recipient data for tax payments with extended parameters. | Name | Required | Type | Description | | ----------- | -------- | ------ | --------------------------- | | `bik` | + | string | Recipient bank's BIK | | `account` | + | string | Account number | | `account_eks` | + | string | Unified Treasury Account | | `name` | + | string | Recipient name | | `inn` | + | string | Recipient's INN, 10 digits | ## `payer` Sender data for tax payments with extended parameters. | Name | Required | Type | Description | | ---- | -------- | ------ | ------------------------ | | `kpp` | + | string | Sender's KPP, 9 digits | | `inn` | + | string | Sender's INN, 10 digits | ## `payment` The total amount to write off of the sender for money transfers. | Name | Required | Type | Description | |----------|----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amount` | + | number | Total amount to be written off of the sender including all fees. Calculated as [`source`](/reference/reference-objects.mdx#source) + [`transfer_fee`](/reference/reference-objects.mdx#transfer_fee) + [`sms_fee`](/reference/reference-objects.mdx#sms_fee) | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `payment_details` The description of the method for performing the payment. | Name | Mandatory | Type | Description | |-----------------------|--------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Payment method type. Possible values: `card`, `recurrent`, `internet_banking`, `internal_transfer`, `faster_payment_system`, `wallet`, `moneysend` | | `card` | - (mandatory for `type = card`) | object | [Bank card details](/reference/reference-objects.mdx#card) | | `recurrent` | - (mandatory for `type = recurrent`) | object | [Details for repeating the payment using the token](/reference/reference-objects.mdx#recurrent) | | `internet_banking` | - (mandatory for `type = internet_banking`) | object | [Details on payments via payment systems](/reference/objects#internet_banking)| | `internal_transfer` | - (mandatory for `type = internal_transfer`) | object | [Internal transfer details](/reference/reference-objects.mdx#internal_transfer) | | `faster_payment_system` | - (mandatory for `type = faster_payment_system`) | object | [Payment via FPS](/reference/reference-objects.mdx#faster_payment_system) | | `wallet` | - (mandatory for `type = wallet`) | object | [Payment via wallet](/reference/reference-objects.mdx#wallet) | | `moneysend` | - (mandatory for `type = moneysend`) | object | Details of payment via Moneysend | ## `payment_method` = `payout_details` >Use `payment_method` for API v1, and `payout_details` for API v2. The description of the method for receiving the payout. | Name | Mandatory | Type | Description | |----------------|-------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Type of method for receiving the payout. Possible values: `card`, `bank_account`, `wallet`, `tax `, `recurrent`, `tokenized_card`, `moneysend` | | `card` | - (mandatory for `type = card`) | object | [Recipient's bank card](/reference/reference-objects.mdx#card) | | `bank_account` | - (mandatory for `type = bank_account`) | object | [Recipient's bank account](/reference/reference-objects.mdx#bank_account) | | `wallet` | - (mandatory for `type = wallet`) | object | [Recipient's electronic wallet](/reference/reference-objects.mdx#wallet) | | `tax` | - (mandatory for `type = tax`) | object | [ Payouts to the Russian Federal Tax Agency](/reference/reference-objects.mdx#tax) | | `recurrent` | - (mandatory for `type = recurrent`) | object | [Payout with token](/reference/reference-objects.mdx#recurrent) | | `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Payout with tokenized card number](/reference/reference-objects.mdx#tokenized_card) | | `moneysend` | - (mandatory for `type = moneysend`) | object | Details of payment via Moneysend | ## `payment_options` Parameters needed to perform the payment. :::warning Do not use `localhost` or `127.0.0.1` as the value of the `return_url` parameter—requests with these values will not be processed. ::: | Name | Mandatory | Type | Description | |------------|-----------|--------|-------------------------------------------------------------------------------------------------| | `return_url` | - | string | URL to which the user is redirected after the payment is performed **Mandatory for payments made without our payment widget** | | `recurrent` | - | bool | Determines whether the payment is to be performed using the saved token | |`platform_details`|- | object|[User's device data](/reference/reference-objects.mdx#platform_details) ## `payments` = `payout_list` >Use `payments` for API v1, and `payout_list` for API v2. An array of payout details. | Name | Mandatory | Type | Description | | --------------------- | --------- | ----------| ------------------------------------------------------------------------------------------------------------------------------- | | `id` | + | string | Payout identifier | | `status` | + | string | Status. Possible values: `succeeded`, `in_progress`, `pending`, `failed` | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | - | string | Completion date in ISO 8601 format | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer), e.g. the login that lets you verify the recipient on your side | | `payment_method`/`payout_details` | + | object | [Method of receiving the payout](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `amounts` | - | object | [Transaction fee](/reference/reference-objects.mdx#amounts) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object |[ The details of payout participants](/reference/reference-objects.mdx#participant_details) required to perform the payout, e.g. the names and addresses of the payer and the recipient | | `refunds` | - | array | [Refund list](/reference/reference-objects.mdx#refunds) | | `transaction_info` | - | object | [Transaction details](/reference/reference-objects.mdx#transaction_info) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | | `error` | - | object | [Error description](/reference/reference-objects.mdx#error) |   #### Payout statuses (`status`) - `in_progress` – the payment is being processed. - `pending` – awaiting your confirmation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancellation ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). - `succeeded` – the payout has been completed successfully. - `failed` – the payout has not gone through because of an error. ## `period` Tax period description. | Name | Mandatory | Type | Description | |--------|-----------|--------|------------------------------------------------------------------------------------------------| | `type` | + | string | Period type. Possible values: `month`, `quarter` | | `number` | + | number | Depends on the period type. Number from 1 to 12 for `month`, number from 1 to 4 for `quarter` | | `year` | + | string | Year, 4 digits. Example: `2021` | ## `phone` User's phone number details (money transfer sender or recipient). | Name | Mandatory | Type | Description | |---------------|-----------|--------|------------------------------------------------------------------------------------------------------| | `full_number` | + | string | User's full phone number in the `+` format | | `country_iso3` | - | string | User's phone number country code (ISO 3166-1 alpha-3). For transfers to Turkey with cash pickup only | | `operator_code` | - | string | Operator code of the user's phone number. For transfers to Turkey with cash pickup only | | `short_number` | - | string | User's phone number without the operator code. For transfers to Turkey with cash pickup only | ## `platform_details` User's device data. | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | User's device type. Acceptable values: `desktop`, `mobile` | | `os` | + | string | User's operating system. Acceptable values: `ios`, `android`, `windows`, `linux` | | `browser` | + | string | User's browser. Acceptable values: `chrome`, `firefox`, `jivoMobile`, `microsoft edge`, `miui`, `opera`, `safari`, `samsung`, `webKit`, `weChat`, `yandex` | ## `professional_income_taxpayer` Fiscalization details for the self-employed. | Name | Mandatory | Type | Description | |------------------|----------------------------------------|--------|----------------------------------------------------------------------------------------------| | `services` | + | array | [List of services provided (maximum 6)](/reference/reference-objects.mdx#services) | | `tax_reference` | + | string | Self-employed person's INN | | `receipt` | - | object | [Fiscalization receipt](/reference/reference-objects.mdx#receipt). Returned in notifications | | `payer_type` | - | string | [Payer type](#payer_type) | | `payer_tax_number` | - (mandatory for `payer_type = legal`) | string | Payer's INN | | `payer_name` | - (mandatory for `payer_type = legal`) | string | Payer name | #### Payer type Payer type. Possible values: - `legal` – legal entity - `individual` – individual person - `foreign` – non-resident of Russia ## `public_token` Information about a public token. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `qr` QR code for payments via FPS. | Name | Mandatory | Type | Description | | ------- | --------- | ------ | --------------- | | `content` | + | string | Link to QR code | | `img` | + | string | QR code body | ## `rate` The exchange rate for money transfers. | Name | Mandatory | Type | Description | |----------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fx_rate` | + | number | Ratio of the currency to ruble (of the target currency to the write-off currency), displayed to 4 decimals. Example: `75.0145` | | `quantity` | + | number | Quantity of currency units. Some currencies are calculated in tens, hundreds or thousands of units, [the current rates are available on the Bank of Russia website](https://cbr.ru/currency_base/daily) | ## `receipt` The data of the receipt created during fiscalization. | Name | Mandatory | Type | Description | |--------|-----------|--------|--------------------| | `id` | + | string | Receipt identifier | | `link` | - | string | Receipt link | ## `recipient` (recipient of a payout from an escrow account) Information about the recipient of a payout from an escrow account. Parent objects: [`transfer_details`](/reference/reference-objects.mdx#transfer_details). | Name | Mandatory | Type | Description | | ---------------------------- | --------- | ------ | ---------------------------------------------------------- | | `account_number` | - | string | Account number | | `name` | - | string | Name | | `bank_name` | - | string | Bank's name | | `bik` | - | string | Bank's BIC | | `correspondent_account_number` | - | string | Correspondent account number | | `inn` | - | string | Bank's INN (for cash and settlement only) | | `kpp` | - | string | Bank's KPP (for cash and settlement only) | ## `recipient` (payout recipient details) Payout recipient details. Which details are necessary depend upon the method of receiving the payout. Parent objects: [`participant_details`](/reference/reference-objects.mdx#participant_details). | Name | Mandatory | Type | Description | |----------------|---------------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------| | `full_name` | - (mandatory for payouts to any cards) | string | Full name | | `first_name` | - | string | First name | | `last_name` | - | string | Last name | | `middle_name` | - | string | Patronymic name | | `company_name` | - | string | Company name | | `reference` | - | string | Recipient identifier in your system | | `tax_reference` | - | string | Taxpayer identifier | | `beneficiary_id` | - (mandatory for the payments and payouts with a beneficiary) | string | INN of the beneficiary | | `country_iso3` | - | string | Country (ISO 3166-1 alpha-3) | | `account` | - | string | Sender's escrow account | | `date_of_birth` | - | string | Recipient's date of birth in the *YYYY-MM-DD* format. Make sure the recipient is 18 years old or older | ## `recurrent` (token for recurring payments or payouts) Token for recurring payments or payouts. Parent objects: [`payment_method`/`payout_details`](/reference/reference-objects.mdx#payment_method), [`payment_details`](/reference/reference-objects.mdx#payment_details). > A new token is generated for each new payment made using the same card. This token is linked to the payment, not to the card. If you need to identify the card, you can use the [Card identifier](/payments/payment-intro#cross-identifier-card). | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | ## `recurrent` (information about a token for recurring payments or payouts) Information about a token for recurring payments or payouts. [More information about recurring payments and token settings](/payments/payment-recurring.mdx). Parent arrays: [`acquiring_payments`/`payment_list`](/reference/reference-objects.mdx#acquiring_payments). | Name | Mandatory | Type | Description | |-------------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format. The setting isn't processed by the Bank | | `is_active` | + | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | | `type` | + | string | Token type. Always: `recurrent_token` | ## `recurrent_token` Token for recurring payments or payouts. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `redirect` User redirect data. | Name | Mandatory | Type | Description | |----------|-----------|--------------------------|-------------------------------------------------------| | `url` | + | string | Redirect address including GET parameters | | `base_url` | + | string | Redirect address | | `method` | + | string | Submission method, E.g. `GET`, `POST` | | `qs` | - | map<string,string> | Set of parameters depending on the transaction method | | `params` | - | map<string,*> | Set of parameters depending on the transaction method | >- Check if any parameters are specified in the `qs` and `params` objects. >- Redirect the user to the redirect address specified in `base_url` using the method from the `method` parameter and including all the required parameters in the URL or request body. ## `refunds` An array with details on a refund. | Name | Mandatory | Type | Description | |------------------|-----------|--------|--------------------------------------------------------------------------------| | `id` | + | string | Unique refund identifier | | `status` | + | string | Refund status. Possible values: `in_progress`, `accepted`, `declined`, `error` | | `amount_details` | + | object | [Amount of the refund](/reference/reference-objects.mdx#amount_details) | | `created_at` | + | string | Creation date | | `finished_at` | - | string | Completion date | | `is_chargeback` | - | bool | Whether the refund is made within a chargeback | | `transaction_info` | - | object | [Transaction details](/reference/reference-objects.mdx#transaction_info) | #### Refund statuses (`status`) - `in_progress` – the payment is being processed. - `accepted` – the refund has been completed successfully. - `declined` – Bank 131 has declined the refund. - `error` – the refund has not gone through because of an error. ## `resend_sms` Data for requesting a new code. | Name | Mandatory | Type | Description | |------------------|----------------|--------|-------------------------------------------------------------------------| | `rest_of_attempts` | + | string | Number of the code request attempts left | | `allowed_from` | + | string | Time starting from which a new code can be requested | | `callback_url` | + | string | Address to which to send a new code request | ## `ru` Russian bank account details (region: ru). | Name | Mandatory | Type | Description | | ----------- | ------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `bik` | - (mandatory for payouts without a token) | string | Recipient’s Bank Identification Code | | `account` | - (mandatory for payouts without a token) | string | Recipient's bank account | | `token` | - (mandatory for payouts with a token) | string | Bank account token | | `full_name` | + | string | Individual's full name. In case of a payout to an account of a sole proprietor should be passed in the following format: `ИП `. 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 | Payout purpose | | `inn` | - (mandatory for the payouts to the accounts of legal entities and sole proprietors) | string | Recipient's INN, 10 digits for legal entities, 12 digits for individuals, including sole proprietors | | `kpp` | - (mandatory for the payouts to the accounts of legal entities) | string | Recipient's Tax Registration Reason Code (KPP)| | `is_fast` | - | bool | Indicates whether [a speedy payout](/payouts/payout-account-sistema-besp) should be made (via BESP). A speedy payout takes place within an hour, a regular one—up to 3 banking days | ## `sber_pay` SberPay payment details. | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------| | `phone` | - | string | Phone number to send PUSH or SMS to. Format: `7**********` | | `channel` | + | ENUM | SberPay payment channel. Options: `app`, `mobile_web`, `web` | ## `self_employed_widget` Settings for the widget used for linking self-employed people to Bank 131. | Name | Mandatory | Type | Description | |---------------|----------------------------------|--------|-------------------------------------| | `tax_reference` | - (if `phone` is passed) | string | Self-employed person's INN | | `phone` | - (if `tax_reference` is passed) | string | Self-employed person's phone number | ## `sender` (escrow payer details) Information about the payer of a payout from an escrow account. Parent objects: [`account_details`](/reference/reference-objects.mdx#account_details). | Name | Mandatory | Type | Description | | ---------------------------- | --------- | ------ | ---------------------------------------------------------- | | `account_number` | - | string | Account number | | `name` | - | string | Name | | `bank_name` | - | string | Bank's name | | `bik` | - | string | Bank's BIC | | `correspondent_account_number` | - | string | Correspondent account number | | `inn` | - | string | Bank's INN (for cash and settlement only) | | `kpp` | - | string | Bank's KPP (for cash and settlement only) | ## `sender` (payout payer details) Payout payer details. Which details are necessary depend upon the method of receiving the payout. Parent objects: [`participant_details`](/reference/reference-objects.mdx#participant_details). | Name | Mandatory | Type | Description | |----------------|---------------------------------------------------------------|--------|-------------------------------------| | `full_name` | - | string | Full name | | `first_name` | - | string | First name | | `last_name` | - | string | Last name | | `middle_name` | - | string | Patronymic name | | `company_name` | - | string | Company name | | `reference` | - | string | Recipient identifier in your system | | `tax_reference` | - | string | Taxpayer identifier or Sender's INN (12 digits) | | `beneficiary_id` | - (mandatory for the payments and payouts with a beneficiary) | string | INN of the beneficiary | | `country_iso3` | - | string | Country (ISO 3166-1 alpha-3) | | `account` | - (mandatory for making payouts from an escrow account) | string | Sender's escrow account | | `citizenship_country_iso3`|+ | string | Sender's country of citizenship according to ISO 3166-1 alpha-3| | `state` | - |string | State or region of the sender's place of registration| | `city` | - |string | Locality of the sender's place of registration| | `postal_code` | - |string | Postal code of the sender's place of registration| | `street` | - |string | Street of the sender's place of registration| | `building` | - |string | Building number of the sender's place of registration| | `flat` | - |string | Apartment of the sender's place of registration|| | `date_of_birth` | - |string | Sender's date of birth in the *YYYY-MM-DD* format. Make sure the sender is 18 years old or older| | `description` | - |string | Additional information| | `ipv4` | - | string | IP address of the sender's device | ## `services` An array with a description of the service which the payout is covering for fiscalization purposes. The array may contain **up to 6 services**. >- The restriction on the number of services per receipt is regulated by the Federal Tax Service (not by the Bank). >- If the number of services is greater than six, you can: > - split them into multiple receipts, > - combine them. Example: if 10 consulting services, 10 000 rubles each, were provided, you can specify 10 services, 10 000 rubles each, as a single item instead of specifying each service separately. | Name | Mandatory | Type | Description | |----------------|-----------|---------|-----------------------------------------------------------------| | `name` | + | string | Service name (up to 256 characters) | | `amount_details` | + | object | [Service price](/reference/reference-objects.mdx#amount_details) | | `quantity` | - | integer | Number of services provided. Default value: 1 | > Note: The product of the service price and the number of services provided must equal the amount of the payout. ## `session` A container with data about all the operations performed within a single payment session. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund). | Name | Mandatory | Type | Description | |--------------------|--------------------------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Session identifier | | `status` | + | string | Status. Possible values: `created`, `in_progress`, `accepted`, `cancelled`, `error` | | `created_at` | + | string | Creation date in ISO 8601 format | | `updated_at` | + | string | Update date in ISO 8601 format | | `payments`/`payout_details` | - | array | [A list of payouts performed within the session](/reference/reference-objects.mdx#payments) | | `acquiring_payments`/`payment_list` | - | array | [A list of payments performed within the session](/reference/reference-objects.mdx#acquiring_payments) | | `next_action` | - | string | Label indicating actions needed to perform the transaction successfully. Possible values: `confirm`, `capture` | | `error` | - (mandatory for `status = cancelled` and `status = error`) | object | [Error description](/reference/reference-objects.mdx#error) | #### Payment session statuses (`status`) - `created` – the session has been created and is waiting to be started or canceled. - `in_progress` – the payment is being processed. - `accepted` – the payment has been completed successfully. - `cancelled` – the payment has been canceled. - `error` – an unexpected error occurred while processing. >Attention! This status is not final. Please contact Bank 131's support team and wait for a final transaction status. #### Next steps (`next_action`) If this field is not empty, it means that Bank 131 is waiting for you to perform specific actions to continue with the operation: - `confirm` – you need to confirm the operation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). - `capture` – you need to perform the debit ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). ## `sms_fee` The sender's fee for SMS notification to the recipient. | Name | Mandatory | Type | Description | |----------|-----------|--------|-------------------------------------------------------------| | `amount` | + | number | Fee amount to be paid for SMS notification to the recipient | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `source` The amount and currency to write off of the sender for money transfers. | Name | Mandatory | Type | Description | |----------|-----------|--------|---------------------------------------------------------| | `amount` | + | number | Amount in decimal format to calculate the exchange rate | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `subscription_service_info` Subscription details when re-linking the same payer and bank. | Name | Mandatory | Type | Description | |----------|----------------|--------|-------------------------------------| | `id` | + | string | Subscription identifier (exactly 32 characters) | | `name` | + | string | Subscription name (1-70 characters) | ## `tax` Data for tax payment. | Name | Required | Type | Description | |-------------|----------|--------|------------------------------------------------------------------------------------------------------| | `type` | + | string | Tax type or payment method. Options: `tax_short`, `tax_full` | | `tax_details` | + | object | [Tax payment details](/reference/reference-objects.mdx#tax_details) | ## `tax_details` Data for tax payments. | Name | Required | Type | Description | |-----------------|----------------------------------------------------------|--------|-------------------------------------------------------------------------------| | ``period`` | - (required when `type = full`) | string | [Tax period](#tax-period) | | ``period`` | - (required when `type = tax_short`) | object | [Tax period](/reference/reference-objects.mdx#period) | | ``kbk`` | - (required when `type = full`) | string | Budget classification code, 20 digits | | ``oktmo`` | - (required when `type = full`) | string | All-Russian Classifier of Territories of Municipal Formations, 8 or 11 digits | | ``payment_reason`` | - (required when `type = full`) | string | [Payment reason](#tax-reason) | | ``document_number`` | - (required when `type = full`) | string | [Document number](#tax-doc) | | ``document_date`` | - (required when `type = full`) | string | [Document date](#tax-date) | ##### `Input format for the 'period' field` - If the `payment_reason` field is set to `ТП` or `ЗД`, then the payment frequency established by legislation should be specified in one of the following formats: - for monthly payments: `МС.MM.YYYY`, where MM is the month (from 01 to 12), and YYYY is the year for which the payment is made (e.g., for income tax withholding for February 2020, use `МС.02.2020`) - For taxes paid quarterly: `КВ.QQ.YYYY`, where QQ is the quarter (from 01 to 04), and YYYY is the year for which the tax is paid. - For semi-annual taxes (e.g., Simplified Tax System): `ПЛ.HH.YYYY`, where HH is the half-year (01 or 02), and YYYY is the year for which the tax is transferred. - For annual payments: `ГД.00.YYYY`, where YYYY is the year for which the tax is paid (e.g., for final profit tax calculation for 2019, use `ГД.00.2019`). - If the `payment_reason` field is set to `ТР`, then the demand date is indicated. - If the `payment_reason` field is set to `АП`, then `0` is used. ##### `Input format for the 'payment_reason' field` - `ТП` – when paying the tax/contribution for the current period. - `ЗД` – when voluntarily repaying tax/contribution arrears. - `ТР` – when repaying the debt based on a demand issued by the tax authority or the Social Insurance Fund (FSS). - `АП` – when repaying the debt based on an audit act (before the demand is issued). ##### `Input format for the 'document_number' field` - If the `payment_reason` field is set to `ТП` or `ЗД`, then use `0`. - If the `payment_reason` field is set to `ТР`, use the number of the tax payment demand. - If the `payment_reason` field is set to `АП`, use the number of the decision issued after the audit. ##### `Input format for the 'document_date' field` - If the `payment_reason` field is set to `ТП`, use the date of signing the declaration or `0` if the date is not specified. - If the `payment_reason` field is set to `ЗД`, use `0`. - If the `payment_reason` field is set to `ТР`, use the date of the payment demand. - If the `payment_reason` field is set to `АП`, use the date of the post-audit decision. ## `tokenize_widget` Settings for the tokenization widget. | Name | Mandatory | Type | Description | | ------ | --------- | ---- | ------------------------------------------------------------------- | | `access` | + | bool | Identifies whether this public key can use the tokenization widget. | ## `tokenized_card` A card token. | Name | Required | Type | Description | |-------|----------|--------|-------------| | `token` | + | string | Token | ## `total_balance` Balance information. | Name | Mandatory | Type | Description | |---------|-----------|------|---------------------------------------------| | `opening` | + | int | Opening balance on the statement start date | | `closing` | + | int | Closing balance on the statement end date | ## `total_turnover` Information on funds movement. | Name | Mandatory | Type | Description | |--------|-----------|------|--------------------------------------------------------| | `debet` | + | int | Total debits over the period covered by the statement | | `credit` | + | int | Total credits over the period covered by the statement | ## `transaction_info` Transaction information. | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | --------------------------------------------------------------------------------- | | `rrn` | - | string | Retrieval Reference Number (a unique identifier generated for a bank transaction) | | `arn` | - | string | Acquirer Reference Number (a unique number assigned to credit card transactions) | | `auth_code` | - | string | Authorization code | | `fp_message_id` | - | string | Unique transaction identifier in FPS | ## `transactions` An array with information on transactions. | Name | Mandatory | Type | Description | |----------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amount` | + | int | Top-up amount (non-negative values only) | | `base_amount` | - | int | Transaction amount in the currency. Should be filled out only for transactions in currencies other than Russian rubles. When using the base currency (RUB), the parameter is optional | | `currency` | + | string | Transaction currency | | `payment_date` | + | date | Transaction date | | `bank_system_id` | + | string | Payment identifier. It is specified for all kinds of payments:- for payments sent via the API - for transfers from another bank- for payments made through online banking | | `transaction_id` | - | string | Transaction identifier. It is specified for payments sent via the API | | `session_id` | - | string | Session identifier. It is specified for payments sent via the API | | `purpose` | + | string | Payment purpose | | `counter_party` | + | object | [Payer information](/reference/reference-objects.mdx#counterparty) | | `type` | + | string | Transaction type. Possible values: `credit` (for replenishment operations), `debet` (for write-off operations) values | ## `transfer_details` Information about a transfer. | Name | Mandatory | Type | Description | |-------------------------------|-----------|--------|--------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Method of receiving the payout](/reference/reference-objects.mdx#payment_method) | | `customer` | + | object | [Information about a payer](/reference/reference-objects.mdx#nominal_payment_customer) | | `recipient` | + | object | [Information about a recipient](/reference/reference-objects.mdx#nominal_payment_recipient) | | `purpose` | + | string | Payout purpose in the following format: `; card:` | | `amount` | + | object | [Amount](/reference/reference-objects.mdx#amount) | ## `transfer_fee` The sender's fee for money transfer. | Name | Mandatory | Type | Description | |----------|-----------|--------|------------------------------------------------------------| | `amount` | + | number | Fee amount to be paid by the sender for the money transfer | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `transfer_from_bank_account` Information on a transfer from a settlement account. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------- | | `description` | + | string | Description | ## `transfer_from_nominal_account` Information on a transfer from an escrow account. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------- | | `description` | + | string | Description | ## `wallet` Electronic wallet details. | Name | Mandatory | Type | Description | |----------|-----------|--------|-------------------------------------------------------------------------------------| | `type` | + | string | Wallet type. Possible values: `yoomoney` | | `yoomoney` | + | object | [YooMoney wallet details](/reference/reference-objects.mdx#yoomoney) | ## `wallets` Your guarantee payment balance details (this balance is used to perform payouts). | Name | Mandatory | Type | Description | |----------------|-----------|--------|-------------------------------------------------------------------| | `id` | + | string | Balance identifier | | `amount_details` | + | object | [Current balance](/reference/reference-objects.mdx#amount_details) | ## `yoomoney` YooMoney wallet details. :::info For payments, the object must be empty. ::: | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------------------------------------------------------------- | | `account` | + | string | YooMoney wallet number for payouts, 11 to 20 digits. Example: `4100175017397` | | `description` | - | string | Payout description (up to 128 characters) | --- - [API libraries](https://developer.131.ru/en/reference/sdk): Libraries for integration with the Bank 131 API Libraries that you may use to integrate with the Bank 131 API. - [PHP SDK](https://github.com/bank131/php-sdk) --- - [Webhooks](https://developer.131.ru/en/reference/webhooks): Notifications of events on the side of Bank 131 Webhooks are notifications about events happening on Bank 131's side. The Bank sends webhooks to inform you of the results of your operations, ask for confirmation, or alert you about actions you need to take. Also, webhooks can include information on the applicable transaction fee. To enable this functionality, please contact your Bank 131 manager. :::info If you decide to work without webhooks, you will need to use a [session/status](/reference/methods#sessionstatus) request each time to understand your next step and the operation result. ::: #### How to get webhooks 1. In your system, create an address to receive webhooks at. 2. Inform your Bank 131 manager of this address. IP addresses our webhooks arrive from: `84.201.171.246` and `84.252.136.174`. #### What to send in response Bank 131 waits for you to send the 200 HTTP code in response to any webhook. If the Bank receives a 4\*\* or 5\*\* code, it will retry the request with increasing intervals. Here is how it works: * The interval between retries increases progressively, but never exceeds 15 minutes. * After 30 minutes, the Bank will stop sending the webhook. :::warning[IMPORTANT!] Additional fields may be added to the webhook payload over time, depending on the payment methods used. Make sure that your service can handle them without failure. ::: ## `action_required` #### The Bank is waiting for you or your users to take the necessary action The Bank sends this webhook to you when you or your users need to carry out certain actions to proceed with the operation. For example, a user might need to go through 3D Secure authentication when paying via bank card. >The maximum waiting time for an action is 60 minutes. If the action does not occur within this time, the operation will automatically be completed with the `canceled` status. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `action_required` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ## `confirmation_payout` #### Bank 131 informs you when money is successfully deposited into the account at the recipient bank The Bank sends you this webhook, specifying the date and time of the funds' deposit, in the following cases: - **funds delivered to the recipient's account** — for payouts through BESP - **transfer accepted by the Central Bank** (i.e., the funds have been debited from Bank 131’s account and sent to the recipient’s bank account) — for regular payouts > The webhook is disabled by default. To start receiving `confirmation_payout` webhooks, contact you Bank 131 manager. The webhook can arrive within up to 7 business days from the transaction date. The webhook may not be received if the recipient bank fails to provide confirmation. Note that this does not affect the actual deposit of funds into the recipient’s account. The payout can be refunded after you receive the webhook. #### Webhook parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Webhook type: `confirmation payout` | | `event` | + | string | Payout receipt type. Possible options:- `Payout accepted Central Bank`- `Funds credited recipient's account` | | `event_date` | + | date | Payout receipt date and time according to ISO 8601 | | `transaction_id` | + | string | Unique transaction identifier | | `session_id` | + | string | Unique session identifier | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type":"confirmation_payout", "event":"Funds credited recipient's account", "event_date":"2024-11-27T02:03:00.000000Z", "transaction_id":"po_2018", "session_id":"ps_3230" }' ``` ## `nominal_topup` #### Bank 131 informs you when your escrow account is replenished Bank 131 sends this webhook every time funds are added to your **escrow account** as a result of any internal or bank-to-bank transaction. The webhook body includes information on the amount of added funds and the new balance of your account. > Note that you can give the Bank manager any address to which you would like to receive these notifications. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------------------------|-----------|--------|---------------------------------------------------------------------------------------------| | `inn` | + | string | Recipient`s INN | | `kpp` | - | string | Recipient`s KPP | | `account_number` | + | string | Replenished account number | | `account_balance` | + | int | Current account balance (Amount in minor currency units. For 100 rubles, `10000` is passed) | | `doc_id` | + | string | Document identifier | | `doc_num` | + | string | Document number | | `amount` | + | int | Payment amount (Amount in minor currency units. For 100 rubles, `10000` is passed) | | `currency` | + | string | Payment currency code according to ISO 4217 | | `paymentDate` | + | date | Payment date and time according to ISO 8601 | | `purpose` | - | string | Payment purpose | | `contragent_name` | - | string | Sender's name | | `contragent_inn` | - | string | Sender's INN | | `contragent_kpp` | - | string | Sender's KPP | | `contragent_account_number` | + | string | Sender's account number | | `contragent_bank_bik` | + | string | Sender's bank BIK | | `contragent_bank_name` | - | string | Sender's bank name | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "inn": "3316004790", "kpp": "156605101", "account_number": "40702810600200000014", "account_balance": 518619720, "doc_id": "2080040124641368", "doc_num": "333", "amount": 66660, "currency": "810", "paymentDate": "2023-07-27T20:04:36.807000+03:00", "purpose": "Escrow account replenishment for 5896.60 rubles", "contragent_name": "Vector LLC", "contragent_inn": "1655415696", "contragent_kpp": "165501001", "contragent_account_number": "30110810800000000593", "contragent_bank_bik": "049205131", "contragent_bank_name": "Bank 131" }' ``` ## `payment_finished` #### The Bank informs you of the result of an operation The Bank sends this webhook to you when it has completed an operation (a payment or a payout). The webhook body contains all the details of the operation, including its status (in the `status` field). For example, if you are sending a payout and have received the `succeeded` status in this webhook, it means that the payout has been completed successfully. Also, the webhook body contains 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. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `payment_finished` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ## `payment_refunded` #### Bank 131 informs you of the result of a refund Bank 131 will send you this webhook after a refund is performed. The notification parameters contain information about the payment session, including all the information about the refunds. The webhook is sent in the following cases: - you made a refund using the [`session/refund`](/reference/reference-methods.mdx#sessionrefund) method - the recipient's bank [returned your payment sent to a Russian bank account](/payouts/payout-refunds.mdx) - within the **chargeback** procedure > If the return is made within the **chargeback** procedure, the `refunds` object contains the following additional line: `"is_chargeback": true`. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `payment_refunded` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example ```json showLineNumbers curl - X POST\ https: //partner.ru \ -H 'Content-Type: application/json'\ - -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl - X POST\ https: //partner.ru \ -H 'Content-Type: application/json'\ - -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl - X POST\ https: //partner.ru \ -H 'Content-Type: application/json'\ - -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl - X POST\ https: //partner.ru \ -H 'Content-Type: application/json'\ - -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ## `ready_to_capture` #### The Bank informs you that the money has been put on hold >If you work with [delayed capture payments](/payments/payment-hold), Bank 131 will **always** send you this webhook before debiting funds. This webhook means that the amount has been put on hold successfully, and the Bank is waiting for your next command. To debit the money, send a ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) request. To cancel the payment, send a ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) request. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `ready_to_capture` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "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": "capture", // highlight-next-line "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "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": "capture", // highlight-next-line "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": "good" }] } }' ``` ## `ready_to_confirm` #### The Bank is waiting for your confirmation to perform the operation Bank 131 sends this webhook when it is ready to perform an operation (a payment or a payout). You need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) to Bank 131. If something is not right, cancel the operation by sending a ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) to Bank 131. >The maximum waiting time for a confirmation is 240 minutes. If no confirmation is received within this time, the operation will automatically be completed with the `canceled` status. For your convenience, you can use automatic payment session confirmation, when you are not required to obtain a `ready_to_confirm` webhook and then confirm it. To set up the automatic payment session confirmation, apply to your manager in Bank 131. #### Webhook parameters | Name | Mandatory | Type | Description | |---------------------|---------------------------------------------------------------------------|--------|---------------------------------------------------------------------------------------------| | `type` | + | string | Webhook type: `ready_to_confirm` | | `session` | + | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `confirm_information` | - (mandatory for transactions with an escrow account and money transfers) | object | [Transaction confirmation information](/reference/reference-objects.mdx#confirm_information) | Examples ```json showLineNumbers 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", // highlight-next-line "payments": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```json showLineNumbers 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", // highlight-next-line "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```json showLineNumbers 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", // highlight-next-line "payout_list": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```json showLineNumbers 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", // highlight-next-line "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` --- ## Dashboard - [Dashboard](https://developer.131.ru/en/dashboard/dashboard-intro): Merchant's dashboard functionality and advantages Bank 131 provides a service for transaction tracking and analytics—the **Dashboard**. This centralized platform allows you to fully control your business financial flows, see details of each transaction, and resolve issues more quickly. Now, you do not need to request statements from your manager: all data is always at hand. The Dashboard is all about transparency. You see a complete map of fund movements: which transactions succeeded, which failed, and why. This is not just a 'transaction history' but a powerful tool for sales analytics. ## Key benefits for your business **Independent transaction control** You do not need to contact support to obtain information about transactions. Important transaction information is available directly in the Dashboard at any time. **Clear statuses and error details** You will see the current status of each transaction. If a transaction is unsuccessful, the service shows the specific reason. This allows you to respond quickly and minimize the number of unsuccessful transactions. **Transaction analytics for business development (coming soon)** Collect statistics on successful and unsuccessful transactions, analyze trends, identify peak loads and problem scenarios. The Dashboard helps you see not only what happened but also how to optimize everything. **Data security** All transaction data is protected by our corporate security standards and transmitted via secure communication channels. You can be confident in the safety of your business and customer financial information. ## Core features The following options are already available in the Dashboard. You can: * view the [transaction registry](#registry) and the [details of any transaction](#detalization) * search for transactions using the [date filter](#searching) * search for transactions using [AI](#AI) * download transaction reports in CSV format ### Transaction registry The transaction registry allows you to track the complete history of fund movements, including payments, payouts, and refunds. This tool enables you to monitor financial flows without having to contact your manager. The registry displays transaction statuses and key details, allowing you to quickly analyze both successful and unsuccessful transactions. ### Transaction details Click any row in the registry to open a panel with the details of a specific transaction. The details include the following data: * **Session ID** * **Transaction ID** * **Transaction type**: payment, payout, refund * **Method**: SBP, bank card—*other methods will be supported soon* * **Amount**: transaction amount * **Status**: transaction status (`succeeded`, `failed`, `pending`, `in_progress`) * **Date and time** of the transaction creation * **Partner**: your company name * **Fee**: amount withheld by the Bank for transaction processing * **Antifraud**: service comment (`Passed`, `Failed`) ### Date filter At the top of the transaction registry panel, you will find a period filter. You can select: * All time: from the start of using the service (this option is selected by default) * Preset periods: 7 days, 30 days, 90 days * Custom period: any arbitrary start and end dates ### AI-powered search In addition to filters, you can use our AI search. Simply enter a query in the search bar—the neural network will instantly analyze the data array and return the most relevant result. AI search understands natural language queries. For example, you can enter "Show all payments via Mir card for November 25" or "Transactions over 5 thousand rubles"—the service will show an exact result, saving your time. ## How to get access To get access to the Dashboard, contact your personal manager at Bank 131. **How to log in:** 1. Wait for an email from Bank 131 to your corporate email address provided during registration. The email will contain your first login credentials: **login (your email) and temporary password (a generated character combination)**. 2. Follow the link in the email. 3. Upon first login, change the temporary password to a permanent one and complete two-factor authentication. ## Development roadmap An analytics dashboard will soon appear in the Dashboard. We plan to add approved transaction charts, conversion reports broken down by payment method, and widgets for monitoring refunds. Additionally, it will become possible to assign roles to service users. Each role contains a specific set of capabilities for convenient collaboration. Stay tuned for updates. --- ## Widget - [FPS widget](https://developer.131.ru/en/widget/widget-fps): Widget for payments via FPS To acquire payments using FPS, you can use the Bank 131 widget. You add the widget to the page, display it to the user, and the user then interacts with the widget, going through all the payment steps from beginning to end, and then sees a message telling them that the payment has been successful (or an error message if anything goes wrong). You need to create a payment session, and the widget does the rest: it will send the payment request, redirect the user to the appropriate address, and display them the screen with the result of the operation. [How to acquire FPS payments](/payments/payment-fps-qr) ## How the widget looks like ![](/assets/fps_widget_ru.png) ## Code example of a page with FPS widget added ```html showLineNumbers FPS acquiring document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131SBPPayment) { return; } const widget = new Bank131SBPPayment('public_token'); widget.onReady = function () { console.log('SBPPayment is ready.'); }; widget.onSBPStart = function () { console.log('SBPPayment was started.'); }; widget.onSBPFail = function (error) { console.log('SBPPayment was failed with an error', error); }; widget.onSBPSuccess = function () { console.log('SBPPayment was succeed.'); }; widget.render(); }); ``` ## How to embed the FPS widget #### 1. Set up scripts and CSS styles ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2. Add widget container ```html showLineNumbers ``` #### 3. Create a widget instance After you set up the script, the `Bank131SBPPayment` constructor class becomes available. ```js const widget = new Bank131SBPPayment('public token'); ``` To display the FPS payment form, use the `render()` method: ```js widget.render(); ``` ## Widget API ### `Bank131SBPPayment` FPS payment form instance constructor ```js const widget = new Bank131SBPPayment(publicToken[, options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | publicToken | string | Mandatory public token. | | options | object | Additional settings. | | options.container | HTMLElement | Container with form. Default value: `` | ### `widget.render()` method The method displays the payment form in the page. The container is specified within the `options.container` setting. ```js widget.render([options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | options | object | Additional settings. | | options.container | HTMLElement | Container with form. Default value: `` | ### `widget.onReady` event handler The widget is up and ready event handler. ```js widget.onReady = function () { /* handler */ } ``` ### `widget.onSBPStart` event handler Payment start event handler. ```js widget.onSBPStart = function () { /* handler */ } ``` ### `widget.onSBPSuccess` event handler Payment succeeded event handler. ```js widget.onSBPSuccess = function () { /* handler */ }; ``` ### `widget.onSBPFail` event handler Payment failed event handler. ```js widget.onSBPFail = function (error) { /* handler */ } ``` ## How to customize the SBP widget ### Widget appearance You can set up your own styles: ```css /* custom-styles.css */ .bank131-Field__label { color: green; } ``` --- ## Finance - [Daily payment report](https://developer.131.ru/en/finance/payment-daily-report): All successful operations for a day in CSV format The daily report is sent in CSV format to the email address specified in your agreement with Bank 131. If you wish to receive the reports in the XLSX or in a different way, for example, via SFTP, please contact your Bank 131 manager. ## How to use the report The report sent by Bank 131 contains a list of all successful operations for a day (24 hours). You need to check the operations on your side against those in the report. In case of any discrepancy, contact your Bank 131 manager. The timeframe for making corrections is specified in your agreement with the Bank. ## Report file name `_YYYY-MM-DD-YYYY-MM-DD` ## Report fields | Field name | Description |Example | |--------------------------------|-------------------------------------------------------------------------------|-----------------------| | ID | Bank 131 payment identifier | `pm_1237020` | | paymentSessionId | Payment session identifier | `ps_3232` | | Project name | The name of your project on Bank 131's side | `acquiring_card` | | Type of payment | Payment type. Possible options: `Adjustment`, `Advice`, `Refund`, `Recurrent`. [More details](/finance/payment-daily-report#payment-types) | `Advice` | | Amount | Total of the operation in rubles | `110` | | Fee | Bank 131's total fee (as per the agreement). Specified as a negative value | `-2` | | Settlement | Total of the settlement the Bank must transfer to you. The total of the settlement can be negative, for example for `Refund` or `Chargeback` | `-2` | | Transaction Date and Time | Date and time of the transaction on Bank 131's side | `2026-05-01 13:17:56` | | Card number | Masked number of the card/wallet number used to make the payment | `4...1878` | | paymentSessionMerchantMetadata | Your additional data that you passed within the request for the operation | `1Di732vw57` |   ### Payment types - `Adjustment` – partial cancellation of a transaction - `Advice` – successful transaction - `Refund` – rollback of a successful transaction - `Recurrent` – [recurring payment](/payments/payment-recurring) (automatic payment or repeated payment) ## How to receive large report files In case of large amount of data, Bank 131 is able to send report files with one of the methods below: - A CSV or XLSX file split into parts in CSV or XLSX format. - A single ZIP archive file (CSV or XLSX file archived). - A ZIP archive file split into parts (CSV or XLSX file archived and then split into parts). This can help to deal with the issues when your email server cannot process a single email file with a size larger than specified. To know more about this service, please contact your manager at Bank 131. In some cases, Bank 131 can split and/or archive reports based on their own business and/or operational needs. You can specify the number of transactions you want to receive in each part of a report to split the report file in accordance with that number. **An XLSX report example** **Example of split report** ``` acquiring_monthly_2023-02-01-2023-03-01_part_1_of_3.csv acquiring_monthly_2023-02-01-2023-03-01_part_2_of_3.csv acquiring_monthly_2023-02-01-2023-03-01_part_3_of_3.csv ``` --- - [Payout reports](https://developer.131.ru/en/finance/payouts-daily-report): All successful operations for a day in CSV format Bank 131 generates a daily report of successful payouts and sends it as a CSV file to the email address specified in your agreement. If no transactions took place, the Bank will send an empty register. :::warning Important! In case of any discrepancy, contact your Bank 131 manager. The timeframe for making corrections is specified in your agreement with the Bank. ::: If the report contains a large number of transactions, Bank 131 may split it into several CSV files or send it as a ZIP file. ### Changing report format and delivery settings You can choose the format in which you receive the report, for example, XLSX instead of CSV. If your mail server blocks large files, choose one of the options: - multiple CSV or XLSX files (split into parts) - one ZIP file (with CSV or XLSX) - multiple ZIP files (if the report is split) You can also change the delivery method, for example, choose SFTP. To set this up, contact your Bank 131 manager. ## Report file name `_YYYY-MM-DD_YYYY-MM-DD` ## Report fields The set of fields depends on the operation type. | Field name | Format | Description | Example | |--------------------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------| | operationId | string | Bank 131 payout identifier | `po_2121` | | transactionDate | string (date in the following format: `YYYY-MM-DD H:I:S`) | Date and time of payout creation on Bank 131's side | `2019-06-21 23:17:55` | | finishedAt | string (date in the following format: `YYYY-MM-DD H:I:S`) | Date and time of payout completion on Bank 131's side | `2019-06-21 23:17:56` | | typeOfPayment | string | Operation type. Options: `Advice` is a successful payout; `Refund` is a [payout refund](/payouts/payout-refunds) | `Advice` | | paymentFast | int | Payout type. `0` is a regular payout, `1` [is a fast payout via the BESP system](/payouts/payout-account-sistema-besp) (only for payouts to Russian bank accounts) | `1` | | paymentSessionId | string | Payment session identifier | `ps_2323` | | contract | string | Number of your contract with Bank 131 | `100-C-000000` | | paymentSessionMerchantMetadata | string | Data that you passed within the payout request | `{"test_data":"test"}` | | paymentMethodIdentity | string | Payment instrument (masked card or account number) | `420080******8800` | | product | string | Product or service identifier according to the agreement with Bank 131 | `new_test_payouts` | | grossLocalAmount | decimal | Total amount of the payout | `110` | | paymentLocalAmount | decimal | Payout amount after the fee is deducted | `100` | | feesLocalAmount | decimal | Bank 131's fee (`grossLocalAmount - paymentLocalAmount`) | `10` | | currency | string | Three-letter currency code (ISO) | `RUB` | | receipt | string | Online receipt link | `https://lknpd.nalog.ru/api/v1/receipt/220704837033/205ldfqqhc/print` | | rrn | string | Retrieval Reference Number: the unique identifier of a bank operation | `12345678` | **An XLSX report example** **An example of a split report** ``` payout_monthly_2023-02-01-2023-03-01_part_1_of_3.csv payout_monthly_2023-02-01-2023-03-01_part_2_of_3.csv payout_monthly_2023-02-01-2023-03-01_part_3_of_3.csv ``` --- ## Statements - [Account balance](https://developer.131.ru/en/statements/statements-balance): Sending a request to get balance for settlement or escrow account To get your settlement or escrow account balance, use the [`account_balance`](/reference/methods#reportaccount_balance) method. Accounts you can check the balance for You can only get the balance of an account that starts with the following numbers: - 40702 - 40703 - 40802 - 40807 - 40701 ### Request parameters | Name | Mandatory | Type | Description | | ------------------ | --------- | ------ | -------------- | | `account_number` | + | string | Account number | Account balance request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/report/account_balance \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-start "account_number": "40702810400000000333" // highlight-end }' ``` ### Response parameters | Name | Mandatory | Type | Description | |--------------------|-----------|--------|------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `account_number` | - | string | Account number | | `account_currency` | - | string | Account currency according to ISO 4217. Example: `RUB` | | `balance` | - | object | [Balance details](/reference/reference-objects.mdx#balance) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Successful response example ```json showLineNumbers { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { // highlight-next-line "current_balance": 20900 } } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "code": "Error code", "description": "Error description" } } ``` --- - [Account statements](https://developer.131.ru/en/statements/statements-escrow): Sending a request to get bank statements for settlement or escrow account You can get bank statements for your settlement or escrow account for any given day in rubles—for example, to confirm a payout. To get a statement, use the [`report/account_statement`](/reference/reference-methods.mdx#reportaccount_statement) method. ### Request parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|-------------------------------------------------------------------------------| | `account_number` | + | string | Account number (20 digits) for which you request a statement | | `date_from` | + | date | Statement start date. Example: 2023-06-01 | | `date_to` | + | date | Statement end date. It should be the same as `date_from`. Example: 2023-06-01 | Account statement request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/report/account_statement \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-start "date_from": "2023-06-01", "date_to": "2023-06-01", "account_number": "40702810600200000014" // highlight-end }' ``` ### Response parameters | Name | Mandatory | Type | Description | |------------------------------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `method` | + | object | [Method data](/reference/reference-objects.mdx#method) | |   `name` | + | string | Method name `account_statement` | |   `account_statement` | + | object | [Statement details](/reference/reference-objects.mdx#account_statement) | |     `date_from` | + | date | Statement start date | |     `date_to` | + | date | Statement end date | |     `account_number` | + | string | Account number (20 digits) for which the statement is generated | |     `total_turnover` | + | object | [Information on funds movement](/reference/reference-objects.mdx#total_turnover) | |       `debet` | + | int | Total debits over the period covered by the statement | |       `credit` | + | int | Total credits over the period covered by the statement | |     `total_balance` | + | object | [Balance information](/reference/reference-objects.mdx#total_balance) | |       `opening` | + | int | Opening balance on the statement start date | |       `closing` | + | int | Closing balance on the statement end date | |     `transactions` | + | array | [Information on transactions](/reference/reference-objects.mdx#transactions) | |       `amount` | + | int | Top-up amount (non-negative values only) | |       `base_amount` | - | int | Transaction amount in foreign currency. When using the base currency (RUB), the parameter is optional | |       `currency` | + | string | Transaction currency | |       `payment_date` | + | date | Transaction date | |       `bank_system_id` | + | string | Payment identifier. It is specified for all kinds of payments:- for payments sent via the API - for transfers from another bank- for payments made through online banking | |       `transaction_id` | - | string | Transaction identifier. It is specified for payments sent via the API | |       `session_id` | - | string | Session identifier. It is specified for payments sent via the API | |       `purpose` | + | string | Payment purpose | |       `counter_party` | + | object | [Counterparty details](/reference/reference-objects.mdx#counterparty) | |         `kpp` | - | string | Counterparty's KPP | |         `inn` | - | string | Counterparty's INN | |         `name` | + | string | Counterparty's name | |         `account_number` | + | string | Counterparty's account number | |         `bank_code` | + | string | Counterparty's bank BIK | |       `type` | + | string | Transaction type. Possible values: `credit` (for replenishment operations), `debet` (for write-off operations) values | Successful response example ```json showLineNumbers { "status": "ok", "method": { "name": "account_statement", "account_statement": { "date_from": "2022-11-12T18:19:32.487+0000", "date_to": "2022-11-13T18:19:32.487+0000", "account_number": "40703810500000000025", "total_turnover": { "debet": 0, "debet_base": null, "credit": 100, "credit_base": null }, "total_balance": { "opening": 0, "opening_base": null, "closing": 100, "closing_base": null }, "transactions": [{ "amount": 10000, "base_amount": null, "currency": "RUB", "payment_date": "2022-11-13", "bank_system_id": "2080040097819020", "transaction_id": "c7b923ec-844f-4d98-ad02-795d62fe1989", "session_id": "ps_3230", "purpose": "Account replenishment", "counter_party": { "kpp": "165501001", "inn": "1655415696", "name": "Fee for money transfer processing services", "account_number": "70606810600004710401", "bank_code": "049205131" }, "type": "credit" }] } } } ``` Unsuccessful response examples ##### `date_from` does not match `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (max interval is 1 day)", "code": "invalid_request" } } ``` ##### `date_from` is greater than `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (date_to must be greater than date_from); (max interval is 1 day)", "code": "invalid_request" } } ``` ##### Invalid date in `date_from` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_from", "code": "invalid_request" } } ``` ##### Invalid date in `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_to", "code": "invalid_request" } } ``` ##### Invalid JSON format ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ##### Internal error This response is returned in the following cases: - the account number is specified incorrectly - the account does not exist - the account does not belong to the user ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` ---