# 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. [Example prompts and skills for AI agents](/skills-and-prompts) ::: --- - [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). Payouts to foreign bank cards 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 {#payment_methods} 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 | + | + | - | + | | 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 | + | + | - | + | | 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. There are currently no ready-made integrations or plugins for CMS platforms such as WordPress, 1C-Bitrix, OpenCart, or others. --- - [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. If your business needs multiple projects, you can create as many as you need—there are no limits. ## 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](/account-selection): - 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. ::: --- - [Which account type to choose](https://developer.131.ru/en/account-selection): Choose an account type by goal—payment acceptance and payouts Bank 131 offers three account types: [settlement](/settlement-account/settlement-intro), [escrow](/escrow-account/escrow-intro), and [collateral](/payouts/collateral-intro). Which account to open depends on your goal: a primary account for your own operations, an account for settlements with clients, or one-time payouts without a settlement account. {title} {note && {note}} {children} ); ↓ ); {children} ); ### Account selection guide **What is your goal?** **Need a primary account for your own operations** Settlements with counterparties, payroll, taxes, and payment acceptance from clients First open the account, then connect payment acceptance or payouts Payment acceptance [cards](/en/payments/payment-pcidss) [FPS](/en/payments/payment-fps-qr) [SberPay](/en/payments/payment-sber-pay) [T-Pay](/en/payments/payment-tpay) [YooMoney](/en/payments/p-yoomoney) Payouts [to card](/en/settlement-account/settlement-payout-cards) [to account in RU bank](/en/settlement-account/settlement-payout-accounts) [via FPS](/en/payouts/payout-fps-phone) [via BESP](/en/payouts/payout-account-sistema-besp) **Need an account for settlements with clients** Intermediation, escrow transaction—funds belong to beneficiary clients **Settlement account** Opened first Open after the settlement account—then set up payouts Payouts [to card](/en/escrow-account/escrow-payout-cards) [to account in RU bank](/en/escrow-account/escrow-payout-accounts) [via FPS](/en/payouts/payout-fps-phone) [via BESP](/en/payouts/payout-account-sistema-besp) **Need one-time or recurring payouts** Payouts to counterparties, contractors, partners Top up the account in advance Payouts [to card](/en/payouts/payout-pcidss) [to account in RU bank](/en/payouts/russian-account) [to YooMoney](/en/payouts/yoomoney) [to cards in currency](/en/payouts/payout-currency) [VAT](/en/payouts/payout-taxes) [via BESP](/en/payouts/payout-account-sistema-besp) ### Account comparison | Feature | Settlement | Escrow | Collateral | |---|---|---|---| | Payment acceptance (cards, FPS, SberPay, T-Pay, YooMoney) | ✔ | — | — | | Payouts to cards and accounts of Russian banks | ✔ | ✔ | ✔ | | Payouts via FPS | ✔ | ✔ | — | | Payouts via BESP | ✔ | ✔ | ✔ | | Payouts to YooMoney, in currency, VAT | — | — | ✔ | --- - [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 {#version_API} 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/start/payout`](/reference/methods#sessionstartpayout) - [`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 {#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 {#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 and webhooks from Bank 131 are signed using its secret key. To ensure a request or webhook 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 [/assets/production_131_public.pem](/assets/production_131_public.pem) - For demo testing [/assets/demo_131_public.pem](/assets/demo_131_public.pem) Signature generation and validation examples **OpenSSL** ```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** ```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 {#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/start/payout`](/reference/methods#sessionstartpayout) - [`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. Under normal circumstances, the Bank 131 public key does not change. If a key change occurs, the Bank will notify partners in advance and provide the new key. Requests can only be signed using the RSA/SHA-256 algorithm. ECDSA and other algorithms are not supported. When API versions change, backward compatibility is maintained—updates will not break your current integration. --- - [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 [/assets/demo_131_public.pem](/assets/demo_131_public.pem) 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 refunds and chargebacks To verify that refunds are processed correctly, perform a [refund](/payments/payment-refund). If you receive the `payment_refunded` webhook after the refund, the integration is working correctly. Chargebacks are handled similarly—if refunds are tested successfully, their processing will also work correctly. ### Testing an FPS payment To test an FPS payment in the test environment, wait for the `action_required` webhook, then call the following methods: - `https://demo.bank131.ru/provider/v1/public/StubProvider/qrConfirm?session_id={session_id}` to test successful transactions (the session status will be `accepted`) - `https://demo.bank131.ru/provider/v1/public/StubProvider/qrCancel?session_id={session_id}` to test unsuccessful transactions (the session status will be `cancelled`) ### 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 | Test transaction data cannot be cleared. The API has no rate limits on the number of requests per second or minute. --- - [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. **Payouts** The steps depend on whether or not you use our widget. **With 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. ### Payout scheme with our widget ![Payout scheme with our widget](/img/docs/payouts/schema_payouts_with_widget_en.png) ```plantuml @startuml PayoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget Partner -> Bank_131: ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters card details ... Partner -> Bank_131: ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **Without our widget** 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. ### Payout scheme without our widget ![Payout scheme without our widget](/img/docs/payouts/schema_payouts_without_widget_en.png) ```plantuml @startuml PayoutNoWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **Payments** The steps depend on whether or not you use our widget. **With 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. ### Payments scheme with our widget ![Payments scheme with our widget](/img/docs/payments/schema_payments_with_widget_en.png) ```plantuml @startuml PaymentWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget participant ACS as ACS Partner -> Bank_131: ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... Customer interaction with the payment form ... Bank_131_Widget -> Bank_131: initializes payment Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure Bank_131 -> Bank_131_Widget: data for passing 3D Secure Bank_131_Widget -> ACS: redirects the user to pass 3D Secure ACS -> Bank_131: passes 3D Secure result end alt Bank_131 -> Bank_131: holds funds Bank_131 -> Partner: ""ready_to_capture"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/capture"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: debits funds Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK Bank_131 -> Bank_131_Widget: passes payment information Bank_131_Widget -> Bank_131_Widget: displays payment status @enduml ``` **Without our widget** 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. ### Payments scheme without our widget ![Payments scheme without our widget](/img/docs/payments/schema_payments_without_widget_en.png) ```plantuml @startuml PaymentNoWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant ACS as ACS Partner -> Bank_131: ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payment"" Bank_131 -> Bank_131: starts the payment Bank_131 --> Partner: 200 OK Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure Bank_131 -> Partner: ""action_required"" Partner --> Bank_131: 200 OK Partner -> ACS: redirects the user to pass 3D Secure ACS -> Bank_131: passes 3D Secure result end alt Bank_131 -> Bank_131: holds funds Bank_131 -> Partner: ""ready_to_capture"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/capture"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` --- - [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 {#get_certificate} 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 {#import_certificate} **For Windows** 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 Linux** 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. **For Java** 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 {#check_certificate} 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 {#list_of_accounts} Accounts allowed for payouts from collateral accounts You can only send payouts to the accounts that begin with these digits: - 40817810 - 42301810 - 42302810 - 42303810 - 42304810 - 42305810 - 42306810 - 42307810 - 40802810 - 40820810 - 40702810 (for legal entities) --- - [Monthly reports](https://developer.131.ru/en/payouts/finance-act): Via email, EDM, or on paper Bank 131 generates a monthly report on the rendered services and sends it to the email address specified in your agreement. You must sign the report and return it within 5 business days of receiving it. You can sign it using a qualified electronic signature (QES) and reply to the same email. If you prefer to receive reports via EDM or in paper form, please contact your account manager. ### PDF report template Monthly payout report [/assets/monthly_payout_report_bank_131_en.pdf](/assets/monthly_payout_report_bank_131_en.pdf) Monthly payment report [/assets/monthly_payment_report_bank_131_en.pdf](/assets/monthly_payment_report_bank_131_en.pdf) --- - [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 You can only send payouts to the accounts that begin with these digits: - 40817810 - 42301810 - 42302810 - 42303810 - 42304810 - 42305810 - 42306810 - 42307810 - 40802810 - 40701810 - 40502810 - 40702810 (for legal entities) Accounts allowed for payouts from collateral accounts You can only send payouts to the accounts that begin with these digits: - 40817810 - 42301810 - 42302810 - 42303810 - 42304810 - 42305810 - 42306810 - 42307810 - 40802810 - 40820810 - 40702810 (for legal entities) ### Making a speedy payout {#besp} :::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", "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" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "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" } }, "amount_details": { "amount": 800000, "currency": "rub" }, "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 {#target} 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: `?`, `!` - minimum length: 15 characters - maximum length: 140 characters #### Payout purpose example **For residents** `Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` **For non-residents** `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ## How to perform a payout from the settlement account {#payout-rko} 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", "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" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "metadata": "good" }' ``` ## How to perform a payout from the escrow account {#payout-nominal} :::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", "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" } } }, "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, and sole proprietors 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. ### Payout crediting timeframes | Method | Weekdays | Weekends/Public holidays | |---------------------------------------------|--------------------------------------------|--------------------------| | To card | Instant, 24/7 | Instant, 24/7 | | To account (standard payout) | From 2 hours to 3 business days | Not credited | | To account via BESP | Up to 1 hour during CBR operating day | Not credited | | Via FPS | Instant, 24/7 | Instant, 24/7 | | To YooMoney | Instant, 24/7 | Instant, 24/7 | ### 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. Transaction limits depend on the service provider and the terms of the Agreement signed between the Bank and the Partner. No API method to request the particular limits is provided. --- - [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 **cURL** ```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** ```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 **cURL** ```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" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` **PHP** ```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" }] } }' ``` ### 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 **cURL** ```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** ```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 **cURL** ```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** ```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. ### Sequence diagram ![Payout scheme from a collateral account by card number](/img/docs/payouts/schema_collateral_payout_without_widget_en.png) ```plantuml @startuml PayoutCollateralWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: sends ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [More about the payout statuses >](/reference/reference-objects.mdx#payout_status) [View error codes >](/reference/errors) --- - [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 sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. **For residents** | 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` | **For non-residents** | 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 {#target} 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 **For residents** `Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` **For non-residents** `{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 {#payout_account} #### 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 **For residents** ```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'{ "session_id": "ps_3230", "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" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` **For non-residents** ```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'{ "session_id": "ps_3230", "payment_method": { "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" } } }, "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 **cURL** ```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** ```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'); ``` Пример с отменой выплаты **cURL** ```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** ```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. ::: ### Sequence diagram ![Payout scheme from a collateral account by account number](/img/docs/payouts/schema_collateral_payout_account_without_widget_en.png) ```plantuml @startuml PayoutCollateralWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: sends ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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. **With the widget or by token/hash** 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) | **By card number** 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) ## 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. ## 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` | + | object | [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": { "type": "tax_short", "tax_details": {} } } }' ``` #### Payout with an extended set of parameters {#parameters_full} **Request parameters** | Name | Mandatory | Type | Description | |-----------------------------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [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` {#tax-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` {#tax-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` {#tax-doc} 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 {#tax-date} 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": { "type": "tax_full", "tax_details": { "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" } } }, "amount_details": { "amount": 5900, "currency": "rub" }, "customer": { "reference": "lucky", "contacts": [{ "email": "user123@test.com" }] }, "metadata": { "key": "value" } }' ``` ##### How to specify the payout purpose {#target} 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 **For residents** `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` **For non-residents** `{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) **With our 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 **cURL** ```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 } }' ``` **PHP** ```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 **cURL** ```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** ```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 '{ "session_id": "ps_3230", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Ivanov Ivan Ivanovich", "description": "Money transfer" } } }, "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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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 **cURL** ```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** ```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 **cURL** ```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** ```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. **By token** #### 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'{ "session_id": "ps_1694821", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Ivanov Ivan Ivanovich", "description": "Payout" } } }, "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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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 **cURL** ```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** ```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 **cURL** ```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** ```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. #### Sequence diagram **With our widget** ![Payout scheme from a collateral account with our widget](/img/docs/payouts/schema_collateral_payout_widget_account_en.png) ```plantuml @startuml PayoutCollateralWidgetAccount autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget Partner -> Bank_131: sends ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters the bank account details ... Partner -> Bank_131: sends ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: sends ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **By token** ![Payout scheme from a collateral account by token](/img/docs/payouts/schema_collateral_payout_account_without_widget_en.png) ```plantuml @startuml PayoutCollateralWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: sends ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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. **With our 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 **cURL** ```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 } }' ``` **PHP** ```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 **cURL** ```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** ```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 **cURL** ```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": "encrypted_card", "encrypted_card": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` **PHP** ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\EncryptedCard; 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('session_id') ->setCard(new EncryptedCard('9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48')) ->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" }] } }' ``` #### 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 **cURL** ```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** ```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 **cURL** ```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** ```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. **By token/hash** 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 **With a token received via the method** ```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": "tokenized_card", "tokenized_card": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "metadata": "good" }' ``` **With a hash from the widget** ```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": "encrypted_card", "encrypted_card": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` **With a token from recurring payments** ```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": "recurrent", "recurrent": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }, "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" }] } }' ``` #### 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 **cURL** ```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** ```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 **cURL** ```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** ```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. #### Sequence diagram **With our widget** ![Payout scheme from a collateral account with our widget](/img/docs/payouts/schema_collateral_payout_widget_card_en.png) ```plantuml @startuml PayoutCollateralWidgetCard autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget Partner -> Bank_131: sends ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters card details ... Partner -> Bank_131: sends ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: sends ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **By token/hash** ![Payout scheme from a collateral account by token](/img/docs/payouts/schema_collateral_payout_without_widget_en.png) ```plantuml @startuml PayoutCollateralWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details Partner -> Bank_131: sends ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [More about the payout statuses >](/reference/reference-objects.mdx#payout_status) [View error codes >](/reference/errors) --- - [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. ### 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` | |       `description` | + | string | Payout purpose (up to 128 characters) | | `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` | - | * | Any additional information| ### 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": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": { "account": "410012411727100", "description": "Payout purpose" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` --- - [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** ```html showLineNumbers Widget for bank account tokenization
``` ### 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 Use the widget to store bank card data with Bank 131. **What the widget looks like** **Code example** ```html showLineNumbers Card number tokenization widget.
``` ### How to use the widget You embed the widget on your website. The user enters their card number, Bank 131 stores it in its system, and returns a payout hash to you. You can save this hash and use it for future payouts to the same account. This is secure. :::info You can find out information about the hash using the [`token/info`](/reference/methods#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 `Bank131CardTokenizer` 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 `Bank131CardTokenizer` class constructor: ```js showLineNumbers const cardTokenizer = new Bank131CardTokenizer('public token'); ``` Set the following event handler for the successful completion of the tokenization process: ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { // ... }; ``` #### Step 5. Display the widget Call the `render()` method: ```js showLineNumbers cardTokenizer.render(); ``` ### Widget API #### Constructor: `Bank131CardTokenizer` {#card_tokenizer} Widget class constructor: ```js showLineNumbers new Bank131CardTokenizer(publicToken[, options]) ``` | Parameter | Type | Description | |-----------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------| | `PublicToken` | string | Public token. The parameter is mandatory | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the widget will be inserted. The default value is: `
` | | `options.texts` | object | | | `options.texts.cardNumberLabel` | string | Label for the card number field. Default value: `Card number` | | `options.texts.submitButtonLabel` | string | Label for the card linking button. Default value: `Link the card` | #### Method: `cardTokenizer.render()` It displays the widget in the container defined by the `options.container` parameter: ```js showLineNumbers cardTokenizer.render(); ``` #### Event handler: `cardTokenizer.onReady` It is called when the widget is ready for work: ```js showLineNumbers cardTokenizer.onReady = function () { /* handler */ }; ``` #### Event handler: `cardTokenizer.onTokenizationStart` It is called at the start of the hashing process: ```js showLineNumbers cardTokenizer.onTokenizationStart = function () { /* handler */ }; ``` #### Event handler: `cardTokenizer.onTokenizationSuccess` It is called when the tokenization process finishes successfully: ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { /* handler */ }; ``` | Parameter | Type | Description | |-------------------------------------|--------|-------------------------------------------------------------------------------------------| | `cardToken` | object | | | `cardToken.info` | object | Additional card information | | `cardToken.info.card_network` | string | Payment system type. Possible values: `visa`, `mastercard`, `mir` | | `cardToken.info.card_type` | string | Card type. Additionally specifies the subbrand (`visa_electron`, `maestro`, `mirmaestro`) | | `cardToken.info.masked_card_number` | string | Masked card number value, e.g. `424242******4242` | | `cardToken.token` | string | Card number hash | #### Event handler: `cardTokenizer.onTokenizationFail` It is called when the tokenization process finishes unsuccessfully: ```js showLineNumbers cardTokenizer.onTokenizationFail = function (error) { /* handler */ }; ``` ### Widget customization #### Appearance To customize the widget's appearance, include your own stylesheet after the default styles. Input fields inside `iframe` cannot be modified. An example of adding custom styles: ```html showLineNumbers ``` An example of reassigning the color: ```css showLineNumbers /* custom-styles.css */ .bank131-Field__label { color: green; } ``` #### Texts You can change the standard texts using the `options.texts` parameter in the [`Bank131CardTokenizer`](#card_tokenizer) constructor. [How to make a payout using the widget or by token >](/payouts/payout-tokenized-card) --- ## Payments - [Monthly report](https://developer.131.ru/en/payments/finance-act): Monthly payout report Bank 131 generates a monthly report on the rendered services and sends it to the email address specified in your agreement. You must sign the report and return it within 5 business days of receiving it. You can sign it using a qualified electronic signature (QES) and reply to the same email. If you prefer to receive reports via EDM or in paper form, please contact your account manager. ### PDF report template Monthly payout report [/assets/monthly_payout_report_bank_131_en.pdf](/assets/monthly_payout_report_bank_131_en.pdf) Monthly payment report [/assets/monthly_payment_report_bank_131_en.pdf](/assets/monthly_payment_report_bank_131_en.pdf) --- - [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.inform.qr.img` from the `action_required` webhook). * With a deeplink, which works for payments made from a mobile device (`customer_interaction.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": { "type": "faster_payment_system", "faster_payment_system": { "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": { "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": { "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", "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). ### Sequence diagram ![](/img/docs/payments/fps_en.png) ```plantuml @startuml autonumber "[00]" skinparam maxMessageSize 200 participant Partner participant Bank_131 participant Issuer_app Partner -> Bank_131: ""session/create"" Partner <-- Bank_131: ""200 OK"" Partner -> Bank_131: ""session/start/payment"" note left URL to take customer back after payment: ""payment_options.return_url"" end note Partner <-- Bank_131: ""200 OK"" opt #c9ed74 Optional \nAutomatic confirmation Partner <- Bank_131: ""ready_to_confirm"" Partner --> Bank_131: ""200 OK"" Partner -> Bank_131: ""session/confirm"" Partner <-- Bank_131: ""200 OK"" end Partner <- Bank_131: ""action_required"" note left Payment URL passed within ""customer_interaction.inform.qr.content"" end note Partner --> Bank_131: ""200 OK"" Partner->Partner: create QR out from URL within ""customer_interaction.inform.qr.content"" or forward customer to payment page at mobile device Partner->Issuer_app: customer is forwarded to issuer's app Issuer_app->Issuer_app: payment completed Issuer_app->Partner: customer returns at ""payment_options.return_url"" Partner <- Bank_131: ""payment_finished"" note left In ""session.acquiring_payments.customer.contacts.phone"" customer's phone number, masked or full end note Partner --> Bank_131: ""200 OK"" @enduml ``` --- - [Delayed capture payments](https://developer.131.ru/en/payments/payment-hold): Delayed payment deductions You can accept payments with an authorization hold: the customer's payment is first placed on hold ("frozen"), and then, on your command, it is captured—either in full or in part. This is convenient, for example, for paying for services after they have been rendered. Once the feature is enabled, all payments are processed with an authorization hold. The hold period is up to 5 days. If you do not capture the funds or cancel the payment by the end of this period, the payment is automatically returned to the customer. As an alternative to automatic refunds, you can enable automatic capture of the amount after the hold period expires. To enable authorization hold or set up automatic capture, contact your personal manager at Bank 131. The procedure depends on the payment method: with or without our widget. **Without our widget** #### Step 1. Create a payment session Send a ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) request. In response you will get the session identifier. > Alternatively, you can use the ([`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment) method to create a session and a payment at the same time. In this case, specify all the payment parameters and skip the next step. This option is not recommended. #### Step 2. Start the payment Send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request with the session identifier and payment parameters. #### Step 3. Wait for a webhook confirming the payment is ready Bank 131 will then send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to notify you that you should now confirm or cancel the payment. #### Step 4. Confirm or cancel the payment Check the data, then confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. #### Step 5. Wait for a webhook on additional actions An [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook from Bank 131 arrives if the customer's bank requests 3D Secure authentication or other actions. Redirect the customer using the link from the [`customer_interaction.redirect.url`](/reference/objects#redirect) parameter to complete 3D Secure authentication. #### Step 6. Wait for a webhook confirming that the funds have been placed on hold Bank 131 will send you a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook once the customer's funds are on hold. 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" }] } }' ``` #### Step 7. Capture the amount or cancel the payment Capture ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) the full or partial amount ([`amount_details`](/reference/reference-objects.mdx#amount_details)) or cancel the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel))—the held amount will be returned to the customer. #### Step 8. Wait for a webhook on the payment results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The payment status is in the `acquiring_payments/payment_list` array. If the status is `succeeded`, the payment went through. If the status is `failed`, the payment was not processed due to an error. **With our widget** #### Step 1. Create a payment session Send a ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) request. In response you will get the session identifier. #### Step 2. 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/methods#token)), specifying the widget type as `acquiring_widget`. The response will contain your public token. #### Step 3. Initialize the widget on your site [Initialize the widget on your site](/payments/payment-widget) using the public token obtained in the previous step. After this, the customer will be able to enter their bank card details into the data collection form, and Bank 131 will initiate the payment without your involvement. #### Step 4. Wait for a webhook confirming the payment is ready Bank 131 will then send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to notify you that you should now confirm or cancel the payment. #### Step 5. Confirm or cancel the payment Check the data, then 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`](/reference/reference-webhooks.mdx#action_required) webhook, then the customer's bank requests 3D Secure authentication or other actions. The customer is redirected automatically. #### Step 6. Wait for a webhook confirming that the funds have been placed on hold Bank 131 will send you a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook once the customer's funds are on hold. 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" }] } }' ``` #### Step 7. Capture the amount or cancel the payment Capture ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) the full or partial amount ([`amount_details`](/reference/reference-objects.mdx#amount_details)) or cancel the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel))—the held amount will be returned to the customer. #### Step 8. Wait for a webhook on the payment results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The payment status is in the `acquiring_payments/payment_list` array. If the status is `succeeded`, the payment went through. If the status is `failed`, the payment was not processed due to an error. #### Sequence diagram **Without our widget** ![Payment diagram with holding](/img/docs/payments/schema_payment_hold_en.png) ```plantuml @startuml autonumber header Delayed capture payments participant Partner participant Bank_131 participant ACS Partner -> Bank_131: ""session/create"" Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payment"" Bank_131 --> Partner: 200 OK Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure Bank_131 -> Partner: ""action_required"" Partner --> Bank_131: 200 OK Partner -> ACS: redirects the user to pass 3D Secure ACS -> Bank_131: passes 3D Secure result end alt Bank_131 -> Bank_131: holds funds Bank_131 -> Partner: ""ready_to_capture"" Partner --> Bank_131: 200 OK Partner -> Bank_131: confirms ""session/capture"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: debits funds Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **With our widget** ![Payment diagram with holding](/img/docs/payments/schema_payment_with_form_en.png) ```plantuml @startuml autonumber header Delayed capture payments using our widget participant Partner participant Bank_131 participant Bank_131_Widget participant ACS Partner -> Bank_131: ""session/create"" Bank_131 --> Partner: 200 OK Partner -> Bank_131: issues a public token Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: calls widget.js ... Customer interaction with the payment form ... Bank_131_Widget -> Bank_131: initializes payment Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure Bank_131 -> Bank_131_Widget: data for passing 3D Secure Bank_131_Widget -> ACS: redirects the user to pass 3D Secure ACS -> Bank_131: passes 3D Secure result end alt Bank_131 -> Bank_131: holds funds Bank_131 -> Partner: ""ready_to_capture"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/capture"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: debits funds Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK Bank_131 -> Bank_131_Widget: passes payment information Bank_131_Widget -> Bank_131_Widget: displays payment status @enduml ``` --- - [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](/assets/payments/restricted-business_en.pdf), 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 {#cross-identifier-card} 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. ### Payment crediting timeframes | Method | Weekdays | Weekends/Public holidays | |---------------------------------------------|-----------------------------------------|---------------------------------| | Card | On business days | Not credited | | FPS | Instant, 24/7 | Instant, 24/7 | | SberPay | On business days | Not credited | | T-Pay | On business days | Not credited | | YooMoney | On business days | Not credited | ### 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 Card payments can be processed with a single request—the result is returned immediately in the response. In this case, webhooks from Bank 131 are not sent. This method is suitable if you are not using the [payment form widget](/payments/payment-widget). > We do not recommend processing payments with a single request. If you still wish to use this method, please contact your personal account manager at Bank 131. ### Step 1. Create a payment with a single request Start the payment using the [`session/init/payment/sync`](/reference/methods#sessioninitpaymentsync) method. Pass the payment parameters. Single-request payment 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" } }' ``` ### Step 2. Wait for the payment result The payment status is returned in the response in the `status` parameter of the `acquiring_payments`/`payment_list` array: - `succeeded` — the payment was successful - `failed` — the payment failed due to an error - `pending` — 3D Secure authentication is required. Redirect the payer using the link from the [`customer_interaction.redirect.url`](/reference/objects#redirect) parameter to complete 3D Secure authentication - `in_progress` — the payment is being processed (returned if processing takes more than 40 seconds) Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2025-05-27T02:03:00.000000Z", "updated_at": "2025-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_203", "status": "succeeded", "created_at": "2025-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" } }] } } ``` :::info[] You can also check the final status using the [`session/status`](/reference/methods#sessionstatus) method. ::: [View error codes >](/reference/errors) --- - [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 You can accept payments by bank cards. This method is suitable for services that comply with the PCI DSS standard and store card data on their side. ### Step 1. Create a payment session Create a session using the [`session/create`](/reference/methods#sessioncreate) method. You will receive the payment session identifier in response. > Alternatively, you can use the [`session/init/payment`](/reference/methods#sessioninitpayment) method to create a session and a payment at the same time. In this case, specify all the payment parameters right away and skip the next step. This option is not recommended. Creating a session **cURL** ```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": "good" }' ``` **PHP** ```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('good') ->build(); $response = $client->session()->create($request); ``` ### Step 2. Start the payment Start the payment using the [`session/start/payment`](/reference/methods#sessionstartpayment) method. Pass the session identifier along with the payment parameters. Request example **cURL** ```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": "2200774546102058", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } } }, "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "metadata": "good" }' ``` **PHP** ```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; $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( '2200774546102058', '01', '26', '123', 'cardholder name' ) ) ->setCustomer(new Customer('user123')) ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); ``` ### Step 3. Wait for a webhook saying the payment is ready Bank 131 will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. This means that the payment 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": "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": { "last4": "2058", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ### Step 4. Confirm or cancel the payment Check the payment details and confirm that you are ready to perform the payment ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel it ([`session/cancel`](/reference/methods#sessioncancel)). Confirming the session **cURL** ```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** ```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 **cURL** ```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** ```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 on additional actions The [`action_required`](/reference/webhooks#action_required) webhook is sent if the payer's bank requests 3D Secure authentication. Redirect the payer using the link from the [`customer_interaction.redirect.url`](/reference/objects#redirect) parameter to complete 3D Secure authentication. 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": "2058" } }, "amount_details": { "amount": 10000, "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" } } } }] } }' ``` ### Step 6. Wait for a webhook with the payment results Bank 131 will send you a [`payment_finished`](/reference/webhooks#payment_finished) webhook. 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 was successful. If the status is `failed`, then the payment failed because of an error. ### Sequence diagram ![Payment scheme by bank card with PCI DSS](/img/docs/payments/schema_payment_pcidssNOHOLD_en.png) ```plantuml @startuml PaymentPCIDSS autonumber participant Partner participant Bank_131 participant ACS Partner -> Bank_131: ""session/create"" Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payment"" Bank_131 --> Partner: 200 OK Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure Bank_131 -> Partner: ""action_required"" Partner --> Bank_131: 200 OK Partner -> ACS: redirects the customer to pass 3D Secure ACS -> Bank_131: passes 3D Secure result end alt Bank_131 -> Bank_131: debits funds Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [More about the payment statuses >](/reference/objects#payment_status) [View error codes >](/reference/errors) --- - [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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "initiator": "client" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "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. ### Sequence diagram ![](/img/docs/payments/cit_en.png) ```plantuml @startuml actor Customer participant Partner participant Bank_131 participant ACS autonumber Customer -> Partner: Requests a recurring payment Partner -> Partner: Customer validation required Partner -> Bank_131: ""/api/v1/session/init/payment:"" \n -"" "recurrent": {"" \n \t "" "token": "token_value","" \n \t "" "initiator": "client"},"" \n \t ... \n - ""return_url"" (to redirect the Customer from ACS) \n - other required settings Partner <-- Bank_131: ""http 200"" Bank_131 -> Partner: ""action_required"" note left Settings for 3DS verification end note Bank_131 <-- Partner: ""http 200"" Partner -> Customer: redirected at ACS Customer -> ACS: enters code ACS --> Customer: redirects the Customer using ""return_url"" note right #FFAAAA For ""return_url"", the method can be GET or POST end note Bank_131 -> Partner: ""payment_finished"" @enduml ``` --- - [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 {#with_charge} 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 **Success** ```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", "status": "accepted", "created_at": "2024-08-08T08:06:51.841432Z", "updated_at": "2024-08-08T08:14:56.168219Z", "acquiring_payments": [{ "id": "pm_308906", "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": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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" } } }' ``` **Failure** ```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", "status": "cancelled", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "acquiring_payments": [{ "id": "pm_308906", "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 {#no_charge} 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": { "type": "faster_payment_system_binding" }, "amount_details": { "amount": 100, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "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": { "type": "recurrent", "recurrent": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` ### How to create multiple FPS subscriptions for the same payer and bank {#multiple-subscriptions} Each time an FPS 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": { "subscription_service_info": { "id": "54f731a9f86b46188b7961cb933fb3ff", // subscription identifier "name": "subscription2" // subscription name } } }, "amount_details": { "amount": 1000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "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) **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 {#agreement} ### 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 {#token} 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. :::info[] If the card is changed, get a new recurring token. ::: ### 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 {#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 {#first_payment} **Without our widget** >[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 **cURL** ```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": { "recurrent": true } }' ``` **PHP** ```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->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); ``` **With our widget** >[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", "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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "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 {#recurring_payment} 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 **cURL** ```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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` **PHP** ```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() ->setRecurrentToken('9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48') ->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 refund a successful payment to the payer in full or in part using the [session/refund](/reference/methods#sessionrefund) method. The Bank 131 fee charged on the payment is non-refundable. :::warning[] A refund cannot be undone. Please make sure this action is necessary. ::: The payer can also dispute a payment through the **chargeback** procedure. Bank 131 will notify you if this happens. For both operations, the amount is deducted from your settlement. Records of `refund` and `chargeback` operations are included in the [payment registry](/finance/payment-daily-report). ### Step 1. Send a refund request Send a [`session/refund`](/reference/methods#sessionrefund) request. In the `session_id` field passing the identifier of the [payment session](/reference/objects#payment_session) you are refunding in the `session_id` parameter. Pass the refund amount in the `amount_details.amount` parameter. If you leave this parameter empty, the full payment amount will be refunded to the payer. Example **cURL** ```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** ```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 for a webhook with the refund results Bank 131 will send you a [`payment_refunded`](/reference/webhooks#payment_refunded) webhook. You will find the result of the refund in the `status` field of the `refunds` array: - `accepted`—the refund has been completed successfully - `in_progress`—the refund is being processed - `error`—the refund has failed due to an error - `declined`—the refund has been declined by Bank 131 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": "2025-05-27T02:03:00.000000Z", "updated_at": "2025-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2025-05-27T02:03:00.000000Z", "finished_at": "2025-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "mir", "last4": "2058" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 100, "currency": "RUB" } } }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2025-05-27T02:03:00.000000Z", "finished_at": "2025-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 0, "currency": "RUB" } } } }] }] } }' ``` --- - [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 `cancelled` status. ### Payment scenario The payment scenario depends on the customer's payment channel: mobile application (app), mobile browser (mobile_web), or desktop browser (web). **Mobile application (app)** 1. Create a session separately 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 session separately. 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 `onlineapp://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 `onlineios-app://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 `startonline://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 `onlineappmobile://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 `budgetonline-ios://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 to hide a possible alert if the deeplink could not open properly. 24. Redirect back to your page with the new request settings. 25. Open the `btripsexpenses://sbolpay/...` deeplink. 26. Wait 50ms. 27. Reload the page to hide a possible alert if the deeplink could not open properly. 28. Redirect back to your page with the new request settings. 29. Open the `kidsonline://sbolpay/...` deeplink. 30. Wait 50ms. 31. Reload the page to hide a possible alert if the deeplink could not open properly. 32. 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": { "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" } }' ``` 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 } }] } } ``` **Mobile browser (mobile_web)** 1. Create a session separately 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 session separately. 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 `onlineapp://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 `onlineios-app://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 `startonline://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 `onlineappmobile://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 `budgetonline-ios://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 to hide a possible alert if the deeplink could not open properly. 24. Redirect back to your page with the new request settings. 25. Open the `btripsexpenses://sbolpay/...` deeplink. 26. Wait 50ms. 27. Reload the page to hide a possible alert if the deeplink could not open properly. 28. Redirect back to your page with the new request settings. 29. Open the `kidsonline://sbolpay/...` deeplink. 30. Wait 50ms. 31. Reload the page to hide a possible alert if the deeplink could not open properly. 32. 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": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "mobile_web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "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 } }] } } ``` **Desktop browser (web)** 1. Create a session separately 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 payer's phone number in the `phone` 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 session separately. 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": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "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 } }] } } ``` ### Sequence diagram Show diagrams **Mobile application (app)** ![](/img/docs/payments/sberpay_app_en.png) ```plantuml @startuml sberpay_app_en autonumber header SberPay actor Customer participant Partner participant Bank_131 participant Sber Customer -> Partner: makes payment\nfrom a mobile app\nvia SberPay Partner -> Partner: verifies the customer's payment channel Partner -> Partner: verifies if a phone number passed Partner -> Bank_131: ""session/init/payment"": \n - type = sber_pay \n - channel = ENUM: app \n - phone = value \n - return_url = deeplink \n - other required settings Partner <-- Bank_131: ""ready_to_confirm"" alt #faf1d7 Cancel payment Partner -> Bank_131: ""session/cancel"" Bank_131 --> Partner: ""payment_finished"" Partner --> Customer: payment results end Partner -> Bank_131: payment confirmation \n""session/confirm"" Bank_131 ->Sber: creates a payment using SberPay Bank_131 <-- Sber: http 200 alt #faf1d7 Payment rejected/20 min timeout Customer -> Customer: payment rejected by Sber \n or no customer's activity \nwithin 20 minutes note left Customer can tap **Cancel** within a Sber app and they will be taken back to the URL passed within ""return_url"". Transaction will not be canceled, and you can forward the customer back for payment within the 20 minutes interval. end note Bank_131 <-- Sber: transaction is canceled by timeout Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results end alt #faf1d7 Optional. ""sberpay/push"" to send PUSH or SMS to the customer Partner -> Bank_131: ""sberpay/push"" Partner <-- Bank_131: http 200 note left #red 1. Payment cannot be guaranteed for the ""app"" channel! 2. PUSH/SMS method is defined by Sber. end note Bank_131 -> Sber: sends PUSH Bank_131 <-- Sber: http 200 Sber -> Customer: sends PUSH or SMS Customer -> Sber: makes payment Sber --> Bank_131: payment results Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results end Bank_131 -> Partner: ""action_required""\n""redirect.url"" Partner -> Customer: forwards customer to ""redirect.url"" note right Follow the algorithm described on this page to select a proper iOS mobile application end note Customer -> Sber: forwards to ""redirect.url"" Partner -> Partner: waits for ""payment_finished"" \n or sends requests (no more than once in 5 seconds)\nto obtain the transaction status Customer -> Sber: makes payment Sber --> Customer: Returns customer to ""return_url"" Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results @enduml ``` **Mobile browser (mobile_web)** ![](/img/docs/payments/sberpay_webmobile_en.png) ```plantuml @startuml sberpay_webmobile_en autonumber header SberPay actor Customer participant Partner participant Bank_131 participant Sber Customer -> Partner: makes payment\nfrom a mobile browser\nvia SberPay Partner -> Partner: verifies the customer's payment channel Partner -> Partner: verifies if a phone number passed Partner -> Bank_131: ""session/init/payment"": \n - type = sber_pay \n - channel = ENUM: mobile_web \n - phone = value \n - return_url = URL \n - other required settings Partner <-- Bank_131: ""ready_to_confirm"" alt #faf1d7 Cancel payment Partner -> Bank_131: ""session/cancel"" Bank_131 --> Partner: ""payment_finished"" Partner --> Customer: payment results end Partner -> Bank_131: payment confirmation \n""session/confirm"" Bank_131 ->Sber: creates a payment using SberPay Bank_131 <-- Sber: http 200 alt #faf1d7 Payment rejected/20 min timeout Customer -> Customer: payment rejected by Sber \n or no customer's activity \nwithin 20 minutes Bank_131 <-- Sber: transaction canceled by timeout Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results end alt #faf1d7 Optional. ""sberpay/push"" to send PUSH or SMS to customer Partner -> Bank_131: ""sberpay/push"" Partner <-- Bank_131: http 200 note left PUSH/SMS method is defined by Sber. end note Bank_131 -> Sber: send PUSH Bank_131 <-- Sber: http 200 Sber -> Customer: Sends PUSH or SMS Customer -> Sber: makes payment Sber --> Bank_131: payment results Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results end Bank_131 -> Partner: ""action_required""\n""redirect.url"" Partner -> Customer: forwards customer to ""redirect.url"" Customer -> Sber: forwards to ""redirect.url"" Partner -> Partner: waits for ""payment_finished"" \n or sends requests (1 time or less in 5 seconds)\nto obtain the transaction status Customer -> Sber: makes payment Sber --> Customer: returns the customer to ""return_url"" Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results @enduml ``` **Desktop browser (web)** ![](/img/docs/payments/sberpay_web_en.png) ```plantuml @startuml sberpay_web_en autonumber header SberPay actor Customer participant Partner participant Bank_131 participant Sber Customer -> Partner: makes payment\nfrom a web browser\nvia SberPay Partner -> Partner: verifies the customer's payment channel Partner -> Partner: verifies if a phone number passed Partner -> Bank_131: ""session/init/payment"": \n - ""type = sber_pay"" \n - ""channel = ENUM: web"" \n - ""return_url = URL"" \n - ""phone = value"" \n - other required parameters note left 1. ""phone"" setting is mandatory. 2. ""return_url"" is mandatory but its value is ignored and the customer is not taken back from Sber. end note Partner <-- Bank_131: ""ready_to_confirm"" alt #faf1d7 Cancel payment Partner -> Bank_131: ""session/cancel"" Bank_131 --> Partner: ""payment_finished"" Partner --> Customer: payment results end Partner -> Bank_131: payment confirmation \n""session/confirm"" Bank_131 ->Sber: creates a payment using SberPay Bank_131 <-- Sber: http 200 Partner -> Partner: waits for ""payment_finished"" \n or sends requests (no more than once in 5 seconds)\nto obtain the transaction status Sber --> Customer: sends PUSH or SMS Customer -> Sber: makes payment Sber --> Bank_131: payment results Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results alt #faf1d7 payment rejected/20 min timeout Customer -> Customer: payment rejected by Sber \n or no customer's activity \nwithin 20 minutes Bank_131 <-- Sber: transaction canceled by timeout Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results end alt #faf1d7 Optional. ""sberpay/push"" to send PUSH or SMS to customer Partner -> Bank_131: ""sberpay/push"" Partner <-- Bank_131: http 200 note left PUSH/SMS method is defined by Sber. end note Bank_131 -> Sber: send PUSH Bank_131 <-- Sber: http 200 Sber -> Customer: sends PUSH or SMS Customer -> Sber: payment Sber --> Bank_131: payment results Bank_131 --> Partner: ""payment_finished""\npayment results Partner --> Customer: payment results end @enduml ``` ### Selecting a proper deeplink for Sber iOS mobile applications {#sberselect} Code example for selection logic implementation ```c showLineNumbers const openOnlineApp = () => { window.location.href = "onlineapp://sbolpay/invoicing/v2? bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; 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 openOnlineAppMobile = () => { 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 openAppSmart = () => { window.location.href = "ios-app-smartonline://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 openKids = () => { window.location.href = "kidsonline://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(openOnlineApp, 50); clearMessage() setTimeout(openOnlineIosApp, 50); clearMessage() setTimeout(openStartOnline, 50); clearMessage() setTimeout(openOnlineAppMobile,50); clearMessage() setTimeout(openBuget, 50); clearMessage() setTimeout(openAppSmart, 50); clearMessage() setTimeout(openBtripExp, 50); clearMessage() setTimeout(openKids, 50); clearMessage(); setTimeout(openLandingpage, 800); } ``` ### Recurring payments {#r-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", "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": { "type": "recurrent", "recurrent": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" } }' ``` --- - [SberPay payments via our widget](https://developer.131.ru/en/payments/payment-sber-pay-with-widget): Accept SberPay payments using our widget You can accept payments via SberPay using our widget. No card details need to be entered to make a payment. ### Step 1. Create a payment session Send a request to create a payment session [`session/create`](/reference/methods#sessioncreate). In the response, you will receive the session identifier. 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" }' ``` ### Step 2. Get a public token Get a public token to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/methods#token)) passing the widget type (`sber_pay_widget`). In the response, you will receive a public token. > For the first payment from a device, the payer needs to authorize. For subsequent payments up to 10,000 rubles inclusive, re-authorization is not required. To force authorization on each payment regardless of the amount, pass the payer's phone number (`phone`) when calling the `token` method. The number will be automatically inserted into the widget, and the payer can change it if necessary. Request example ```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 '{ "sber_pay_widget": { "session_id": "ps_77872830", "phone": "79680000000", "return_url": "https://131.ru" } }' ``` ### Step 3. Initialize the widget on the site [Initialize the widget on the site](/payments/payment-sber-pay-widget) using the public token obtained in the previous step. Our widget creates a transaction, collects the data required to process it, and opens the widget for payment via SberPay. The payer authorizes in the SberPay widget and makes the payment. > The payer has 20 minutes to complete the payment. If the payer does not pay within this time, the transaction will be automatically canceled with the `cancelled` status. After the payment, the payer returns to the URL specified in the `return_url` parameter. Wait until the payer either confirms or cancels the payment. ### Step 4. Wait for an `action_required` webhook Wait for an [`action_required`](/reference/webhooks#action_required) webhook from Bank 131. This means that the payer has started the payment via the SberPay widget. 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_77872830", "status": "in_progress", "created_at": "2026-08-18T06:58:02.250718Z", "updated_at": "2026-08-18T06:59:10.000000Z", "acquiring_payments": [{ "id": "pm_17617410", "status": "pending", "created_at": "2026-08-18T06:59:05.000000Z", "customer": { "reference": "sberpay" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "channel": "widget" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "inform", "inform": { "type": "notification", "notification": { "type": "sber_pay_widget", "sber_pay_widget": { "order_id": "019ff9be-7bbf-5fb2-1e7f-ef6dedfb7b5d" } } } } }], "actions": { "confirm": "2026-08-18T06:59:10.000000Z" } } }' ``` ### Step 5. Wait for a `payment_finished` webhook Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the payment results. The `succeeded` status means the payment was successful. If the status is `failed`, the payment failed. 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_77872830", "status": "accepted", "created_at": "2026-08-18T06:58:02.250718Z", "updated_at": "2026-08-18T07:08:04.356341Z", "acquiring_payments": [{ "id": "pm_17617410", "status": "succeeded", "created_at": "2026-08-18T07:08:03.323479Z", "customer": { "reference": "sberpay" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "channel": "widget" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "amounts": {} }] } }' ``` ### Sequence diagram ![Sequence diagram](/img/docs/payments/schema_sberpay_en.png) ```plantuml @startuml SberPay autonumber participant Partner participant Bank_131 participant Widget participant Sber Partner -> Bank_131: ""session/create"" Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""token"" Bank_131 --> Partner: 200 OK Partner -> Widget: initializes the widget Widget -> Bank_131: creates a transaction ... The payer authenticates in the SberPay widget and pays ... Widget -> Sber: payment request Sber -> Widget: payment confirmation Bank_131 -> Partner: ""action_required"" Partner --> Bank_131: 200 OK Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` --- - [SberPay widget](https://developer.131.ru/en/payments/payment-sber-pay-widget): Connect and set up the widget for accepting SberPay payments Our SberPay payment widget allows you to accept payments without entering card details. Example of a page with the widget ```html showLineNumbers SberPay payment
``` ### How the widget works You embed the widget on your website. The widget opens a SberPay window, where the user authorizes and confirms the payment. After that, the widget displays the status and result of the operation. ### Widget initialization #### Step 1. Get a public token Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), passing the widget type (`sber_pay_widget`) in it. In the response you will receive a public token. #### Step 2. Connect the script and styles Connect the widget script (JS) and styles (CSS): ```html showLineNumbers ``` After connecting the script, the `Bank131SberPayPayment` class will appear in the global scope. #### Step 3. Add a container Add a container with a unique identifier to place the widget on your page: ```html showLineNumbers
``` #### Step 4. Create a class instance Pass the public token to the constructor of the `Bank131SberPayPayment` class: ```js showLineNumbers const widget = new Bank131SberPayPayment('publicToken'); ``` #### Step 5. Render the widget Call the `render()` method: ```js showLineNumbers widget.render(); ``` ### Widget API #### Constructor: `Bank131SberPayPayment` Widget class constructor: ```js showLineNumbers const widget = new Bank131SberPayPayment(publicToken) ``` | Parameter | Type | Mandatory |Description | |-----------------|--------| --------|-----------------------| | `publicToken` | string | + | Public token | #### Method: `widget.render()` It renders the widget inside the container specified in `id="bank131-sber-pay-payment"`: ```js showLineNumbers widget.render(); ``` #### Event handler: `widget.onReady` It is called when the widget is ready to work: ```js showLineNumbers widget.onReady = function () { /* handler */ } ``` #### Event handler: `widget.onSberPayStart` It is called at the start of the payment process via SberPay: ```js showLineNumbers widget.onSberPayStart = function () { /* handler */ } ``` #### Event handler: `widget.onSberPaySuccess` It is called when the payment is successfully completed: ```js showLineNumbers widget.onSberPaySuccess = function () { /* handler */ } ``` #### Event handler: `widget.onSberPayFail` It is called when the payment fails: ```js showLineNumbers widget.onSberPayFail = function (error) { /* handler */ } ``` [How to accept a payment via SberPay using our widget >](/payments/payment-sber-pay-with-widget) --- - [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 [payment 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. Payers do not have to enter card details to make payments. ### Payment scenario The payment scenario depends on the payer's payment channel: mobile device (mobile) or desktop browser (desktop). The payer device properties in the request define the format of the payment link in the `action_required` webhook. **Mobile device (mobile)** 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": { "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } } }' ``` 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": 67000, "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 payer 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": 67000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { "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 payer by the link passed within the `redirect.url` parameter to the T-Bank mobile application. Wait until the payer approves or cancels the payment. >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 `cancelled` status. 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the payment result from Bank 131. The `succeeded` status indicates a successful payment. **Desktop browser (desktop)** 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 `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": { "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "desktop", "os": "windows", "browser": "chrome" } } }' ``` 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 payment link in the `redirect.url` parameter. 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": 67000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { "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. Forward the payer by the link from the `redirect.url` parameter to T-Bank's web interface. Wait until the payer approves or cancels the payment. >The link cannot be opened in an `iframe`. Forward the payer directly by the link to T-Bank's web interface. >After being redirected, the payer will have 20 minutes to complete the payment. Otherwise, the session terminates within 20 minutes with the `cancelled` status. 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the payment result from Bank 131. The `succeeded` status indicates a successful payment. ### Sequence diagram Show diagrams **Mobile device (mobile)** ![](/img/docs/payments/tpay_mobile_en.png) ```plantuml @startuml tpay_app autonumber header TPay actor Customer participant Partner participant Bank_131 participant T_Bank Customer -> Partner: chooses T-Pay payment Partner -> Partner: verifies the customer's payment channel Partner -> Bank_131: ""session/init/payment"" Partner <-- Bank_131: ""ready_to_confirm"" alt #faf1d7 Cancel payment Partner -> Bank_131: ""session/cancel"" Bank_131 --> Partner: ""payment_finished"" Partner --> Customer: payment results end Partner -> Bank_131: ""session/confirm"" Bank_131 -> T_Bank: creates a T-Pay payment alt #faf1d7 Payment rejected/20 min timeout Customer -> Customer: payment rejected by T-Bank \n or no customer's activity \nwithin 20 minutes Bank_131 <-- T_Bank: transaction canceled by timeout Bank_131 --> Partner: ""payment_finished"" Partner --> Customer: payment results end Bank_131 -> Partner: ""action_required""\n""redirect.url"" Partner -> Customer: forwards the customer to ""redirect.url"" alt #faf1d7 Customer doesn't have T-Bank app Customer -> Customer: redirect to the page with an offer to become a T-Bank customer end Customer -> T_Bank: goes to the app by the ""redirect.url""\n- chooses an account\n- performs T-Pay payment T_Bank -> T_Bank: payment authorization alt #pink Authorization failed T_Bank -> Customer: displays failure screen Bank_131 -> Partner: ""payment_finished"" else #lightgreen Authorization successful T_Bank -> Customer: displays success screen Bank_131 -> Partner: ""payment_finished"" end alt @enduml ``` **Desktop browser (desktop)** ![](/img/docs/payments/tpay_desktop_web_interface_en.png) ```plantuml @startuml tpay_desktop autonumber header TPay actor Payer participant Partner participant Bank_131 participant T_Bank Payer -> Partner: chooses T-Pay payment Partner -> Partner: verifies the Payer's payment channel Partner -> Bank_131: ""session/init/payment"" Partner <-- Bank_131: ""ready_to_confirm"" alt #faf1d7 Cancel payment Partner -> Bank_131: ""session/cancel"" Bank_131 --> Partner: ""payment_finished"" Partner --> Payer: payment results end Partner -> Bank_131: ""session/confirm"" Bank_131 -> T_Bank: creates a T-Pay payment alt #faf1d7 Payment rejected/20 min timeout Payer -> Payer: payment rejected by T-Bank \n or no Payer's activity \nwithin 20 minutes Bank_131 <-- T_Bank: transaction canceled by timeout Bank_131 --> Partner: ""payment_finished"" Partner --> Payer: payment results end Bank_131 -> Partner: ""action_required""\n""redirect.url"" Partner -> Payer: forwards the payer to T-Bank's \nweb interface from ""redirect.url"" alt #faf1d7 Payer is not a T-Bank client Payer -> Payer: redirected to the page with an offer to become a T-Bank client end Payer -> T_Bank: goes to the web interface by ""redirect.url""\n and performs T-Pay payment T_Bank -> T_Bank: payment authorization alt #pink Authorization failed T_Bank -> Payer: displays failure screen Bank_131 -> Partner: ""payment_finished"" else #lightgreen Authorization successful T_Bank -> Payer: displays success screen Bank_131 -> Partner: ""payment_finished"" end alt @enduml ``` ### Recurring payments {#r-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": { "recurrent": true, "platform_details": { "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 **MIT recurring 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": "recurrent", "recurrent": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "initiator":"merchant" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "android", "browser": "chrome" } } }' ``` **Response example** ```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": {} }] } } ``` **CIT recurring 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": "recurrent", "recurrent": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "initiator":"client" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } } }' ``` **Response example** ```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 You can accept bank card payments via our payment widget. In this case, card data is stored at Bank 131, not on your side. ### Step 1. Create a payment session Create a session using the [`session/create`](/reference/methods#sessioncreate) method. You will receive the payment session identifier in response. Example **cURL** ```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@example.com" }] }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }' ``` **PHP** ```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); ``` ### Step 2. 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/methods#token)), specifying the widget type as `acquiring_widget`. The response will contain your public token. > To perform [recurring payments](/payments/payment-recurring), add an **I agree to recurring payments** checkbox to the payment form. To do this, set the `show_recurrent_checkbox` parameter to `true`. Example **cURL** ```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" } }' ``` **PHP** ```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( 'ps_123456', 'https://success.url', 'https://failed.url', false ) ->build(); $publicTokenResponse = $client->widget()->issuePublicToken($request); $publicToken = $publicTokenResponse->getPublicToken(); ``` ### Step 3. Initialize the widget on your site [Initialize the widget on your site](/payments/payment-widget) using the public token obtained in the previous step. After this, the customer will be able to enter their bank card details into the data collection form, and Bank 131 will initiate the payment without your involvement. ### Step 4. Wait for a webhook confirming the payment is ready Bank 131 will send you a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. This means that the payment can be performed and the Bank is waiting for you to confirm or cancel it. 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_123456", "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@example.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }] } }' ``` ### Step 5. Confirm or cancel the payment Check the payment details and confirm that you are ready to perform the payment ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel it ([`session/cancel`](/reference/methods#sessioncancel)). > If you receive an `action_required` webhook, it means the customer's bank requires 3D Secure authentication. Redirection happens automatically. Example **Confirming the session** **cURL** ```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_123456" }' ``` **PHP** ```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** **cURL** ```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_123456" }' ``` **PHP** ```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 6. Wait for a webhook with the payment results Bank 131 will send you a [`payment_finished`](/reference/webhooks#payment_finished) webhook. 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 was successful. If the status is `failed`, then the payment failed because of an error. ### Sequence diagram ![Diagram for payment via payment form](/img/docs/payments/schema_payment_with_formNOHOLD_en.png) ```plantuml @startuml PaymentWithForm autonumber header Payment using the widget participant Partner participant Bank_131 participant Bank_131_Widget participant ACS Partner -> Bank_131: ""session/create"" Bank_131 --> Partner: 200 OK Partner -> Bank_131: issues a public token Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: calls widget.js ... Customer interaction with the payment form ... Bank_131_Widget -> Bank_131: initializes payment Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: checks the card for participation in 3D Secure alt #faf1d7 The card participates in 3D Secure Bank_131 -> Bank_131_Widget: data for passing 3D Secure Bank_131_Widget -> ACS: redirects the customer to pass 3D Secure ACS -> Bank_131: passes 3D Secure result end alt Bank_131 -> Bank_131: debits funds Bank_131 -> Partner: ""payment_finished"" Partner --> Bank_131: 200 OK Bank_131 -> Bank_131_Widget: passes payment information Bank_131_Widget -> Bank_131_Widget: displays payment status @enduml ``` [More about the payment statuses >](/reference/objects#payment_status) [View error codes >](/reference/errors) --- - [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). :::info Payments with YooMoney are made without the Bank 131 payment widget. ::: #### Step 1. Create a payment session {#yoo_payment} Send a ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) request. In response you will get the session identifier. > Alternatively, you can use the ([`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment) method to create a session and a payment at the same time. In this case, specify all the payment parameters and skip the next step. This option is not recommended. #### Step 2. Start the payment Send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request with the session identifier and payment parameters. Optionally, you can pass a URL in `payment_options.return_url` to redirect the payer back after the payment is completed. >The payment amount limits depend on the [YooMoney wallet level](https://yookassa.ru/docs/support/payments/limits)—the higher the level, the larger the amount that can be charged. 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 '{ "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "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" } }' ``` #### Step 3. Wait for a webhook confirming the payment is ready Bank 131 will then send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to notify you that you should now confirm or cancel the payment. 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": { "return_url": "https://www.131.ru", "description": "description" } }], "next_action": "confirm" } }' ``` #### Step 4. Confirm or cancel the payment Check the data, then confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. #### Step 5. Wait for a webhook on additional actions An [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook from Bank 131 arrives if the payer needs to confirm the charge in their YooMoney wallet. Redirect the customer using the link from the [`customer_interaction.redirect.url`](/reference/objects#redirect) parameter. Wait for the payer to confirm the payment. > The payer has 20 minutes to confirm the payment after being redirected. If the timeout expires, the transaction will automatically complete with the `cancelled` status. 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": {}, "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": {} } }, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://www.131.ru", "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z" } } }' ``` #### Step 6. Wait for a webhook on the payment results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The payment status is in the `acquiring_payments/payment_list` array. If the status is `succeeded`, the payment went through. If the status is `failed`, the payment was not processed due to an error. 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", "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": 25420, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "return_url": "https://www.131.ru", "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z", "capture": "2025-11-05T08:45:18.934056Z" } } }' ``` ### Sequence diagram View the diagram ![](/img/docs/payments/yoomoney_en.png) ```plantuml @startuml autonumber header Payments with YooMoney actor Payer participant Partner participant Bank_131 participant YooMoney Payer->Partner: chooses YooMoney as a payment method Partner -> Bank_131: ""session/create"" Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payment"" Bank_131 --> Partner: 200 OK Bank_131 -> Partner: ""ready_to_confirm"" Partner --> Bank_131: 200 OK Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: 200 OK Partner<-Bank_131: ""action_required"" Partner --> Bank_131: 200 OK Partner->Payer: redirects the payer to the payment page Payer->YooMoney: follows the link, logs in Payer->YooMoney: upgrades the wallet level if required Payer->YooMoney: confirms the payment Payer<--YooMoney: redirects the payer if a URL was passed Partner<-Bank_131: ""payment_finished"" Partner-->Bank_131: 200 OK @enduml ``` ### MIT recurring payments {#r-payments} :::info CIT recurring payments with YooMoney wallets are not supported. ::: Make a one-time payment to get a recurring token. You can use this token to make subsequent payments. #### Get a recurring token When making a one-time payment, send `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": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "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", "recurrent": true } }' ``` #### Make a payment by token Use the token received earlier. 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": "recurrent", "recurrent": { "token": "7e2b9c4a1f6d8035b3a7e0c9d5f28416a8c3e7b0d9f4a1c6e2b8d5f093a7c4e1" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] } }' ``` [More about MIT recurring payments >](/payments/payment-recurring) [More about the payment statuses >](/reference/objects#payment_status) [View error codes >](/reference/errors) --- - [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 payments. 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 recurring payments** **With no cardholder** **With the note** **Code example** ```html showLineNumbers Payment form widget
``` ### 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` {#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 {#window} 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 {#no-name} To hide the **Cardholder** filed, pass `hideCardHolderField: true`. By default, the field is shown. #### Display the note on certificates To display the note on certificates issued by the National Certification Center of the Russian Ministry of Digital Development, pass `isMDDCertificatesDisclaimerDisplayed: true`. By default, the note is not 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 | `Error` | | Payment form | `paymentForm` | object | | | Payment button name | `buttonPayLabel` | string | `Pay` | | Cardholder name text | `cardholderLabel` | string | `Cardholder` | | Cardholder name prompt text | `cardholderNote` | string | None | | Cardholder name placeholder | `cardholderPlaceholder` | string | `Full name` | | Card number | `cardNumberLabel` | string | `Card number` | | 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 | `Expiration date` | | Card expiration date prompt text | `expireDateNote` | string | `As stated on the card` | | Card expiration date placeholder | `expireDatePlaceholder` | string | `MM/YY` | | Recurring payment checkbox | `recurrentLabel` | string | `I agree to recurring payments` | | 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 | `By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}` | | Field validation error messages | `validationErrors` | object | | | Invalid card number | `INVALID_CARD_NUMBER` | string | `Invalid card number` | | Invalid CVV/CVC | `INVALID_CVV` | string | `CVV/CVC has 3 digits` | | Invalid card expiration date | `INVALID_EXPIRY_DATE` | string | `Invalid date` | | Required field value is missing | `IS_REQUIRED` | string | `Required field` | | Payment process page | `paymentProcessScreen` | object | | | Payment processing page text | `description` | string | `Just a moment` | | Payment process screen heading | `title` | string | `Payment processing...` | | 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 | ``If you haven`t been redirected automatically, use {{#link}}this link.{{/link}}`` | | Payment processing page header | `title` | string | `Payment processing...` | | 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 | ``You will be redirected to the issuer bank`s page in {{#strong}}{{countdown}} seconds.{{/strong}}`` | | Successful payment page | `successPaymentScreen` | object | | | Successful payment page header | `title` | string | `Payment success` | | Transaction data | `transactionData` | object | | | Transaction amount label | `amountLabel` | string | `Amount` | | Payment type data (card type and masked card number) label | `creditCardLabel` | string | `Card` | | Transaction ID label | `transactionIdLabel` | string | `Transaction ID` | | Unknown error message | `unknownError` | string | `Something went wrong...` | 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 {#endUserErrors} 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 Use the widget to store bank card data with Bank 131. **What the widget looks like** **Code example** ```html showLineNumbers Card number tokenization widget.
``` ### How to use the widget You embed the widget on your website. The user enters their card number, Bank 131 stores it in its system, and returns a payout hash to you. You can save this hash and use it for future payouts to the same account. This is secure. :::info You can find out information about the hash using the [`token/info`](/reference/methods#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 `Bank131CardTokenizer` 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 `Bank131CardTokenizer` class constructor: ```js showLineNumbers const cardTokenizer = new Bank131CardTokenizer('public token'); ``` Set the following event handler for the successful completion of the tokenization process: ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { // ... }; ``` #### Step 5. Display the widget Call the `render()` method: ```js showLineNumbers cardTokenizer.render(); ``` ### Widget API #### Constructor: `Bank131CardTokenizer` {#card_tokenizer} Widget class constructor: ```js showLineNumbers new Bank131CardTokenizer(publicToken[, options]) ``` | Parameter | Type | Description | |-----------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------| | `PublicToken` | string | Public token. The parameter is mandatory | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the widget will be inserted. The default value is: `
` | | `options.texts` | object | | | `options.texts.cardNumberLabel` | string | Label for the card number field. Default value: `Card number` | | `options.texts.submitButtonLabel` | string | Label for the card linking button. Default value: `Link the card` | #### Method: `cardTokenizer.render()` It displays the widget in the container defined by the `options.container` parameter: ```js showLineNumbers cardTokenizer.render(); ``` #### Event handler: `cardTokenizer.onReady` It is called when the widget is ready for work: ```js showLineNumbers cardTokenizer.onReady = function () { /* handler */ }; ``` #### Event handler: `cardTokenizer.onTokenizationStart` It is called at the start of the hashing process: ```js showLineNumbers cardTokenizer.onTokenizationStart = function () { /* handler */ }; ``` #### Event handler: `cardTokenizer.onTokenizationSuccess` It is called when the tokenization process finishes successfully: ```js showLineNumbers cardTokenizer.onTokenizationSuccess = function (cardToken) { /* handler */ }; ``` | Parameter | Type | Description | |-------------------------------------|--------|-------------------------------------------------------------------------------------------| | `cardToken` | object | | | `cardToken.info` | object | Additional card information | | `cardToken.info.card_network` | string | Payment system type. Possible values: `visa`, `mastercard`, `mir` | | `cardToken.info.card_type` | string | Card type. Additionally specifies the subbrand (`visa_electron`, `maestro`, `mirmaestro`) | | `cardToken.info.masked_card_number` | string | Masked card number value, e.g. `424242******4242` | | `cardToken.token` | string | Card number hash | #### Event handler: `cardTokenizer.onTokenizationFail` It is called when the tokenization process finishes unsuccessfully: ```js showLineNumbers cardTokenizer.onTokenizationFail = function (error) { /* handler */ }; ``` ### Widget customization #### Appearance To customize the widget's appearance, include your own stylesheet after the default styles. Input fields inside `iframe` cannot be modified. An example of adding custom styles: ```html showLineNumbers ``` An example of reassigning the color: ```css showLineNumbers /* custom-styles.css */ .bank131-Field__label { color: green; } ``` #### Texts You can change the standard texts using the `options.texts` parameter in the [`Bank131CardTokenizer`](#card_tokenizer) constructor. [How to make a payout using the widget or by token >](/payouts/payout-tokenized-card) --- ## 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 | The sender transfers funds in rubles, while the recipient receives them in the local currency (conversion is performed automatically). ## 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. The conversion rate is set by the provider and can vary at any time. --- - [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). ### 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 **Direct rate, from RUB to 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": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" } } }' ``` **Inverse rate, from UZS to RUB** ```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 **Direct rate, from RUB to TRY** ```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 } } } ``` **Inverse rate, from UZS to RUB** ```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 } } } ``` **Unsuccessful response example** ```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 **Transfer from a bank card to a bank card in Tajikistan** ```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" } } } }] }' ``` **Transfer from a bank card to IBAN in Turkey** ```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 **Transfer from a bank card to a bank card in Tajikistan** ```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 } }] } } ``` **Transfer from a bank card to IBAN in Turkey** ```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 } }] } } ``` **Unsuccessful response example** ```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" }, "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" } }] } }' ``` ### 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", "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" } }] } }' ``` ### 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", "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": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ### Sequence diagram ![Sequence diagram of a money transfer](/img/docs/transfers/money_transfer_new_en.png) ```plantuml @startuml autonumber participant Partner participant Bank_131 group Preliminary rate calculation Partner -> Bank_131: ""calculate"" activate Partner activate Bank_131 Bank_131 --> Partner: response deactivate Bank_131 end group Transfer start Partner -> Bank_131: ""session/multi/init"" activate Bank_131 Bank_131 --> Partner: response Bank_131 -> Bank_131: sender and recipient verified,\nexchange rate reserved Bank_131 -> Partner: ""ready_to_confirm"" end group Transfer confirmation Partner -> Bank_131: ""session/confirm"" Bank_131 --> Partner: response Bank_131 -> Partner: ""action_required"" deactivate Partner note over Partner Sender passes 3DS end note else #lightgrey Transfer cancellation Partner -> Bank_131: ""session/cancel"" activate Partner Bank_131 --> Partner: response Bank_131 -> Partner !!: ""payment_finished"" deactivate Partner end group Payout to recipient Bank_131 -> Bank_131: payout to the recipient's card activate Partner Bank_131 -> Partner: ""payment_finished"" deactivate Partner deactivate Bank_131 end @enduml ``` --- ## 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. :::info For payouts from the escrow account, you will need the `confirm_information` object returned in the `ready_to_confirm` webhook—make sure [the webhooks are enabled](/reference/webhooks). ::: ### 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 {#list_of_accounts} Accounts allowed for payouts from escrow accounts You can only send payouts to the accounts that begin with these digits: - 40817810 - 42301810 - 42302810 - 42303810 - 42304810 - 42305810 - 42306810 - 42307810 - 40802810 - 40701810 - 40502810 - 40702810 (for legal entities) ### 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. If you require an escrow mechanism (safe deal), it can be implemented using an escrow account. To enable it, please contact your personal manager at Bank 131. --- - [Payouts from an escrow account by account number](https://developer.131.ru/en/escrow-account/escrow-payout-accounts): Sending payments to legal entities and 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 {#payout_account} #### 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 **For individuals** ```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 '{ "session_id": "ps_2643", "payment_method": { "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" } }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` **For legal entities** ```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 '{ "session_id": "ps_2643", "payment_method": { "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" } }, "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": {} }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. ### Sequence diagram ![Payout scheme from an escrow account by account number](/img/docs/payouts/schema_escrow_payout_account_without_widget_en.png) ```plantuml @startuml PayoutNominalWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create/nominal"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout/nominal"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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 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 '{ "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": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "5536********8371" } } }, "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" }, "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" } } } }' ``` ### 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", "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" } } } }' ``` 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", "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" } } } }' ``` ### 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. ### Sequence diagram ![Payout scheme from an escrow account by card number](/img/docs/payouts/schema_escrow_payout_without_widget_en.png) ```plantuml @startuml PayoutNominalWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/multi/create/nominal"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/multi/start/payment/nominal"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) --- - [Parameters for payouts to Russian bank accounts](https://developer.131.ru/en/escrow-account/russian-account-parameters): Payouts to sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. **For residents** | 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` | **For non-residents** | 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 {#target} 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 **For residents** `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` **For non-residents** `{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. **With the widget or by token/hash** 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 | **By card number** 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 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) **With our 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 \ 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 } }' ``` #### 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 **To individuals** ```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 '{ "session_id": "ps_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` **To legal entities** ```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 '{ "session_id": "ps_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } }, "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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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": {} }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. **By token** #### 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 **To individuals** ```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 '{ "session_id": "ps_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` **To legal entities** ```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 '{ "session_id": "ps_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } }, "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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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": {} }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. #### Sequence diagram **With our widget** ![Payout scheme from an escrow account with our widget](/img/docs/payouts/schema_escrow_payout_widget_account_en.png) ```plantuml @startuml PayoutNominalWidgetAccount autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget Partner -> Bank_131: sends ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters the bank account details ... Partner -> Bank_131: sends ""session/create/nominal"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout/nominal"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **By token** ![Payout scheme from an escrow account by token](/img/docs/payouts/schema_escrow_payout_account_without_widget_en.png) ```plantuml @startuml PayoutNominalWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create/nominal"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout/nominal"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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 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) **With our 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 \ 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 } }' ``` #### 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 '{ "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": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "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" }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. **By token/hash** 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 **With a token received via the method** ```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_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": { "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "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" } }' ``` **With a hash from 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 '{ "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": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "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" } }' ``` **With a token for recurring payouts** ```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_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": { "type": "recurrent", "recurrent": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }, "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" }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. #### Sequence diagram **With our widget** ### Sequence diagram ![Payout scheme from an escrow account with our widget](/img/docs/payouts/schema_escrow_payout_widget_card_en.png) ```plantuml @startuml PayoutNominalWidgetCard autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget Partner -> Bank_131: sends ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters card details ... Partner -> Bank_131: sends ""session/multi/create/nominal"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/multi/start/payment/nominal"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **By token/hash** ### Sequence diagram ![Payout scheme from an escrow account by token](/img/docs/payouts/schema_escrow_payout_without_widget_en.png) ```plantuml @startuml PayoutNominalWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/multi/create/nominal"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/multi/start/payment/nominal"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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). **API v2** #### 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 **Successful response** ```json showLineNumbers { "status": "ok", "data": { "id": "7", "description": "request added to queue" } } ``` **Response with an error** ```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` | **API v1** #### 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 **Successful response** ```json showLineNumbers { "status": "ok", "data": { "id": "7", "description": "request added to queue" } } ``` **Response with an error** ```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 {#errors} 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. **API v2** #### 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 **Successful response** ```json showLineNumbers { "status": "ok", "data": { "id": "7", // check request ID "description": "valid" } } ``` **Processing request** ```json showLineNumbers { "status": "pending", "data": { "id": "7", "description": "Check in progress" } } ``` **Response with an error** Data already verified. ```json showLineNumbers { "status": "error", "error": { "code": "already_exists", "description": "Request with the same data already exists" }, "data": { "id": "7" } } ``` **API v1** #### 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 **Successful response** ```json showLineNumbers { "status": "ok", "data": { "id": "7", // check request ID "description": "valid" } } ``` **Processing request** Send another `check/{id}` request with the same data later. ```json showLineNumbers { "status": "pending", "data": { "id": "7", "description": "Check in progress" } } ``` **Response with an error** 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 {#statuses_error_codes} #### 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 **Invalid passport** ```json showLineNumbers { "status": "error", "error": { "code": "passport_validation_failure", "description": "По данным МДВ предоставленный паспорт признан недействительным" } } ``` **No passport data** ```json showLineNumbers { "status": "error", "error": { "code": "passport_validation_failure", "description": "В базе данных МВД отсутствуют сведения о предоставленном паспорте" } } ``` **INN and passport failed verification** ```json showLineNumbers { "status": "error", "error": { "code": "inn_validation_failure", "description": "По данным ФНС предоставленный паспорт не соответствует предоставленному ИНН" } } ``` Only employees of Bank 131 can add or remove beneficiaries of an escrow account in the Bank's system. --- ## 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. :::info For payouts from the settlement account, you will need the `confirm_information` object returned in the `ready_to_confirm` webhook—make sure [the webhooks are enabled](/reference/webhooks). ::: ### 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 {#list_of_accounts} Accounts allowed for payouts from settlement accounts You can only send payouts to the accounts that begin with these digits: - 40817810 - 42301810 - 42302810 - 42303810 - 42304810 - 42305810 - 42306810 - 42307810 - 40802810 - 40701810 - 40502810 - 40702810 (for legal entities) --- - [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 {#payout_account} #### 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 **For individuals** ```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_2643", "payment_method": { "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" } }, "amount_details": { "amount": 350000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` **For legal entities** ```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_2643", "payment_method": { "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" } }, "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": {} }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. ### Sequence diagram ![Payout scheme from a settlement account by account number](/img/docs/payouts/schema_settlement_payout_account_without_widget_en.png) ```plantuml @startuml PayoutRKOAccountWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create/rko"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout/rko"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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 '{ "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": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "5536********8371" } } }, "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" }, "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" } } } }' ``` ### 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", "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" } } } }' ``` 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", "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" } } } }' ``` ### 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. ### Sequence diagram ![Payout scheme from a settlement account by card number](/img/docs/payouts/schema_settlement_payout_without_widget_en.png) ```plantuml @startuml PayoutRKOWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/multi/create/rko"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/multi/start/payment/rko"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) --- - [Parameters for payouts to Russian bank accounts](https://developer.131.ru/en/settlement-account/russian-account-parameters): Payouts to sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. **For residents** | 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` | **For non-residents** | 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 | ### How to specify the payout purpose {#target} 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 **For residents** `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` **For non-residents** `{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. **With the widget or by token/hash** 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/objects#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 | **By card number** 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 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) **With our 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 \ 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 } }' ``` #### 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 **To individuals** ```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_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` **To legal entities** ```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_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } }, "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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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": {} }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. **By token** #### 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 **To individuals** ```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_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` **To legal entities** ```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_2643", "payment_method": { "type": "bank_account", "bank_account": { "ru": { "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } }, "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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "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": {} }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. #### Sequence diagram **With our widget** ![Payout scheme from a settlement account with our widget](/img/docs/payouts/schema_settlement_payout_widget_account_en.png) ```plantuml @startuml PayoutRKOWidgetAccount autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant ank_131_Widget as Bank_131_Widget Partner -> Bank_131: sends ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters the bank account details ... Partner -> Bank_131: sends ""session/create/rko"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout/rko"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **By token** ![Payout scheme from a settlement account by token](/img/docs/payouts/schema_settlement_payout_account_without_widget_en.png) ```plantuml @startuml PayoutRKOAccountWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/create/rko"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/start/payout/rko"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [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 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. **With our 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 \ 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 } }' ``` #### 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 '{ "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": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "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" }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. **By token/hash** 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 **With a token received via the method** ```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_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": { "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` **With a hash from 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 '{ "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": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` **With a token for recurring payouts** ```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_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": { "type": "recurrent", "recurrent": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }, "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" }, "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" } } } }' ``` #### 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", "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" } } } }' ``` 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", "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" } } } }' ``` #### 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. #### Sequence diagram **With our widget** ![Payout scheme from a settlement account with our widget](/img/docs/payouts/schema_settlement_payout_widget_card_en.png) ```plantuml @startuml PayoutRKOWidgetCard autonumber participant Partner as Partner participant Bank_131 as Bank_131 participant Bank_131_Widget as Bank_131_Widget Partner -> Bank_131: sends ""token"" Bank_131 --> Partner: 200 OK Partner -> Bank_131_Widget: initializes the widget ... The recipient enters card details ... Partner -> Bank_131: sends ""session/multi/create/rko"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/multi/start/payment/rko"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` **By token/hash** ![Payout scheme from a settlement account by token](/img/docs/payouts/schema_settlement_payout_without_widget_en.png) ```plantuml @startuml PayoutRKOWithoutWidget autonumber participant Partner as Partner participant Bank_131 as Bank_131 Partner -> Bank_131: sends ""session/multi/create/rko"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: sends ""session/multi/start/payment/rko"" Bank_131 -> Bank_131: starts the payout Bank_131 --> Partner: 200 OK Bank_131 -> Partner: sends ""ready_to_confirm"" with ""confirm_information"" Partner --> Bank_131: 200 OK Partner -> Partner: checks the details and saves ""confirm_information"" Partner -> Bank_131: sends ""session/confirm"" with ""confirm_information"" Bank_131 --> Partner: 200 OK Bank_131 -> Bank_131: performs the payout Bank_131 -> Partner: sends ""payment_finished"" Partner --> Bank_131: 200 OK @enduml ``` [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) --- ## 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 | | `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 | | `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 During request processing, the system validates the input data, ensures the [required headers](/reference/reference-format.mdx) are present, and confirms that the user has the appropriate rights to perform the 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` #### Deactivating a token A method for disabling a token for recurring payments. To do this, 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 anymore. > After the token is disabled, the token expiration setting `finished_at` may contain a date referring to the year 2000. Ignore it. #### Endpoint `/api/v1/recurrent/disable` #### Request parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|------------------------------------------------------------------------| | `recurrent` | + | object | [Token](/reference/reference-objects.mdx#recurrent) | Request example **cURL** ```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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }' ``` **PHP** ```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('9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48') ->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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "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` #### Canceling an operation A method for canceling a payout or a payment after receiving a `ready_to_confirm` or `ready_to_capture` webhook from Bank 131. **API v1** #### Endpoint `/api/v1/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### Endpoint `/api/v2/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/capture` #### Debiting amounts put on hold A method for debiting previously held funds after receiving a `ready_to_capture` webhook from Bank 131. You can debit the amount fully or partially. **API v1** #### 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 **cURL** ```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** ```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 **Successful response example** ```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": "mir", "last4": "2058" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` **API v2** #### 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 **cURL** ```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** ```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 **Successful response example** ```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": "mir", "last4": "2058" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/confirm` #### Confirming an operation A method for confirming a payout or a payment after receiving a `ready_to_confirm` or `ready_to_capture` webhook from Bank 131. The request must be sent within 4 hours of the operation being created; otherwise, a `confirm_timeout` error is returned. **API v1** #### Endpoint `/api/v1/session/confirm` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | | `confirm_information` | - (mandatory for operations with settlement and escrow accounts, as well as for money transfers) | object | [Transaction confirmation information](/reference/reference-objects.mdx#confirm_information) | Request example **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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 **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/create` #### Creating a payment session A method for creating a payment session. Returns `session_id`—the session identifier that Bank 131 uses to determine which session a request belongs to. This method is mandatory for payments via the widget, as `session_id` is required to generate a public token. The token links the card details entered by the user to a specific session. Without it, Bank 131 cannot determine which payment the entered details and webhooks relate to. If you [accept payments via FPS](/payments/payment-fps-qr), be sure to pass `faster_payment_system` in `payment_details`. > You can create a session and start a payout/payment at the same time using the `session/init` method. We do not recommend using this method. **API v1** #### 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` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [User'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 **cURL** ```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** ```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 **Successful response example** ```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" } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` **API v2** #### 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` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [User'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 **cURL** ```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** ```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 **Successful response example** ```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" } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment` #### Creating a session with a simultaneous payment A method for running a payment without creating a session separately. In this case, you pass all the data at once. The response contains the parameters of the created session with the payment information ([`acquiring_payments`/`payment_list`](/reference/objects#acquiring_payments)). **API v1** #### 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` | | `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 **cURL** ```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** ```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('https://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()->initPayment($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 **Successful response example** ```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" } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` **API v2** #### 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` | | `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 **cURL** ```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** ```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('https://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()->initPayment($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 **Successful response example** ```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" } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment/sync` > We do not recommend using this method. #### Creating a single-request payment A method for running a payment with a single request. Suitable if you do not use the widget. When using this method, webhooks are not sent. The payment result is returned in the response to this same request. [Learn more about single-request payments >](/payments/payment-pcidss-simple) **API v1** #### 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` | | `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 **cURL** ```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 **Successful response example** ```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" } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` **API v2** #### 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` | | `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 **cURL** ```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 **Successful response example** ```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" } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payout` #### Creating a session with a simultaneous payout A method for running a payout without creating a session separately. In this case, you pass all the data at once. The response contains the parameters of the created session and information about the payout ([`payments`/`payout_list`](/reference/objects#payments)). **API v1** #### 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` | | `participant_details` | - (mandatory for payouts to bank cards) | 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 **cURL** ```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": "Ivan Ivanovich Ivanov" } } }' ``` **PHP** ```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('Ivan Ivanovich Ivanov'); $request = RequestBuilderFactory::create() ->initPayoutSession() ->setCard(new BankCard('4242424242424242')) ->setAmount(1000, 'rub') ->setRecipient($participant) ->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 **Successful response example** ```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" }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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` | | `participant_details` | - (mandatory for payouts to bank cards) | 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 **cURL** ```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": "Ivan Ivanovich Ivanov" } } }' ``` **PHP** ```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('Ivan Ivanovich Ivanov'); $request = RequestBuilderFactory::create() ->initPayoutSession() ->setCard(new BankCard('4242424242424242')) ->setAmount(1000, 'rub') ->setRecipient($participant) ->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 **Successful response example** ```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" }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/refund` #### Creating a refund A method for returning money to the sender. You can return the full payment amount or part of it, while the fee is non-refundable. A refund cannot be canceled—before sending the request, make sure that it is really necessary. After the refund, Bank 131 will send you a [`payment_refunded`](/reference/webhooks#payment_refunded) webhook with the result. **API v1** #### Endpoint `/api/v1/session/refund` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Identifier of the session to refund | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). If not specified, the full payment amount is returned to the sender | | `metadata` | - | \* | Additional information | Request example **cURL** ```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** ```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. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples **Successful response example** ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.000000Z", "updated_at": "2025-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2025-05-27T02:03:00.000000Z", "finished_at": "2025-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "mir", "last4": "2058" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2025-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### Endpoint `/api/v2/session/refund` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Identifier of the session to refund | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). If not specified, the full payment amount is returned to the sender | | `metadata` | - | \* | Additional information | Request example **cURL** ```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** ```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. Options: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples **Successful response example** ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.000000Z", "updated_at": "2025-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2025-05-27T02:03:00.000000Z", "finished_at": "2025-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "mir", "last4": "2058" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2025-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/start/payment` #### Starting a payment A method for starting a payment within an existing session. In the request, you can pass the missing parameters or replace the ones that have already been passed. **API v1** #### 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) | | `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 **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` **API v2** #### 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) | | `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 **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` ### `session/start/payout` #### Starting a payout A method for starting a payout within an existing session. In the request, you can pass the missing parameters or replace the ones that have already been passed. **API v1** #### 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` | - (mandatory for payouts to bank cards) | 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", "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" } } }' ``` #### 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 **Successful response example** ```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" }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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` | - (mandatory for payouts to bank cards) | 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", "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" } } }' ``` #### 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 **Successful response example** ```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" }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `token` #### Getting a token to work with the widgets A method for getting a public token required to work with the widgets. It is valid for 24 hours and is intended for a single operation. In the request, specify the type of widget for which you need to get the token. #### 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) | | `acquiring_widget` | - | object | [Data required by the payment form widget](/reference/reference-objects.mdx#acquiring_widget) | | `sber_pay_widget` | - | object | [Data required by the SberPay widget](/reference/reference-objects.mdx#sber_pay_widget) | An example of a token request for a payout that obtains card details via the widget **cURL** ```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 } }' ``` **PHP** ```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() ->setAcquiringWidget( 'test_ps_id', 'https://success.url', 'https://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" } }' ``` An example of how to get a token to perform a payment via SberPay ```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 '{ "sber_pay_widget": { "session_id": "ps_77872830", "phone": "79680000000", "return_url": "https://131.ru" } }' ``` #### 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 **Successful response example** ```json showLineNumbers { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539" } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "acquiring_widget.session_id.not_unique", "code": "invalid_request" } } ``` ### `tokenize` #### Tokenizing a bank account number A method for tokenizing a bank account (for a 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 **Successful response example** ```json showLineNumbers { "status": "ok", "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "data": { "masked_account": "40817***9535" } } ``` **Unsuccessful response example** ```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 **Successful response example** ```json showLineNumbers { "status": "ok", "data": { "number": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "info": { "masked_card_number": "424242******4242", "card_network": "visa", "card_type": "visa" } } } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Information ### `fps/banks` {#banks_fps} #### Getting a list pf FPS member banks A method for getting a list of banks with their names and identifiers for sending payouts via the Faster Payments System. #### Endpoint `/api/v1/fps/banks` Request example **cURL** ```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** ```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` {#fps_verification} #### Verifying an FPS recipient A method for checking 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). **API v1** #### 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 **Successful response example** ```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": "Иванович" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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 **Successful response example** ```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": "Иванович" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `report/account_balance` #### Checking the balance A method for getting your settlement or escrow account 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 **Successful response example** ```json showLineNumbers { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { "current_balance": 20900 } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "code": "Error code", "description": "Error description" } } ``` ### `report/account_statement` #### Getting a bank statement A method for getting bank statements for your settlement or escrow account opened in rubles for a day. #### 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 **Invalid dates** `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 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` #### Getting session information A method for obtaining full information about the payment session. For example, you can check the payout status or find out whether the held amount can be debited. **API v1** #### Endpoint `/api/v1/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### Endpoint `/api/v2/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example **cURL** ```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** ```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 **Successful response example** ```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" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `token/info` {#token_info} #### Getting token information A method for getting information about a token: both about the linked payment method and about its technical parameters. With this method you can get the following information: - for a card – masked card number and payment system type - for an account – masked account number - for the token itself – token type, creation date and time, expiration date, active/inactive status at the moment of inquiry #### 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 **Card number hash** 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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } } }' ``` **Public 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" } }' ``` **Token for recurring payments or payouts** 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": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48" } }' ``` **Bank account 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": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c" } }' ``` #### 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 **Card information via hash** ```json showLineNumbers { "status": "ok", "info": { "number_hash": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "brand": "visa", "last4": "4242", "type": "card" } } ``` **Information about a public token** ```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" } } ``` **Information about a token for recurring payments or payouts** ```json showLineNumbers { "status": "ok", "info": { "token": "9a1c4e7f2b8d5036af61c9e0d4b72f8a3c5e190d6f24b8a7c0e3d5f19b6a2c48", "created_at": "2021-03-17T14:19:05+03:00", "finished_at": "2021-04-17T14:19:05+03:00", "is_active": true, "type": "recurrent_token" } } ``` **Information about a bank account 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` #### Checking the balance A method for getting the current balance of your collateral account. Use it to make sure there is enough money for payouts and refunds. If the amount is insufficient, top up the account. :::note You can find your acquiring balance information in your online banking service account in the **Statements** section. ::: #### Endpoint `/api/v1/wallet/balance` #### Request parameters | Name | Mandatory | Type | Description | | ----------------- | --------- | ------ | ---------------------------- | | `request_datetime` | + | string | Timestamp of the request in ISO 8601 | Request example **cURL** ```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** ```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 **Successful response example** ```json showLineNumbers { "status": "ok", "wallets": [{ "id": "131", "amount_details": { "amount": 13100, "currency": "rub" } }] } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Escrow account ### `session/create/nominal` #### Creating a payment session A method for creating a payment session for a payout to a bank account. It returns `session_id`—a session identifier used by Bank 131 to determine the session associated with a request. Use this method if you get the bank account details for a payout through a widget and send the payout as a separate request within the created session. > You can create a session and start a payout at the same time using the `session/init/payout/nominal` method. We do not recommend this approach. **API v1** #### 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) | | `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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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) | | `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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/nominal` {#payout-nominal} #### Creating a session with a simultaneous payout to a bank account A method for making a payout to a bank account, including via [FPS](/payouts/payout-fps-phone#payout-nominal), without creating a session separately. In this case, you pass all the data at once. **API v1** #### 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) | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples **Payout to an individual's account** ```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": { "system_type": "ru", // for FPS payouts, use the faster_payment_system object "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" } } }' ``` **Payout to a legal entity's account** ```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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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) | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples **Payout to an individual's account** ```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": { "system_type": "ru", // for FPS payouts, use the faster_payment_system object "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" } } }' ``` **Payout to a legal entity's account** ```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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/multi/create/nominal` #### Creating a payment session A method for creating a payment session for a payout to a card. It returns `session_id`—a session identifier used by Bank 131 to determine the session associated with a request. Use this method if you get the card details for a payout through a widget and send the payout as a separate request within the created session. > You can create a session and start a payout at the same time using the `session/multi/init/payment/nominal` method. We do not recommend this approach. **API v1** #### 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.) | | `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": "mir", "bank_card": { "number": "2200774546102058" } } }, "participant_details": { "sender": { "full_name": "Sender's details", "beneficiary_id": "1987654321" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "1234567890", "reference": "1234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "lucky" } }' ``` #### 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 **Successful response example** ```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": "mir", "last4": "2058" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Sender's details", "beneficiary_id": "1987654321" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "1234567890", "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": "220077******2058" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "participant_details": { "sender": { "full_name": "Sender's details", "beneficiary_id": "1987654321" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "1234567890", "reference": "1234" } } } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` **API v2** #### Endpoint `/api/v2/session/multi/create/nominal` #### Request parameters | Name | + | 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.) | | `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": "mir", "participant_details": { "sender": { "full_name": "Sender's details", "beneficiary_id": "1987654321" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "1234567890", "reference": "1234" } }, "sender": { "full_name": "Sender's details", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "lucky" } }' ``` #### 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 **Successful response example** ```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": "mir", "last4": "2058" } }, "amount_details": { "amount": 30000, "participant_details": { "sender": { "full_name": "Sender's details", "beneficiary_id": "1987654321" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "1234567890", "reference": "1234" } } "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": "220077******2058" } } }, "participant_details": { "sender": { "full_name": "Sender's details", "beneficiary_id": "1987654321" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "1234567890", "reference": "1234" } } "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` **Unsuccessful response example** ```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 A method for making a payout to a bank card without creating a session separately. In this case, you pass all the data at once. **API v1** #### 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.) | | `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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` **API v2** #### 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.) | | `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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/start/payment/nominal` #### Starting a payout to a bank card A method for starting a payout within an already created session. In the request, you can pass the missing parameters or replace the ones already passed. **API v1** #### 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.) | | `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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` **API v2** #### 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.) | | `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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/start/payout/nominal` #### Starting a payout to a bank account A method for starting a payout to a bank account, including via [FPS](/payouts/payout-fps-phone#payout-nominal), within an already created session. In the request, you can pass the missing parameters or replace the ones already passed. **API v1** #### 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) | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples **Payout to an individual's account** ```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", // for FPS payouts, use the faster_payment_system object "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" } } }' ``` **Payout to a legal entity's account** ```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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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) | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples **Payout to an individual's account** ```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", // for FPS payouts, use the faster_payment_system object "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" } } }' ``` **Payout to a legal entity's account** ```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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Settlement account ### `session/create/rko` #### Creating a payment session A method for creating a payment session for a payout to a bank account.It returns `session_id`—a session identifier used by Bank 131 to determine the session associated with a request. Use this method if you get the bank account details for a payout through a widget and send the payout as a separate request within the created session. > You can create a session and start a payout at the same time using the [`session/init/payout/rko`](/reference/methods#payout-rko) method. We do not recommend this approach. **API v1** #### 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) | | `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 **Successful response example** ```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" }, "participant_details": { "sender": { "account": "40702810900000000011" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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) | | `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 **Successful response example** ```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" }, "participant_details": { "sender": { "account": "40702810900000000011" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/rko` {#payout-rko} #### Creating a session with a simultaneous payout to a bank account A method for making payouts from a settlement account to a bank account, including via [FPS](/payouts/payout-fps-phone#payout-rko), without creating a session separately. In this case, you pass all the data at once. **API v1** #### 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) | | `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 **Successful response example** ```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" }, "participant_details": { "sender": { "account": "40702810900000000011" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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) | | `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 **Successful response example** ```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" }, "participant_details": { "sender": { "account": "40702810900000000011" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/multi/create/rko` #### Creating a payment session A method for creating a payment session for a payout to a card. It returns `session_id`—a session identifier used by Bank 131 to determine the session associated with a request. Use this method if you get the card details for a payout through a widget and send the payout as a separate request within the created session. > You can create a session and start a payout at the same time using the `session/multi/init/payment/rko` method. We do not recommend this approach. **API v1** #### 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.) | | `participant_details` | - | 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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` **API v2** #### 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.) | | `participant_details` | - | 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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```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 A method for making a payout to a bank card without creating a session separately. In this case, you pass all the data at once. **API v1** #### 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` | | `participant_details` | + | 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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` **API v2** #### 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` | | `participant_details` | + | 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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/start/payment/rko` #### Starting a payout to a bank card A method for starting a payout within an already created session. In the request, you can pass the missing parameters or replace the ones already passed. **API v1** #### 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` | | `participant_details` | + | 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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` **API v2** #### 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` | | `participant_details` | + | 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 **Successful response example** ```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" } } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/start/payout/rko` #### Starting a payout to a bank account A method for starting a payout to a bank account within an existing session. In the request, you can pass the missing parameters or replace the ones already passed. **API v1** #### 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) | | `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 **Successful response example** ```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" }, "participant_details": { "sender": { "account": "40702810900000000011" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` **API v2** #### 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) | | `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 **Successful response example** ```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" }, "participant_details": { "sender": { "account": "40702810900000000011" } }, "metadata": "good" }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Money transfers ### `calculate` #### Calculating currency conversion for a money transfer A method for calculating currency conversion for a money transfer. The currency exchange rate can be calculated as follows: - 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 **Direct rate, from RUB to 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": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" } } }' ``` **Inverse rate, from UZS to RUB** ```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 **Direct rate, from RUB to TRY** ```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 } } } ``` **Inverse rate, from UZS to RUB** ```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 } } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ### `session/multi/init` {#session_multi_init} #### Creating a multisession with a simultaneous cross-border transfer start A method for creating a multisession and starting a cross-border transfer—debiting funds from the sender and paying them out to the recipient without creating a session separately. #### 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 **Transfer from a bank card to a bank card in Tajikistan** ```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" } } } }] }' ``` **Transfer from a bank card to IBAN in Turkey** ```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 **Transfer from a bank card to a bank card in Tajikistan** ```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 } }] } } ``` **Transfer from a bank card to IBAN in Turkey** ```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 } }] } } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ## Other methods ### `sberpay/push` #### Verifying the payment status A method for requesting the SberPay payment status. #### 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://demo.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 **Successful response example** ```json showLineNumbers { "status": "ok" } ``` **Unsuccessful response example** ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` --- - [Objects](https://developer.131.ru/en/reference/objects): List of objects ## `accept_code` {#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` {#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` {#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) | It is not possible to get a list of transactions filtered by date range, amount, or status. ## `acquiring_payments` = `payment_list` {#acquiring_payments} >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 | | `payment_options` | - | object | [Payment parameters](/reference/objects#payment_options) | | `error` | - | object | [Error description](/reference/reference-objects.mdx#error) | #### Payment statuses (`status`) {#payment_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. View status diagram ```mermaid stateDiagram-v2 [*] --> in_progress: session/create + session/start/payment (or session/init/payment) in_progress --> pending: ready_to_confirm webhook → action_required webhook → ready_to_capture webhook pending --> in_progress in_progress --> succeeded: session/capture in_progress --> failed: session/cancel in_progress --> failed: unsuccessful payment succeeded --> [*] failed --> [*] ``` ## `acquiring_widget` {#acquiring_widget} Settings for the payment 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` {#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} 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_details} Amount object. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount in minor currency units. For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Example: `rub` | ## `amounts` {#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) {#amounts_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` {#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` {#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_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` {#bankcard} 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` {#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` {#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` {#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` {#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` {#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) {#contactsObject} 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} 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) {#customer} 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) {#nominal_payment_customer} 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` {#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` {#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) {#data} 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) {#tokenize_data} 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` {#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 | ## `encrypted_card` {#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} Error description object. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------------- | | `code` | - | string | Error code | | `description` | - | string | Error description | [View error codes ](/reference/reference-errors.mdx) ## `exchanges` {#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` {#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 (15 to 140 characters) | | `subscription_service_info` | - | object | [Subscription details](/reference/objects#subscription_service_info) | ## `faster_payment_system_verification` {#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` {#fee} Information on the applicable fee. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `merchant_fee` | + | object | [Fee amount and currency](/reference/objects#merchant_fee) | ## `iban` {#iban} Recipient's IBAN for a money transfer. | Name | Mandatory | Type | Description | |----------|----------------|--------|--------------------------------| | `account` | + | string | IBAN of a money transfer recipient | ## `identity_document` {#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_ru_info} 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) {#card_token_info} 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` (public token) {#public_token_info} 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) {#info_recurrent} 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) {#tokenize_info} 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` {#inform} Payment option data. | Name | Mandatory | Type | Description | |------|-----------|--------|---------------------------------------------------------------------| | `qr` | - | object | [QR code for payments via FPS](/reference/reference-objects.mdx#qr) | ## `internal_transfer` {#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` {#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) | ## `merchant_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` | ## `method` {#method} Method details. | Name | Mandatory | Type | Description | |-------------------|-----------|--------|------------------------------------------------------------------------| | `name` | + | string | Method name (`account_statement`) | | `account_statement` | + | object | [Statement details](/reference/reference-objects.mdx#account_statement) | | ## `number` {#number} Token and tokenized card details. | Name | Required | Type | Description | |-------|----------|--------|-----------------------------------------------------| | `token` | + | string | Token | | `info` | + | object | [Card information](/reference/objects#tokenize_info) | ## `participant_details` {#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` {#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` {#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` {#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` {#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` {#payment_method} >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` {#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` {#payments} >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) | | `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`) {#payout_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. View status diagram ```mermaid stateDiagram-v2 direction LR [*] --> in_progress: session/create + session/start/payout (or session/init/payout) in_progress --> pending: ready_to_confirm webhook pending --> in_progress: session/confirm in_progress --> succeeded: successful payout in_progress --> failed: unsuccessful payout / session/cancel succeeded --> [*] failed --> [*] ``` ## `period` {#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` {#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` {#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` | ## `public_token` {#public_token} Information about a public token. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `qr` {#qr} QR code for payments via FPS. | Name | Mandatory | Type | Description | | ------- | --------- | ------ | --------------- | | `content` | + | string | Link to QR code | | `img` | + | string | QR code body | ## `rate` {#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) | ## `recipient` (recipient of a payout from an escrow account) {#nominal_payment_recipient} 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) {#participant_details_recipient} 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) | | `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) {#recurrent} 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) {#recurrent_token_info} 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` {#recurrent_token} Token for recurring payments or payouts. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `redirect` {#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` {#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 View status diagram ```mermaid stateDiagram-v2 [*] --> in_progress: session/refund in_progress --> accepted: successful refund in_progress --> declined: refund declined by the bank in_progress --> error: unsuccessful refund accepted --> [*] declined --> [*] error --> [*] ``` ## `resend_sms` {#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` {#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} SberPay payment system transaction details. | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------| | `phone` | - | string | Phone number to send PUSH or SMS to. Format: `7**********` | | `channel` | + | ENUM | Payment acceptance method via SberPay: `app`, `mobile_web`, `web`—via channel, `widget`—via our widget | ## `sber_pay_widget` {#sber_pay_widget} SberPay widget settings. | Name | Mandatory | Type | Description | | ------------ | --------- | ------ | ----------------------------------------------------------- | | `session_id` | + | string | Payment session ID for which the payment is made | | `phone` | - | string | Payer's phone number for authorization | | `return_url` | - | string | URL to return the payer after payment | ## `sender` (escrow payer details) {#nominal_payment_sender} 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) {#participant_details_sender} 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 or settlement account) | string | Sender's escrow or settlement 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 | ## `session` {#payment_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. View status diagram ```mermaid stateDiagram-v2 [*] --> created: session/create created --> in_progress: session/start* in_progress --> accepted: successful completion in_progress --> cancelled: session/cancel in_progress --> error: unexpected error note right of error: not a final status, please contact Bank 131's support error --> accepted error --> cancelled accepted --> [*] cancelled --> [*] ``` #### 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` {#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` {#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_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` {#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` {#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` {#tax-period} - 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` {#tax-reason} - `ТП` – 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` {#tax-doc} - 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` {#tax-date} - 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` {#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` {#tokenized_card} A card token. | Name | Required | Type | Description | |-------|----------|--------|-------------| | `token` | + | string | Token | ## `total_balance` {#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` {#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_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` {#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` {#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` {#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` {#transfer_from_bank_account} Information on a transfer from a settlement account. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------- | | `description` | + | string | Description | ## `transfer_from_nominal_account` {#transfer_from_nominal_account} Information on a transfer from an escrow account. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------- | | `description` | + | string | Description | ## `wallet` {#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` {#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} 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) | Time in API responses is provided in UTC. --- - [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 the webhooks are disabled, you will need to send a [session/status](/reference/methods#sessionstatus) request each time to understand the 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. If the option is enabled, you will receive all enabled webhooks (selective webhook delivery cannot be set up). IP addresses our webhooks arrive from: `84.201.171.246` and `84.252.136.174`. #### What to send in response {#resp} 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 or no response at all, it will resend the webhook repeatedly at increasing intervals. Here is how it works: * The interval between resends increases progressively, but never exceeds 15 minutes. * After 30 minutes, Bank 131 stops sending the webhook. #### How to process webhooks with the SDK To handle webhooks in PHP, use the [PHP SDK](https://github.com/bank131/php-sdk#обработка-веб-хуков) library. The `handleWebHook` method automatically verifies the signature and converts the JSON into a `$hook` object containing the webhook type (`getType()`) and session data (`getSession()`). :::warning[IMPORTANT!] The set of fields in the webhook may expand over time depending on the payment methods used. Make sure it does not break your service. ::: The Bank's testing environment does not provide any webhook simulator. The Dashboard does not support logging webhooks or sending them manually. WebSocket and Server-Sent Events are not supported for real-time notifications—only HTTP webhooks are used. ### `action_required` #### The Bank is waiting for additional actions from you or your users 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 waiting time for an action depends on the transaction type and current settings. For example, the waiting time for 3DS confirmation for card payments is 20 minutes, while the QR code lifetime for payments via FPS can vary from 5 to 60 minutes. If the action is not performed within the set time, the operation is automatically completed with the `cancelled` status. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `action_required` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example **API v1** ```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@gmail.com" }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { // content depends on the payment method and provider "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" } } }, "payment_options": { "recurrent": false }, "metadata": "good" }] } }' ``` **API v2** ```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@gmail.com" }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { // content depends on the payment method and provider "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" } } }, "payment_options": { "recurrent": false }, "metadata": "good" }] } }' ``` ### `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 non-speedy payouts > This webhook is disabled by default. To start receiving `confirmation_payout` webhooks, contact your 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. 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. 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 when it completes 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 receive the `succeeded` status in this webhook, it means that the payout has been completed successfully. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | + | string | Webhook type: `payment_finished` | | `session` | + | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Examples **API v1** **Successful payout** ```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", "payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "payment_method": { // content depends on the payment method "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }], "actions": { "confirm": "2018-05-27T02:03:00.000000Z" } } }' ``` **Unsuccessful payout** ```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_1234", "status": "cancelled", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "failed", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "payment_method": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": { "parent_session_id": "ps_1234" }, "error": { "description": "Operation was declined", "code": "declined_by_issuer_bank" } }], "error": { "description": "Session cancelled", "code": "session_cancelled" }, "actions": { "confirm": "2022-03-01T11:57:31.895773Z", "capture": "2022-03-01T11:57:31.895773Z" } } }' ``` **Successful payment** ```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": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "recurrent": { // passed for recurring payments "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "created_at": "2024-08-08T10:10:27+03:00", "finished_at": "2034-08-08T10:10:27+03:00", "is_active": true, "type": "recurrent_token" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "payment_options": { "recurrent": false } }], "actions": { "confirm": "2018-05-27T02:03:00.000000Z", "capture": "2018-05-27T02:03:00.000000Z" } } }' ``` **Unsuccessful payment** ```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_1234", "status": "cancelled", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2018", "status": "failed", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": { "parent_session_id": "ps_3435347785" }, "error": { "description": "QR expired", "code": "qr_expired" }, "payment_options": { "recurrent": false } }], "error": { "description": "Session cancelled", "code": "session_cancelled" }, "actions": { "confirm": "2022-03-01T11:57:31.895773Z", "capture": "2022-03-01T11:57:31.895773Z" } } }' ``` **API v2** **Successful payout** ```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", "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "payout_details": { // content depends on the payment method "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }], "actions": { "confirm": "2018-05-27T02:03:00.000000Z" } } }' ``` **Unsuccessful payout** ```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_1234", "status": "cancelled", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "failed", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "payout_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": { "parent_session_id": "ps_1234" }, "error": { "description": "Operation was declined", "code": "declined_by_issuer_bank" } }], "error": { "description": "Session cancelled", "code": "session_cancelled" }, "actions": { "confirm": "2022-03-01T11:57:31.895773Z", "capture": "2022-03-01T11:57:31.895773Z" } } }' ``` **Successful payment** ```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", "payment_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "recurrent": { // passed for recurring payments "token": "d47b2f90a6c1e8350f9a4d7c2e6b183fa5c0d9e472b6f8a1c3e5d7092b4f6a8c", "created_at": "2024-08-08T10:10:27+03:00", "finished_at": "2034-08-08T10:10:27+03:00", "is_active": true, "type": "recurrent_token" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "payment_options": { "recurrent": false } }], "actions": { "confirm": "2018-05-27T02:03:00.000000Z", "capture": "2018-05-27T02:03:00.000000Z" } } }' ``` **Unsuccessful payment** ```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_1234", "status": "cancelled", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2018", "status": "failed", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": { "parent_session_id": "ps_1234" }, "error": { "description": "QR expired", "code": "qr_expired" }, "payment_options": { "recurrent": false } }], "error": { "description": "Session cancelled", "code": "session_cancelled" }, "actions": { "confirm": "2022-03-01T11:57:31.895773Z", "capture": "2022-03-01T11:57:31.895773Z" } } }' ``` ### `payment_refunded` #### Bank 131 informs you of the result of a refund Bank 131 sends you this webhook after a refund is performed. The notification parameters contain information about the payment session, which includes 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 payout 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 **API v1** ```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": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057862" }, "payment_options": { "recurrent": false }, "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" }, "metadata": { "internal_refund_id": "rf_123" }, "amounts": { // commission is not refunded "fee": { "merchant_fee": { "amount": 0, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }], "actions": { "confirm": "2018-05-27T02:03:00.000000Z", "capture": "2018-05-27T02:03:00.000000Z" } } }' ``` **API v2** ```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", "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": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "payment_options": { "recurrent": false }, "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" }, "metadata": { "internal_refund_id": "rf_123" }, "amounts": { // commission is not refunded "fee": { "merchant_fee": { "amount": 0, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }], "actions": { "confirm": "2018-05-27T02:03:00.000000Z", "capture": "2018-05-27T02:03:00.000000Z" } } }' ``` ### `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. The webhook means that the amount has been successfully put on hold, and the Bank is waiting for your 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 **API v1** ```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", "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": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "payment_options": { "recurrent": false }, "metadata": "good" }] } }' ``` **API v2** ```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:07:00.000000Z", "next_action": "capture", "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "payment_options": { "recurrent": false }, "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)) request to the Bank. If something is wrong, cancel the operation by sending a ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) request. >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 `cancelled` status. You can set up automatic confirmation of the payment session—in this case, `ready_to_confirm` will not be sent. To configure the automatic confirmation, contact your Bank 131 manager. :::info This webhook is mandatory when the operation requires the [`confirm_information`](/reference/reference-objects.mdx#confirm_information) object: for payouts from a settlement or escrow account, and for money transfers. ::: #### 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 a settlement or escrow account, and money transfers) | object | [Information for confirming the transaction](/reference/reference-objects.mdx#confirm_information) | Examples **API v1** **Payout** ```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": { // content depends on the payment method "type": "card", "card": { "brand": "mir", "last4": "4940", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ // for payouts to an escrow or settlement account "id": "pm_6933973", "status": "pending", "created_at": "2025-09-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { // content depends on the payment method "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer in accordance with the offer", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "participant_details": { // for payouts to an escrow or settlement account "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, "confirm_information": { // for payouts from an escrow or settlement account "transfer_details": { "payment_method": { // content depends on the 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 in accordance with the offer", "amount": { "amount": 293400, "currency": "RUB" } } } }' ``` **Payment** ```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", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "123456789012", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "payment_options": { "recurrent": false }, "metadata": "good" }] } }' ``` **API v2** **Payout** ```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", "payout_list": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-09-14T09:32:20.100149Z", "customer": { "reference": "123456789012" }, "payout_details": { // content depends on the payment method "type": "card", "card": { "brand": "mir", "last4": "4940", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "payment_list": [{ // for payouts from an escrow or settlement account "id": "pm_6933973", "status": "pending", "created_at": "2025-09-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { // content depends on the payment method "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer in accordance with the offer", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "participant_details": { // for payouts from an escrow or settlement account "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, "confirm_information": { // for payouts from an escrow or settlement account "transfer_details": { "payment_method": { // content depends on the payment method "type": "card", "card": { "brand": "mir", "last4": "4940", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "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 in accordance with the offer", "amount": { "amount": 293400, "currency": "RUB" } } } }' ``` **Payment** ```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", "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "123456789012", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { // content depends on the payment method "type": "card", "card": { "last4": "4940", "brand": "mir", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "payment_options": { "recurrent": false }, "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 {#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 {#detalization} 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**: FPS, bank card, SberPay, T-Pay, YooMoney * **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 {#searching} 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 {#AI} 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 results. 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 precise results, 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. Stay tuned for updates. API integration with the Dashboard is not supported. --- - [User actions](https://developer.131.ru/en/dashboard/user-actions): How to add, edit, and delete users Each user in the Dashboard has one or more roles. A role defines which sections and actions are available to the user. Three roles are available: **Admin**, **Manager**, **Support**. - **Admin**—manages users and has access to all sections. - **Manager**—works with transactions, reports, balances, and commissions but cannot manage users. - **Support**—designed for partner support—сan view transactions, export reports and confirmations, but cannot see balances or commissions and cannot manage users. :::info[] Only users with the **Admin** role can manage users. If you do not see the **Users** section in the menu, you have a different role. The **Admin** role can be assigned to only one user. You cannot assign another administrator through the Dashboard interface. If you need to transfer the role to another employee, contact support. ::: Administrators can do the following actions with other users: - [add](#adding) - [edit](#editing) - [block and delete](#block_delete) - [recover access](#access-recovery) - [re-invite](#reinvite) - [reset password](#password-reset) To start managing users, select the **Users** section on the left panel. On the page that opens, you will see two tabs: **Users** and **Roles and permissions**. The **Users** tab displays the list of all users and their information: - total number of users - first and last name - user status - **Active**—the user has accepted the invitation and can work in the Dashboard - **Invited**—invited user who has not yet accepted the invitation - **Deactivated**—the user's access is blocked - user role: **Manager**, **Support** - user email address used during registration - partner company the user has access to To find a user by first name, last name, or email, use the search bar above the table. The **Roles and permissions** tab shows actions available to each role. For example, **Manager** can view balances and commissions, while **Support** cannot. Both roles allow viewing transactions and exporting reports. ## Adding a user {#adding} To add a user, follow these steps: 1. Click the **Add** button above the users table. 2. In the window that opens, enter the new user's first and last name, select one or more roles, specify their email for sending the invitation, and select partners they will have access to. 3. Click **Add** . The user will appear in the table with the **Invited** status. When the user accepts the invitation, the status will change to **Active**. ## Editing a user {#editing} To edit a user, follow these steps: 1. Click the user in the table. 2. In the window that opens, change the necessary information: first name, last name, role, partner. The email cannot be changed. 3. Click **Save**. The user card data will be updated. ## Blocking and deleting a user {#block_delete} You can block or delete a user in three ways: - Select one or more users by checking the checkbox next to their name in the table. Then click **Block** or **Delete** on the panel that appears. - Click the three dots in the user row in the table and select **Block** or **Delete**. - Open the user card, click **Actions**, and select **Block** or **Delete**. | Action | What happens | Can be restored | |--------|--------------|-----------------| | Block | The user remains in the table with the **Deactivated** status, access is blocked | Yes | | Delete | The user is removed from the table, access is revoked | No | ## Access recovery {#access-recovery} This action is only available to users in the **Deactivated** status. It restores the user's access. The user status in the table changes from **Deactivated** to **Active**. To restore a user's access, follow these steps: 1. Click the three dots in the user row in the table. 2. In the menu that opens, select **Restore**. 3. A confirmation window will open. Click the **Restore** button. ## Re-inviting a user {#reinvite} This action is only available to users in the **Invited** status. If you invited a user but the email was lost or needs to be sent to a different address, you can resend the invitation. Follow these steps: 1. Click the three dots in the user row in the table. 2. In the menu that opens, select **Re-invite**. 3. A confirmation window will open. Click the **Send** button. The user will receive a new invitation email at the specified address. ## Password reset {#password-reset} This action is only available to users in the **Active** or **Invited** status. If a user forgot their password and cannot log in to the Dashboard, you can reset their password. There are two ways: - Open the user card, click **Actions** at the top, and select **Reset password**. - Click the three dots in the user row in the table and select **Reset password**. A confirmation window will open. Click the **Reset** button. The user will receive an email with a temporary password at the specified address. After clicking the link in the email, they will be asked to set a permanent password. --- - [Payout accounts](https://developer.131.ru/en/dashboard/payout-accounts): How to monitor balances and get account statements In the Dashboard, you can view payout balances and statements for these accounts. :::info[] A payout balance is an amount that you can only spend on payouts to partners, clients, and contractors. To top up the payout account balance, please contact your personal manager at the Bank. ::: Only the settlement account is used for payouts via FPS. Payouts to accounts, cards, and wallets are possible from the settlement or collateral accounts. Learn more about [payouts](/payouts/payouts-intro). You can use a single account for all payout types or create a dedicated account for each type. To view payout accounts, select the **Balances** section on the left panel. On the page that opens, you will see a carousel displaying all your payout accounts. When an account is selected, a statement for that account appears below. The statement has three columns: date, daily change, and end-of-day balance. By default, data for all time is shown, but you can click the dates in the upper right corner of the table and select the required period or specify your own. --- ## 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** [/assets/payment_register_bank131.csv](/assets/payment_register_bank131.csv) **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 ``` The partner receives daily reports (for payments and payouts) that show fee. It is not possible to get an XML/Excel fee report for an arbitrary period yet. --- - [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** [/assets/payout_register_bank131.xlsx](/assets/payout_register_bank131.xlsx) **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 ``` The partner receives daily reports (for payments and payouts) that show fee. It is not possible to get an XML/Excel fee report for an arbitrary period yet. --- ## 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 '{ "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) | Successful response example ```json showLineNumbers { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { "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 '{ "date_from": "2023-06-01", "date_to": "2023-06-01", "account_number": "40702810600200000014" }' ``` ### 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" } } ``` ---