# 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 The table below shows who and which way can receive payouts. ###### Residents of the Russian Federation | Recipient | Bank account | Bank card | YooMoney wallet |       FPS       | |-----------------------|:------------------:|:---------------------:|:----------------:|:----------------------------------------------------------------:| | Individuals | + | + | + | + | | Sole proprietors | + | + | - | + | | Self-employed persons | + | + | + | + | | Legal entities | + (from an escrow/settlement account only) | + (no guarantee) | - | - | ###### Non-residents of the Russian Federation | Recipient | Bank account | Bank card | YooMoney wallet |       FPS       | |-----------------------|:------------------:|:---------------------:|:----------------:|:----------------------------------------------------------------:| | Individuals | + | + | + | + | | Sole proprietors | + | + | - | + | | Self-employed persons | + | + | + | + | | Legal entities | + | + (no guarantee) | - | - | [Learn more about payouts >](/payouts/payouts-intro) ### Payment processing With our API you can do the following: - accepts payments from individuals paying from their bank cards - process delayed capture payments - accept recurring payments [Learn more about accepting payments >](/payments/payment-intro) ### VAT payment Foreign companies providing electronic services to users in Russia can pay the VAT (the Google tax). [Learn more about VAT payments >](/payouts/payout-taxes) Bulk transactions are not supported. Each request processes a single transaction to a single recipient. 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. export const FlowBox = ({title, note, strong, children}) => ( {title} {note && {note}} {children} ); export const FlowArrow = () => ( ↓ ); export const FlowMethod = ({to, children}) => ( {children} ); ### Account selection guide First open the account, then connect payment acceptance or payouts Payment acceptance cards FPS SberPay T-Pay YooMoney Payouts to card to account in RU bank via FPS via BESP Open after the settlement account—then set up payouts Payouts to card to account in RU bank via FPS via BESP Top up the account in advance Payouts to card to account in RU bank to YooMoney to cards in currency VAT via 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 Currently, Bank 131 supports two API versions for certain methods. Some object names vary depending on the version. :::info Using incorrect object names may result in failed operations. ::: | API v1 | API v2 | |----------------------|----------------------| | `payment_method` | **`payout_details`** | | `payments` | **`payout_list`** | | `acquiring_payments` | **`payment_list`** | Methods supported in API v2 - [`session/create`](/reference/methods#sessioncreate) - [`session/init/payout`](/reference/methods#sessioninitpayout) - [`session/init/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/start/payout`](/reference/methods#sessionstartpayout) - [`session/start/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/init/payment`](/reference/methods#sessioninitpayment) - [`session/init/payment/sync`](/reference/methods#sessioninitpaymentsync) - [`session/start/payment`](/reference/methods#sessionstartpayment) - [`session/confirm`](/reference/methods#sessionconfirm) - [`session/capture`](/reference/methods#sessioncapture) - [`session/cancel`](/reference/methods#sessioncancel) - [`session/refund`](/reference/methods#sessionrefund) - [`fps/customer_verification`](/reference/methods#fps_verification) - [`session/status`](/reference/methods#sessionstatus) - [`session/init/payout/nominal`](/reference/methods#payout-nominal) - [`session/multi/create/nominal`](/reference/methods#sessionmulticreatenominal) - [`session/multi/init/payment/nominal`](/reference/methods#sessionmultiinitpaymentnominal) - [`session/multi/start/payment/nominal`](/reference/methods#sessionmultistartpaymentnominal) - [`session/init/payout/rko`](/reference/methods#payout-rko) - [`session/multi/create/rko`](/reference/methods#sessionmulticreaterko) - [`session/multi/start/payment/rko`](/reference/methods#sessionmultistartpaymentrko) ## Endpoint #### How to set this out ` + /api/v{API version number} + ` #### Server address For demo testing: `https://demo.bank131.ru` For live transactions: `https://proxy.bank131.ru` Example: **API v1**: `https://demo.bank131.ru/api/v1/session/init/payout` **API v2**: `https://demo.bank131.ru/api/v2/session/init/payout` ## API authentication Each time you send a request, you must provide your project identifier and the request signature. This allows the Bank to identify you and verify that the request originated from you. | Name | Mandatory | Type | Description | |-------------------------|--------------------------------------------------------------------------------------------|--------|-----------------------------------------------------------| | `X-PARTNER-PROJECT` | \+ | string | Project identifier. Given to you by your Bank 131 manager | | `X-PARTNER-SIGN` | \+ | string | [Request signature](#request-signature) | | `X-PARTNER-SUBMERCHANT` | \- (mandatory for financial institutions that are non-residents of the Russian Federation) | string | Payer's identifier (for legal entities) | Request example with authentication ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // request body }' ``` ### Request signature A signature is required to verify that a request originated from you and not from someone else, and that it was not modified in transit. Two keys are needed for signature verification: a public key (shared with the Bank in the [Certificate of recognition of the electronic signature verification key](/assets/online/bank131_remote_banking_service_rules.pdf)) and a private key (stored securely on your side). The Bank uses the public key to validate requests. The private key is used to sign your requests and must never be disclosed to anyone. You need to generate these two keys using the RSA algorithm. #### Creating request body signature The entire request body must be signed exactly as it is sent to the Bank (i.e., the full text in JSON format). Your private key is required to create the signature. The signature is generated using the SHA-256 encryption method. After creation, the signature must be encoded into Base64 format so it can be transmitted with the request. #### Verifying incoming requests from Bank 131 All outgoing requests 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 - For demo testing Signature generation and validation examples ```openssl showLineNumbers # Generating the private key $ openssl genrsa -out private.pem 2048 # Generating the public key based on the private key $ openssl rsa -in private.pem -pubout > public.pem # Creating the myfile.txt file contents $ echo test > myfile.txt # Generating the signature $ openssl dgst -sha256 -sign private.pem -out sha256.sign myfile.txt # Signature ready for transfer $ base64 sha256.sign # Checking the signature $ openssl dgst -sha256 -verify public.pem -signature sha256.sign myfile.txt Verified OK ``` ```php showLineNumbers $data = "test"; //Obtaining the pointer to the private and public keys $privateKey = openssl_pkey_get_private("file://private.pem"); $publicKey = openssl_pkey_get_public("file://public.pem"); //Generating the signature based on the data using the private key openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); //Encoding the signature into Base64 to transmit it $base64Signature = base64_encode($signature); //On receiving the signature, decoding it from Base64 $decodedSignature = base64_decode($base64Signature); //Validating the received signature using the public key (success = 1) $isValid = openssl_verify($data, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256); ``` ## Idempotency key An idempotency key is a unique code that you generate for each operation to prevent the same operation from being executed multiple times. For example, you sent a payment request, but due to a slow internet connection, you are unsure if it went through. If you send the request again, the funds might be debited twice. To avoid this, use an idempotency key. You generate the key yourself and send it with the request. The Bank stores this key and, if a request with the same key arrives within 24 hours, the Bank will recognize it as a duplicate request and will not perform the operation again. The idempotency key identifier is specified in the request header. | Name | Mandatory | Type | Description | | ----------------- | -------------- | ------ | ---------------------------------------------------- | | `X-PARTNER-IDEMPOTENCY-KEY` | - | string | Idempotency key (from 4 to 64 characters) | Example of a request with an idempotency key ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-IDEMPOTENCY-KEY: testkey' \ -d '{ // request body }' ``` Methods supporting the idempotency key feature - [`session/create`](/reference/methods#sessioncreate) - [`session/init/payout`](/reference/methods#sessioninitpayout) - [`session/init/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/start/payout`](/reference/methods#sessionstartpayout) - [`session/start/payout/fiscalization`](/reference/methods#sessionstartpayoutfiscalization) - [`session/init/payment`](/reference/methods#sessioninitpayment) - [`session/init/payment/sync`](/reference/methods#sessioninitpaymentsync) - [`session/start/payment`](/reference/methods#sessionstartpayment) - [`session/confirm`](/reference/methods#sessionconfirm) - [`session/capture`](/reference/methods#sessioncapture) - [`session/cancel`](/reference/methods#sessioncancel) - [`session/refund`](/reference/methods#sessionrefund) #### Errors Below is a list of common errors that may occur when using the key: - `idempotency_key_params_mismatch` — The key has already been used for another session - `idempotency_key_already_exists` — The previous request with the same key is still in progress - `idempotency_key_not_supported` — This method cannot be used with an idempotency key [View error codes >](/reference/errors) ## Libraries You can use the [PHP SDK](https://github.com/bank131/php-sdk) library to integrate with Bank 131 API. Native SDKs for iOS and Android are not provided. 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 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. The steps depend on whether or not you use our widget. 1. Send a [token](/reference/methods#token) request to get a public token. The token is used to initialize the widget. 2. [Initialize the widget](/payouts/tokenize-widget) using the received token. >Save the hash for future payouts. 3. Start the payout in one of the following ways: - send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request and then a [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) request with the session identifier and payout details—the recommended option - start a session and the payout simultaneously ([`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)) 4. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from the Bank, indicating that it is ready to perform the payout and is waiting for your confirmation. 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout. >To enable automatic confirmation, contact you manager at Bank 131. 6. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook with the payout results. If the status is `succeeded`, the payout was successful. ### 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 ``` 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 ``` The steps depend on whether or not you use our widget. 1. Create a payment session with a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request. In the response you will get the session identifier. 2. Send a [token](/reference/methods#token) request to get a public token. The token is used to initialize the widget. 3. [Initialize the widget](/payments/payment-widget) using the received token. 4. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from the Bank, indicating that it is ready to perform the payment and is waiting for your confirmation. 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. >To enable automatic confirmation, contact you manager at Bank 131. 6. Wait for a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook. It means the required amount is held on the bank card successfully. Capture the full amount or a part of it ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)), or cancel the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). >Skip this step if [delayed capture payments](/payments/payment-hold) are not enabled for you. In this case, the funds will be put on hold and captured automatically. 7. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook with the payment results. If the status is `succeeded`, the payment was successful. ### 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 ``` 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 Current certificates and official instructions are available on the Gosuslugi portal: `https://www.gosuslugi.ru/crt`. Install two certificates: * **Russian Trusted Root CA** — root certificate * **Russian Trusted Sub CA** — intermediate certificate ### Installing the certificates 1. Download the Russian Trusted CA certificates. 2. Double-click the certificate file to open it. 3. Select **Install Certificate**. 4. Launch the Certificate Import Wizard. 5. Place the certificate in the **Trusted Root Certification Authorities** store. 6. Complete the import and confirm the installation. 7. Restart the applications and browsers you are using. For Debian/Ubuntu-based systems, run the following commands: ```json sudo cp russian_trusted_root_ca.pem /usr/local/share/ca-certificates/russian_trusted_root_ca.crt sudo cp russian_trusted_sub_ca.pem /usr/local/share/ca-certificates/russian_trusted_sub_ca.crt sudo update-ca-certificates ``` For RHEL/CentOS-based systems: ```json sudo cp russian_trusted_*.pem /etc/pki/ca-trust/source/anchors/ sudo update-ca-trust ``` After updating the certificate store, restart your application services. If your integration runs on Java, you may need to additionally import the certificates into the JVM truststore: ```json # Create a separate truststore and import both certificates keytool -importcert -alias russian_trusted_root \ -file russian_trusted_root_ca.pem \ -keystore russian_truststore.jks \ -storepass -noprompt keytool -importcert -alias russian_trusted_sub \ -file russian_trusted_sub_ca.pem \ -keystore russian_truststore.jks \ -storepass -noprompt ``` Specify the truststore when launching the application: ```json showLineNumbers java -Djavax.net.ssl.trustStore=/path/to/russian_truststore.jks \ -Djavax.net.ssl.trustStorePassword= \ -jar app.jar ``` ### Verifying the installation To verify that the trusted certificate chain is available: * send a test request to the Bank 131 API * ensure there are no SSL/TLS errors * check that the application logs do not contain any entries about an untrusted certificate or certificate chain validation errors Possible errors when the required root or intermediate certificates are missing from the trusted store: * `certificate verify failed` * `unable to get local issuer certificate` * `certificate chain validation error` * `SSL handshake failed` --- ## Payouts - [Collateral account API](https://developer.131.ru/en/payouts/collateral-intro): Details on operations with a collateral account in Bank 131 From a collateral account, you can make payouts to cards and accounts at Russian banks, as well as to YooMoney wallets. You deposit funds to your account in advance, and Bank 131 debits the funds and transfers them to the recipients. Bank 131 only processes payouts if there are sufficient funds in the collateral account to cover both the transfer amount and the fee. Therefore, you should regularly check the account balance. If you plan to make payouts via the Faster Payments System (FPS), you will need to open a [settlement account](/settlement-account/settlement-intro) or [an escrow account](/escrow-account/escrow-intro). ### Features - Payouts: - to bank cards ([by card number](/payouts/payout-pcidss), [with our widget or by token](/payouts/payout-tokenized-card)) and to Russian bank accounts ([by account number](/payouts/russian-account), [with our widget or by token](/payouts/payout-tokenized-account)) - [to YooMoney wallets](/payouts/yoomoney) - [to the FTS](/payouts/payout-taxes) - Balance info. Check your collateral account balance using the [`wallet/balance`](/reference/methods#walletbalance) method. ### Accounts for payouts Accounts allowed for payouts from collateral accounts --- - [Monthly reports](https://developer.131.ru/en/payouts/finance-act): Via email, EDM, or on paper --- - [Single-request payouts by account number](https://developer.131.ru/en/payouts/payout-account-simple): Save time on creating and performing payouts You can send a payout by account number within a single request. The system automatically handles data transfer and confirms payouts without any intermediate steps. To enable singe-request payouts, contact your Bank 131 account manager. Once this option is enabled, all your payouts will be processed this way. To disable it, contact your account manager again. ### Step 1. Create a session along with a payout Send a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request, specifying [the parameters for payouts](/payouts/russian-account-parameters). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Transfer of funds under agreement N 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\BankAccount\BankAccountRu; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->initPayoutSession() ->setBankAccount( new BankAccountRu( '044525971', '40817810100000270411', 'Ivanov Ivan Ivanovich', 'Transfer of funds under agreement N 5015553111 Ivanov Ivan Ivanovich VAT exempt' ) ) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->initPayout($request); ``` ### Step 2. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds) Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2025-05-27T02:03:00.809901Z", "updated_at": "2025-05-27T02:03:00.360812Z", "payments": [{ "id": "po_2025", // highlight-next-line "status": "succeeded", "created_at": "2025-05-27T02:03:00.204563Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Transfer of funds under agreement N 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` --- - [Speedy payouts to accounts via BESP](https://developer.131.ru/en/payouts/payout-account-sistema-besp): Speedy payouts to accounts via BESP You can send money from your collateral, settlement, or escrow account to bank accounts as speedy payouts through the [BESP system](https://www.banki.ru/wikibank/sistema_besp)—in this case, the money will be credited within an hour. To enable speedy payouts, contact your account manager at Bank 131. The tariffs for speedy payouts are fixed in the agreement with Bank 131. ### Accounts for payouts The accounts you can send payouts to depend on the account you make a payout from: settlement, escrow, or collateral one. Accounts allowed for payouts from settlement/escrow accounts Accounts allowed for payouts from collateral accounts ### Making a speedy payout :::warning If this payout method was not stipulated in your agreement with Bank 131, the transaction will fail with a `routing_internal_error`. In case the recipient's bank is not connected to the BESP system, the payout will be sent as a standard one, but Bank 131 will charge the commission for a speedy payout anyway. ::: [Follow the standard scenario of a payout without our widget](/reference/typical) specifying the parameters required for a payout from a [collateral](/payouts/russian-account-parameters), [settlement](/settlement-account/russian-account-parameters), or [escrow](/escrow-account/russian-account-parameters) account. Make sure you pass `true` in the `is_fast` parameter of the [`ru`](/reference/reference-objects.mdx#ru) object, otherwise a standard payout will be made. #### Object example ```json showLineNumbers { "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt", // highlight-next-line "is_fast": "true" } } } ``` [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) [How to learn that a payout was returned >](/payouts/payout-refunds.mdx) --- - [Payouts to cards in a foreign currency](https://developer.131.ru/en/payouts/payout-currency): Payouts in a foreign currency To enable payouts in a foreign currency, sign an agreement with Bank 131. :::warning If you enabled automatic confirmation earlier, disable it to see the amount in rubles to be debited that is returned in a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook. To do this, contact your account manager at Bank 131. ::: When sending a request, specify the amount in the required currency. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, // highlight-start "amount_details": { "amount": 10000, "currency": "usd" }, // highlight-end "metadata": "good" }' ``` Bank 131 will convert the amount at the exchange rate specified in your agreement and debit the ruble equivalent from your account. The recipient will receive the payment in Russian rubles. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.346700Z", "updated_at": "2025-05-27T02:03:00.100044Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.568099Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, // highlight-start "amount_details": { "amount": 800000, "currency": "rub" }, // highlight-end "metadata": "good" }] } }' ``` You can make a payout in a foreign currency in one of the following ways: - [by card number](/payouts/payout-pcidss) - [with our widget or by token/hash](/payouts/payout-tokenized-card) --- - [Payouts via FPS to a phone number](https://developer.131.ru/en/payouts/payout-fps-phone): Payouts to individuals' accounts via FPS You can make payouts to an account of an individual by their phone number via the Faster Payment System (FPS) from your settlement or escrow account. To do this, open a settlement account with Bank 131, after which the Bank signs you up to the Faster Payment System. :::info To see an up-to-date list of banks participating in FPS, use our [`fps/banks`](/reference/methods#banks_fps) method. ::: Before making a payout using the new details, check whether the recipient is registered in FPS using the [`fps/customer_verification`](/reference/methods#fps_verification) method. For subsequent payouts using the same details, verification is not required. :::warning[Important!] FPS payouts cannot be refunded. ::: ### Payout parameters | Name | Mandatory | Type | Description | |-------------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payout data](/reference/reference-objects.mdx#payment_method) | |   `type` | + | string | Value: `bank_account` | |   `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |     `system_type` | + | string | Bank transfer system. Always: `faster_payment_system` | |     `faster_payment_system` | + | object | [FPS data](/reference/reference-objects.mdx#faster_payment_system) | |       `phone` | + | string | Recipient's phone number | |       `bank_id` | + | string | Identifier of the recipient's bank in FPS | |       `description` | + | string | [Payout purpose](#target) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |   `currency` | + | string | Currency code according to ISO 4217. Case insensitive. Always: `rub` | | `participant_details` | - (mandatory for payouts from an escrow account) |object | [Information on the payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender details](/reference/reference-objects.mdx#participant_details_sender) | |       `account` | + | string | Escrow account number from which to make the payout | |   `recipient` | + | object | [Recipient details](/reference/reference-objects.mdx#participant_details_recipient) | |       `beneficiary_id` | + | string | INN of the beneficiary | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - minimum length: 15 characters - maximum length: 140 characters #### Payout purpose example `Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ## How to perform a payout from the settlement account Use the [payout scenario without our widget](/settlement-account/settlement-payout-accounts) sending the parameters from the table above. Example of an FPS payout from the settlement account ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", // highlight-start "bank_account": { "system_type": "faster_payment_system", "faster_payment_system": { "phone": "79680000000", "bank_id": "100000000069", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } // highlight-end } }, "amount_details": { "amount": 30000, "currency": "rub" }, "metadata": "good" }' ``` ## How to perform a payout from the escrow account :::warning[Important!] Before making a payout, submit a list of beneficiaries to Bank 131 to [identify them](/escrow-account/verification-intro). ::: Use the [payout scenario without our widget](/escrow-account/escrow-payout-accounts) sending the parameters from the table above. Example of an FPS payout from the escrow account ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", // highlight-start "bank_account": { "system_type": "faster_payment_system", "faster_payment_system": { "phone": "79680000000", "bank_id": "100000000069", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } // highlight-end } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } }, "metadata": "good" }' ``` --- - [About payouts](https://developer.131.ru/en/payouts/payouts-intro): API for convenient and secure payouts You can securely and with ease execute payouts to individuals, legal entities, sole proprietors, and self-employed persons as well as pay [VAT](/payouts/payout-taxes) to the Federal Tax Service. You can make payouts in both Russian rubles and [foreign currency](/payouts/payout-currency). You can send money to: - [bank cards](/payouts/russian-card) (Visa, MasterCard, and Mir) - [Russian bank accounts](/payouts/russian-account) - [YooMoney wallets](/payouts/yoomoney) Also, you can send money by the recipient's phone number [via the FPS](/payouts/payout-fps-phone). :::info Bank 131 provides a [daily payout report](/finance/payouts-daily-report) and a [monthly payout report](/payouts/finance-act). ::: ### Bank accounts Depending on your goals and objectives, you will need one or more accounts: a settlement account, a collateral account, and/or an escrow account. #### Settlement account With a settlement account, you can send payouts to counterparties, disburse salaries, settle taxes, and perform other transactions. You can transfer money to Russian bank cards and accounts, or send it by phone number via the FPS. [Learn more on working with the settlement account >](/settlement-account/settlement-intro) #### Escrow account An escrow account is a special bank account for settlements between transaction participants. The key feature of this account is that the funds in it belong to third parties—the beneficiaries, and not to you as the account holder. These beneficiaries are your clients under contracts. You are authorized to manage the funds on their behalf, but you do not own them. To open an escrow account, you must first have a settlement account. The escrow account is used exclusively for payouts, ensuring a clear separation between your funds and your clients' funds. From your escrow account, you can make payouts to bank cards and Russian bank accounts, including via FPS. Before making any payouts, submit a list of beneficiaries to Bank 131. [Learn more on working with the escrow account >](/escrow-account/escrow-intro) #### Collateral account Use your collateral account if you do not need a settlement account. First you deposit funds to the account in advance, and Bank 131 makes payouts provided there are sufficient funds in the account for the transfer, including the fee. Regularly check the balance of your collateral account using the [`wallet/balance`](/reference/reference-methods.mdx#walletbalance) method. If the balance is low, top it up in advance. You can transfer money to cards and accounts at Russian banks, as well as to YooMoney wallets. [Learn more on working with the collateral account >](/payouts/collateral-intro) ### Processing, transferring, and storing card details Choose how you will process, transfer, and store card details: - On your own. You will need to comply with all the requirements of PCI DSS for this method. You can send payouts: - by card number. You get the number using any convenient method and make a payout. - by a bank card token or hash. - Using Bank 131 widget. It is sufficient to meet PCI DSS requirements to operate this widget. You simply embed the widget on your website, the user enters their card number, and Bank 131 saves it in its system and returns a hash to you for payouts. ### Card identifier A card identifier is necessary to determine which card the recipient is using and to identify cases where multiple recipients are using the same card. The identifier is generated based on the card number and its expiration date if it is available. It is passed in the `card_id` parameter of the [`card`](/reference/objects#card) object. By default, `card_id` is unique for each project but you can choose this value to be the same across all your projects. [Learn more about the project >](/before) :::info A card identifier is not a replacement for a token and cannot be used to make payouts or to retrieve all cards linked to a recipient. ::: To set up the identifier, contact your manager at Bank 131. ### 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. --- - [Single-request payouts by card number](https://developer.131.ru/en/payouts/payout-pcidss-simple): Save time on creating and performing payouts You can send a payout by card number within a single request. The system automatically handles data transfer and confirms payments without any intermediate steps. In this case, you will need to comply with all the requirements of PCI DSS for this method. To enable singe-request payouts, contact your account manager at Bank 131. Once this option is enabled, all your payouts will be processed this way. To disable it, contact your account manager again. ### Step 1. Create a session along with a payout Send a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request, specifying [the parameters for payouts](/payouts/russian-card). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Participant; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $participant = new Participant(); $participant->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->initPayoutSession('3230') ->setCard(new BankCard('2200********4940')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->initPayout($request); ``` ### Step 2. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. [More about the payout statuses >](/reference/objects#payout_status) [View error codes >](/reference/errors) Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2025-05-27T02:03:00.303051Z", "updated_at": "2025-05-27T02:03:00.890003Z", "payments": [{ "id": "po_2025", // highlight-next-line "status": "succeeded", "created_at": "2025-05-27T02:03:00.760584Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` --- - [Payouts by card number](https://developer.131.ru/en/payouts/payout-pcidss): Payouts by card number To make payouts by card number, you will need to comply with all the requirements of PCI DSS for this method. ### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` ### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-card). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Participant; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $participant = new Participant(); $participant->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->startPayoutSession('3230') ->setCard(new BankCard('2200********4940')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayout($request); ``` ### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.012389Z", "updated_at": "2025-05-27T02:03:00.023504Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.102036Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { $session = $hook->getSession(); //do your logic here } ``` ### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` ### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` ### 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 the self-employed, sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors| |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | |          `is_fast` | - | string | For [speedy payouts](/payouts/payout-account-sistema-besp) (via BESP) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000` | |    `currency` | + | string | Currency code by ISO 4217. Case insensitive. Always: `rub` | | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | |          `is_fast` | - | string | For [speedy payouts](/payouts/payout-account-sistema-besp) (via BESP) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000` | |    `currency` | + | string | Currency code by ISO 4217. Case insensitive. Always: `rub` | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `full_name` | - (mandatory if the sender is an individual) | string | Sender's name | |       `company_name` | - (mandatory if the sender is a legal entity) | string | Company name | |       `address_line` | + | string | Address. Important: a city and country should be specified in the following fields, do not duplicate them here | |       `country_iso3` | + | string | Country (ISO-3166-1 alpha-3 | |       `city` | + | string | City | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters #### Payout purpose example `Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ### What next [Payouts by bank account number >](/payouts/russian-account) [Payouts using our widget or by token >](/payouts/payout-tokenized-account) --- - [Payouts by bank account number](https://developer.131.ru/en/payouts/russian-account): Payouts by bank account number You can send money from your collateral account to bank accounts as follows: - [as a standard payout](#payout_account)—the money will be credited within a period from 2 hours to 3 banking days (this depends on the recipient's bank) - [as a speedy payout through the BESP system](https://www.banki.ru/wikibank/sistema_besp)—the money will be credited within an hour ### Making a standard payout #### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/payouts/russian-account-parameters) with open card data and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Send the payout Send a [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) request, specifying the session identifier alongside the [payout parameters](/payouts/russian-account-parameters). Example of a payout by account number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "{VO99090} Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "sender": { "full_name": "Vector LLC", "address_line": "123 Main Street", "country_iso3": "USA", "city": "New York" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` #### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.456004Z", "updated_at": "2025-05-27T02:03:00.756005Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.355006Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout. Confirming a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Пример с отменой выплаты ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. :::info To get notifications when funds are credited to the recipient's account, enable the [`confirmation_payout`](/reference/webhooks#confirmation_payout) webhook. To do this, contact your account manager at Bank 131. Webhook delivery is not guaranteed by Bank 131, as it depends on the recipient bank. ::: ### 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. Below are the mandatory parameters to perform a payout to a Russian bank card by token, hash, or via the Bank 131 widget. | Name | Mandatory | Type | Description | |---------------------------------------------|-------------------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment data](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Values: `encrypted_card` or `tokenized_card` | |       `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Encrypted card details](/reference/reference-objects.mdx#encrypted_card) | |          `number_hash` | + | string | Card number hash | |       `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | |          `token` | + | string | Card number token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | Below are the mandatory parameters to perform a payout to a Russian bank card by its number. | Name | Mandatory | Type | Description | |-----------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, bank account, etc.) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Value: `bank_card` | |       `bank_card` | + | object | [Card details](/reference/reference-objects.mdx#bankcard) | |          `number` | + | string | Card number | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | ### What next [Payouts by card number >](/payouts/payout-pcidss) [Payouts using our widget or by token/hash >](/payouts/payout-tokenized-card) --- - [Main payout scenario](https://developer.131.ru/en/payouts/payout-scenarios): Payouts via API with and without a token ## What kinds of scenarios we have Payouts via API can be performed with or without a token. The choice of a scenario depends on how the payment is received and whether you decided to collect and store bank card details on your side. ### Payout to a bank card with the widget In this case, you cannot store and send the recipient's bank card details with open parameters, which means the payout can only be performed using a token, via the [tokenization widget](/payouts/widget-tokenize.mdx). The widget allows you to obtain the user's card details and pass them along within your request in a secure tokenized form. [How to perform a payout to a bank card using our widget](/payouts/payout-tokenized-card.mdx) > To show the user which bank card will receive the payment, use the [`token/info`](/reference/reference-methods.mdx#token_info) method. It takes the last 4 numbers of the card by its token. ### Payout to a bank card, bank account, via FPS, YooMoney wallet No need to use a token: all the payout parameters can be passed along with open parameters. ## Payment session All API operations are carried out within a payment session ([`session`](/reference/reference-objects.mdx#payment_session)) – payouts, payments, and refunds. You can perform payouts in two ways: - initiate the payout when you start the session (as a single request, [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)) - or create a session and only then perform the payout (making two requests: [`session/create`](/reference/reference-methods.mdx#sessioncreate) and [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout)). For example, to immediately obtain the session identifier and use it to monitor the payout status. ## Main payout scenario >#### These steps are only necessary for payouts with the widget >1. Send a request for token creation to access the JavaScript library. >2. Create the [widget](/payouts/widget-tokenize.mdx) with this token, show it to the user, and obtain the card details in tokenized form. >Tokenized card details can be saved so that you can send money to that card later. 3. Perform the payout however you prefer: - either first create a payment session ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) and then create a payout using this session's identifier ([`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout)) - or create a session and a payout simultaneously ([`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout)). In the request for payout creation, you pass the method of receiving the payment and all the parameters mandatory for that method. 1. Make sure Bank 131 is ready to perform a payment and is waiting for your approval. There are two options: - get a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook from Bank 131 - send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request and wait until `confirm` is returned in the `session.next_action` field. 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the operation. 6. Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the result of the payout. If the status is `succeeded`, the payout has been performed successfully. > A payout to a Russian bank account may be refunded within 5 days. In this case, you will receive a `payment_refunded` webhook. [Learn more about payout refunds](/payouts/payout-refunds.mdx) ## Scenario of payouts to self-employed people If you are paying out to self-employed people, the scenario will be slightly different. - Before the start of the payout (at the very beginning), check that the person really is self-employed and is connected to Bank 131. - If the INN belongs to the self-employed person but is not connected to Bank 131, create [a connection request](/selfemployed/selfemployed-binding). - If everything is fine, perform the payout following the standard scenario. Along with the payment, send fiscalization details: [`session/init/payout/fiscalization`](/reference/reference-methods.mdx#sessioninitpayoutfiscalization) or [`session/start/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization). [More about payouts to the self-employed](/selfemployed/intro) ## Single-request payout For payouts to bank accounts or to cards, there is a simplified scenario: you send the payout using a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request and obtain the result from a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook or using the [`session/status`](/reference/reference-methods.mdx#sessionstatus) method. [How to perform a single-request payout](/payouts/payout-pcidss-simple.mdx) ## Payout in a foreign currency (other than Russian ruble) The following steps are eligible for payouts in a foreign currency: - Send a request to create a payment session [`session/create`](/reference/reference-methods.mdx#sessioncreate). - Send a request to create a payout using this session identifier [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout). - Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook from Bank 131 to make your payout. For more details on how to perform payouts in a foreign currency, click [here](/payouts/payout-currency.mdx) ## Payout statuses The status of a payout is returned in the `status` field of the [`payments`/`payout_list`](/reference/objects#payout_status) array. To query it, wait for a webhook from Bank 131 or send a [`session/status request`](/reference/reference-methods.mdx#sessionstatus) with the identifier of the session containing this payout. You can choose any of these options or combine them as you wish. --- - [Payouts to the Russian Federal Tax Service](https://developer.131.ru/en/payouts/payout-taxes): Payouts to the Russian Federal Tax Service `Google tax`—is a value-added tax (VAT) for foreign companies that provide electronic services to customers in Russia. To pay it using our API, contact your manager. ### Possible scenarios **With an automatic deduction**. This scenario is for you if you [accept payments](/payments/payment-intro) through Bank 131. Bank 131 automatically withholds the tax amount from each payment. When the payment deadline arrives, the funds are already in your collateral account. **With account top-up**. You top up your collateral account with Bank 131. Then, the Bank executes your orders for payouts to the tax service. >To check the collateral account balance, use the [`wallet/balance`](/reference/reference-methods.mdx#walletbalance) method. ### How to pay the tax To pay the tax, specify the following bank details: ``` BIC: 017003983  Treasury Account: 03100643000000018500  Treasury Single Account: 40102810445370000059  Recipient: Federal Treasury of Russia (Federal Tax Service of Russia) INN: 7727406020  KPP: 770801001 KBK: 18201061201010000510 ``` Send a [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) request with a minimal or [extended](#parameters_full) set of parameters, when you need to specify additional details (for example, KBK, OKTMO, period, etc.). #### Payout with a minimal set of parameters **Request parameters** | Name | Mandatory | Type | Description | |-------------------------------------|-----------|--------|--------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | 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": { // highlight-next-line "type": "tax_short", "tax_details": {} } } }' ``` #### Payout with an extended set of parameters **Request parameters** | Name | Mandatory | Type | Description | |-----------------------------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | 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` - `TP` – for current-period tax/contribution payment - `ZD` – for voluntary repayment of tax/contribution arrears - `TR` – for debt repayment based on a demand issued by the tax authority or the Social Security Fund (FSS) - `AP` – for debt repayment based on audit findings (before a demand is issued) ##### `period` - If the `payment_reason` parameter contains `TP` or `ZD`, the tax payment frequency established by legislation is indicated in one of the formats below: - for monthly payments: `MS.MM.YYYY`, where `MM` is the month (from 01 to 12), and `YYYY` is the year for which the payment is made (for example, when paying personal income tax for employees' salaries for February 2026, use `MS.02.2025`) - ror taxes paid quarterly: `KV.QQ.YYYY`, where `QQ` is the quarter (from 01 to 04), and `YYYY` is the year for which the tax is paid - for semi-annual taxes (e.g., `UTII`): `PL.HH.YYYY`, where `HH` is the half-year (01 or 02), and `YYYY` is the year for which the tax is remitted - for annual payments: `GD.00.YYYY`, where `YYYY` is the year for which the tax is paid (for example, when making the final calculation for corporate profit tax for 2025, use `GD.00.2025`) - If the `payment_reason` parameter contains `TR`, specify the demand date - If the `payment_reason` parameter contains `AP`, specify `0` ##### `document_number` If the `payment_reason` parameter contains: - `TP` or `ZD`, specify `0` - `TR`, specify the tax demand number - `AP`, specify the audit decision number ##### Input format for the `document_date` field If the `payment_reason` parameter contains: - `TP`, specify the declaration signing date or `0` if the date is missing - `ZD`, specify `0` - `TR`, specify the tax demand date - `AP`, specify the post-audit decision date Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "tax", "tax": { // highlight-next-line "type": "tax_full", "tax_details": { // highlight-start "period": "КВ.04.2025", "document_number": "12345", "kbk": "18210301000011000110", "oktmo": "45348000", "payment_reason": "ЗД", "document_date": "01-07-2025" }, "description": "test payment", "uin": "0", "payer": { "inn": "1234567890", "kpp": "044525416" }, "payee": { "bik": "017003983", "account": "30102810400000000001", "account_eks": "40101810045250010041", "name": "name", "kpp": "770701001", "inn": "7707500730" } // highlight-end } }, "amount_details": { "amount": 5900, "currency": "rub" }, "customer": { "reference": "lucky", "contacts": [{ "email": "user123@test.com" }] }, "metadata": { "key": "value" } }' ``` ##### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters ##### Payout purpose example `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` --- - [Payouts to accounts using our widget or by token](https://developer.131.ru/en/payouts/payout-tokenized-account): Payouts without account details on your side You can make payouts to bank accounts using a token instead of the account number. You can get the token as follows: - using our [`tokenize`](/reference/methods#tokenize) method - using our [widget](/payouts/tokenize-account-widget) #### Step 1. Get a public token The public token is needed to initialize the widget. Send a [`token`](/reference/reference-methods.mdx#token) request to create a token, specifying the `tokenize_widget` widget type. You will receive a public token in response. Request example ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setTokenizeWidget() ->build(); $response = $client->widget()->issuePublicToken($request); $publicToken = $response->getPublicToken(); ``` #### Step 2. Initialize the widget [Initialize the widget](/payouts/tokenize-account-widget) on your website using the public token you received at the previous step. After this, the recipient can enter their bank account number into the widget form. #### Step 3. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/payouts/russian-account-parameters) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with the [payout parameters](/payouts/russian-account-parameters). :::info You can get information on the token or account using the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Money transfer" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.102034Z", "updated_at": "2025-05-27T02:03:00.454005Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.676006Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Money transfer" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-account-parameters) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-account-parameters). :::info You can find information on the token or account using the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ // highlight-next-line "session_id": "ps_1694821", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Payout" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.456004Z", "updated_at": "2025-05-27T02:03:00.756005Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.355006Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Payout" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Sequence diagram ![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 ``` ![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. #### Step 1. Get a public token The public token is needed to initialize the widget. Send a [token](/reference/reference-methods.mdx#token) request to create a token, specifying the `tokenize_widget` widget type. You will receive a public token in response. Request example ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setTokenizeWidget() ->build(); $response = $client->widget()->issuePublicToken($request); $publicToken = $response->getPublicToken(); ``` #### Step 2. Initialize the widget [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token you obtained in the previous step. After this, the recipient can enter their bank card details into the widget form. #### Step 3. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-card). :::info You can find information on the hash or card using the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\EncryptedCard; 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('number_hash')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayout($request); ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.340663Z", "updated_at": "2025-05-27T02:03:00.745032Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.203301Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { //do your logic here } ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Example of how to handle a webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` In the request specify either token or hash depending on which one you use. #### Step 1. Create a payment session Create a session using the [`session/create`](/reference/reference-methods.mdx#sessioncreate) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout`](/reference/reference-methods.mdx#sessioninitpayout) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/payouts/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout`](/reference/reference-methods.mdx#sessionstartpayout) method. Pass the session identifier along with all the [parameters for a payout](/payouts/russian-card). :::info You can find information on the token, hash, or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. ::: Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_method": { // highlight-start "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } // highlight-end }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.102599Z", "updated_at": "2025-05-27T02:03:00.560466Z", "next_action": "confirm", "payments": [{ "id": "po_2025", "status": "pending", "created_at": "2025-05-27T02:03:00.607390Z", "customer": { "reference": "user123", "contacts": [{ "email": "user123@test.ru" }] }, "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "bin": "220024", "country_iso3": "RUS" } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { //do your logic here } ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Example of how to handle a webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` #### Sequence diagram ![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 ``` ![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 and self-employed people. ### Payout parameters | Name | Mandatory | Type | Description | |---------------------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payout details](/reference/reference-objects.mdx#payment_method) | |   `type` | + | string | Value: `wallet` | |   `wallet` | + | object | [Recipient's electronic wallet](/reference/reference-objects.mdx#wallet) | |     `type` | + | string | Wallet type. Value: `yoomoney` | |     `yoomoney` | + | object | [YooMoney wallet details](/reference/reference-objects.mdx#yoomoney) | |       `account` | + | string | YooMoney wallet number, 11 to 20 digits. Example: `4100175017397` | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | ### How to perform the payout Use the [payout scenario without our widget](/reference/typical) sending the parameters from the table above. YooMoney wallet payout request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { // highlight-start "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": { "account": "410012411727100" } } // highlight-end }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` --- - [Widget for getting tokenized bank account details](https://developer.131.ru/en/payouts/tokenize-account-widget): Widget for getting tokenized bank account details Use the widget to save bank account details with Bank 131. ### What the widget looks like Code example: a page with the widget ```html showLineNumbers Widget for bank account tokenization document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131BankAccountTokenizer) { return; } const bankAccountTokenizer = new Bank131BankAccountTokenizer( publicToken, { /* // An example of widget text settings texts: { // Label field Account number. The default is "Account number". bankAccountLabel: '', // BIC field label. The default is "BIC". bikLabel: '', // Account linking button. The default is "Link account". submitButtonLabel: '', validationErrors: { invalidBankAccount: '', invalidBankAccountLength: '', invalidBikLength: '', isRequired: '' }, }, styles: { bankAccountTokenizer: { // Styles for the inline input field container. inputContainer: { background: 'cornsilk' }, // Styles for the input field. inputField: { background: 'cornsilk' }, // Styles for the input field when focused. inputFieldIsFocused: { background: 'white' }, // Styles for the error input field. inputFieldIsInvalid: { background: 'red' }, // Styles for the input field placeholder. inputFieldPlaceholder: { color: 'blue' }, }, } */ } ); bankAccountTokenizer.onReady = function () { console.log('Bank account tokenizer is ready.'); }; bankAccountTokenizer.onTokenizationStart = function () { console.log('The tokenization process was started.'); }; bankAccountTokenizer.onTokenizationFail = function () { console.log( 'The tokenization process was finished with an error', error ); }; bankAccountTokenizer.onTokenizationSuccess = function (result) { console.log( 'The tokenization process was successfully finished.', result ); }; bankAccountTokenizer.render(); }); ``` ### How the widget operates You embed the widget on your website. The user enters their account details, Bank 131 stores them in its system, and returns a payout token to you. You can save this token and use it for future payouts to the same account. This is secure. :::info You can find out information about a token using the [`token/info`](/reference/reference-methods.mdx#token_info) method. ::: ### Initializing the widget #### Step 1. Get a public token Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. #### Step 2. Set up scripts and CSS styles Include the widget's script (JS) and styles (CSS). The URLs differ between testing and live operations: ```html showLineNumbers ``` ```html showLineNumbers ``` After linking the script to the page, the `Bank131BankAccountTokenizer` class will appear in the global scope. #### Step 3. Add a container Add a container with a unique ID to place the widget on the page: ```html showLineNumbers ``` #### Step 4. Create an instance of the class Pass the public token to the `Bank131BankAccountTokenizer` class constructor: ```js showLineNumbers const bankAccountTokenizer = new Bank131BankAccountTokenizer('public token'); ``` You can also pass settings for widget texts and styles for the input field to the constructor: ```js showLineNumbers const bankAccountTokenizer = new Bank131BankAccountTokenizer( 'public token', { texts: { // Label field Account number. The default is "Account number". bankAccountLabel: '', // BIC field label. The default is "BIC". bikLabel: '', // Account linking button. The default is "Link account". submitButtonLabel: '', validationErrors: { invalidBankAccount: '', invalidBankAccountLength: '', invalidBikLength: '', isRequired: '' }, }, styles: { bankAccountTokenizer: { // Styles for the inline input field container. inputContainer: { background: 'cornsilk' }, // Styles for the input field. inputField: { background: 'cornsilk' }, // Styles for the input field when focused. inputFieldIsFocused: { background: 'white' }, // Styles for the error input field. inputFieldIsInvalid: { background: 'red' }, // Styles for the input field placeholder. inputFieldPlaceholder: { color: 'blue' }, }, } ); ``` The following key event handlers can be used: ```js showLineNumbers bankAccountTokenizer.onReady = function () { // Handler for the widget's readiness event. }; bankAccountTokenizer.onTokenizationStart = function () { // Event handler that occurs when the tokenization process starts. }; bankAccountTokenizer.onTokenizationFail = function () { // Event handler that occurs when the tokenization process fails. }; bankAccountTokenizer.onTokenizationSuccess = function (result) { // Event handler for the successful completion of the tokenization process. }; ``` #### Step 5. Display the widget Call the `render()` method: ```js showLineNumbers bankAccountTokenizer.render(); ``` [How to make a payout with the widget ot by token >](/payouts/payout-tokenized-account) --- - [Widget for getting tokenized bank card details](https://developer.131.ru/en/payouts/tokenize-widget): Secure transactions with bank cards with the widget --- ## Payments - [Monthly report](https://developer.131.ru/en/payments/finance-act): Monthly payout report --- - [AFT payments](https://developer.131.ru/en/payments/payment-aft): Replenishment of an account or wallet from a bank card An AFT payment (Account Funding Transaction) is an operation to top up an account or wallet from a bank card. To enable AFT payments, please contact a manager at Bank 131. :::info When processing an AFT payment, the issuing bank may charge a commission. Note that there might be no grace period if a payment is made using a credit card. ::: The processing scenario for an AFT payment does not differ from the scenario for [processing a regular bank card payment](/payments/payment-pcidss.mdx). --- - [Payments via FPS](https://developer.131.ru/en/payments/payment-fps-qr): Payments via FPS You can receive payments using the Faster Payment System (FPS). To do this: 1. Open an account in Bank 131. 2. Register your legal entity account with the FPS. 3. Add an FPS payment link onto your payment webpage. You can accept FPS payments in two ways: * With a QR code, which works for payments made from a desktop browser (`customer_interaction.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": { // highlight-next-line "type": "faster_payment_system", "faster_payment_system": { // highlight-next-line "description": "Payment of services" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_123456789", "status": "created", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z" } } ``` 2. Send a payment request using the [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) method. The `payment_options.return_url` parameter contains an URL to take customer back from the issuer's mobile application. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_123456789", "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" }, "customer": { "reference": "lucky" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_123456789", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_5000", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }] } } ``` 3. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to confirm the payment with [`session/confirm`](/reference/reference-methods.mdx#sessionconfirm) or cancel the payment with [`session/cancel`](/reference/reference-methods.mdx#sessioncancel). 4. Wait for an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook. The `customer_interaction.inform.qr.content` parameter contains a deeplink which you can either display as QR code to the customer in a web browser, or forward the customer to the issuer's mobile application. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_120285623", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_94939668", "status": "pending", "created_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "95.24.204.116" }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer_interaction": { "type": "inform", "inform": { "qr": { // highlight-next-line "content": "https://qr.nspk.ru/AD1000269CKIK8M09C1RB40LB7QAM8IH?type=02&bank=100000000143&sum=1000&cur=RUB&crc=C900", "img": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAATw0lEQVR42u3deXBURR7Acba2at3aqt2tPRRh5dBFWBQUWFYBCVqIS4mCuF5EQiGHohwCyuGFHCpGRUAsISACGw5RWK6AAV3FFbkhCgQLiCEc4QhHCCEkmVy/zYxmYEIyCWHy+tdvvr+q/gOmJzPzXvfnHb/X3TWEIAjCkqjBJiAIArAIgiAAiyAIwCIIggAsgiAIwCIIArAuerFGDTWlst+v0j/8Cj7X2M4ytK2u5PuFup4T7cqJtmaqHdjYzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlqmOqakRaYdXExKmOo1bDgza+4ITvw2wAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACvswDLVgW38ftqLEx3JVDtwc7ZT076szv0GWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWEqzZpoygqb+nqbspKlsopsPjoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWOqyPpqGLWhvlJqG0tjYqbXP1wVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYzIdlFCInsn+aMqDat4upbKJbwDfVzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlo0rP1OPetSzY942wKIe9agHWIBFPeoBFmABFvWoB1iART3qUc/VYGkPTcMgtM+HpSmLZOO8aNrbn6bsX7X2ecACLMACLMACLMACLMACLMACLMACLMACLMACrHAAS/uE/6Y6g5vnBHPLfFja8dS+CIrTnwFYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgGU1WG4eXqM9q2LjECgbs8qa9pum7KRWFAELsAALsAALsAALsAALsAALsAALsAALsAALsABLQZZQO6jaF1YIdYPWnsXUhKL29uf4QQewAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACscwLIxI2PjAhvhMvyiukBwy8FME3ZOZ/QBC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7BcB5aphqWpQZv6ztqHc2iCSDsc2hdB0RqABViABViABViABViABViABViABViABViABVhhC5amDa19OIxbMLERVLcsWuKWkwbAAizAAizAAizAAizAAizAAizAAizAAizAAixXg+VE5zcFpanGa6qzakJHUyZNe9u1MUtYnZ8BWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIDlOrA0IWHjnFumtrOmrFS4rRSuvQ1p6jOABViABViABViABViABViABViABViABViABViuBsstQ1pM7STtnZoMlJ3bwNTvCHVbC3mWELAAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AASztYNnYkTSsSu2UeJDevthxukGvfLoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWGEHlo2Nw1RH15RN1D7nlo0LgJjab9rbs/r5sAALsAALsAALsAALsAALsAALsAALsAALsAALsJjTXVe2RNNnaMrWhdvqzcyH5fxQJMACLMACLMACLMACLMACLMACLMACLMACLMACLKvBcstKyDZ2JO3zZmnKIGvvwJoO/LbvD8ACLMACLMACLMACLMACLMACLMACLMACLMACLKvBMpW90p7lqs5GTugMtwwX03SQUj+BH2ABFmABFmABFgFYgAVYgEUAFmABFmABFmCFGiwbV/I1NeeRG4ddEPaAoH0OL0fmwwIswCIAC7AAC7AAC7AAC7AIwAIswAIsArBsBMvNG9VUIwIsO1HS1Pltz/4BFmARgAVYgAVYgAVYgAVYgAVYgAVYgEUAVtiC5ZZVnp0AuirvdS6K0MihDux0p64uFE0ZAViAJYWntkr2irFSlHUGeQALsABLN1hFp9fL+TmNJf2l2yV346Li/+CMC7AAC7AUg5UXX1syxjSV04MbytnJj0nBkT0oBFiABVhawbpWchY29IHlK0Mby/kl46Uo5xwaAZZ9YJnaCE58rimMtYHlLWffanoBreJy5tUI8SSsQqQQtT8nOrqNC6gAFmBVCazcJTf4zq4uRstbMqf1loLjyWgFWIAFWHrA8pZzU5pcApa3pD/fRLI/myxFebmABViABVg6wPLE1ZX04TeViZbvMnFse8nb/TVgARZgAZZ5sLwla0bjcsEqKec+GiCF6UcBC7D0gRVuwGho5Jcbc789JFmegpCAlfffppK9arLvMjAYWukjmknOFzEiBXlhA5UTnVrrHG2agAYsy8HqM/IzaTH1e4nfl37FYOV/dYvvtcITByRzaq8Kz7Yy3uwk+UmbAQuwAAuwKhcD+i2S20etlT+/uVkeX7RXDmXkXjFYJeH5Ll7OjG4XHK4hjSRrwQtSdO60Y9s1Py9fzp/PBizAAiwbwerW6xOp/dZmH1p1JmyVyRuOiKegqAqXhI0DYUg9JUe7jZf9DR4LWlI7DRVPYmifkt+1c488N/g1afX3rnJjvTvlr3UipE7NVnLdNbf7yrP9RwMWYAGWjWB1fyxW2o383AdWSbnjw52y4VDmZYLV6KfXPPmSPmmZJP0pUvZe9WC5JekP3eR09CIpyg3tvax3354hda9t7cepdPHilXr4GGABlvNgOZ2F0zhHUSjA6t5jgdR7c1MAWldHb5YBcclyIiuv0mBlf5MoKc2eDQqVt6R2eU3yUo6HHIgpk2aXC1VJeW3MFLUHJE0ZRk1zvoXKF8ByC1jFpePznwWAVVJumLhNPtqeJoVFFYC1uoHs/fW/gkKV3OBJObd0Y5X21949+2X+3GUyacJMeX/yHPlizTrxeC5gmrQvRerXvsMP023Nu8jKFV/K2YxMyc31+EthYaH/PVlZ2bJh/fZKlW1bdgIWYAGWFrCiIudKo/EbykTLWzrMSZSEo1nBwSoHqn2/fUROvhwrhedyLvs7JmxPlAc69S3zbKl5k06++1XeGP7ceP//33RjBzmSelwyirHaunmHbN2yQ06dvDQTunvXvgrPyC7+LMACLMBSApa3PDBweblgeUvN6C0ycs0BST/yTaXBOtThZfH8cKhK+yh+1Vq5/i9ty0Wk5a2dfRm/oqIiueVvHf3/P6DfKHm670tSr1Yb//9572tFPjJIkn88CFiABVhuAMtbes3ZIdcUwxQMrsYT/yfzF/YVT3ytcsFKrttLzs7/usqzKR89kiYNr7/LD4YXn75PjJDXx74vfXqO8N08/8+ieF/dQwePBOBycUawdLm1cUdJTT1eJlg3XBfhOzsrKfVqtQYswLKrXqhB1ZTZLAusH3Yf9136tZ+dGBQtb+n8wQJJXB4RCNZvHpK0QdOlIP3K5sV6J3p6AFbrv90W8Prp0xlS+PONte8Tdl96RnTzvT7c3nx9qrRoel/Aa889O65MsEa/MingMzq27xESsLQOVamu9qz1BAawXAqWNwqKL7NmbDvuu+keDK1ab22SMXNelYz4W+Rg2xGSsy0pJJ0o8uGBfix6dBsStO6unXsD4Klfu40cSDnsf/3ggdTiS8sLN+SbNvonYAEWYLkJLG/k5+TLyqnr5IERa+TqCs62mk/+UuL3hO6J9Ye69PNj8cyTLwete/JkegA87SMiL6lzd7vIgDreDCNgARZguQSslI37ZV7PWIm59wNfGRM1V5qPXVfhZWLU4n1y+KznijvRiIuyfk0a3lN8CRh8hZ42LR/017/5xg6Sl3fhkQfvcJybi/9GyesN69/JGRZgAZYbwNqyNklWj13lhyqgdI6R3gOXS51SD5mWLnUnbJUpG49KXkHVV9PZtCEhAJN2rR+RTz6Oky2bd/hutvd/6pUAxN6JjgmoP3jgWDl27ITv7GvYkNcDXuvVYxhgAVb1bnxNi0aY2nGhjtJg9Xl8rkzrElM2Vj+XmV2ny8J5cdIyZmGFZ1veIT7fHsys8vcbPnR80EcNRr30rr+u95mr25p1rvDxhAZ12xWfRSY5CpaprLImKAELsEIO1huRc4JiFT9mlWQez5Q9p7ZKnxW3StePB0n9iV8FRct776t/XLKkZV3+mMH8/AJ5Y9z7ATfMS+Nz8VnWvr0pEtHq4XKxatG0k6xfdyHbCFiABViWgtU/ap5Mv39amVDN7xnru6dVEiVgeUuv5W0k4qMJUjM6+NmWN9s4KyHNl3283PA+tR7zwTzfA6FR3QbLgKdHybTif3ufvyodnlyPfLIgzvfg6H3/fEI63fOE9Ov9osyPXSpZWecD6p45c1Y+XbjSX75L2B3w+uerv/G/tmLZF4AFWIClBawJj866BKoPiy8PN83aKPm5+QHvuxisktJzaaTcN/eHCi8T756dKN8fy5JwD8ACLMCqIlhDi8+uSmO1YuQyST9Y9mMKZYE1KL6tb8X6+TtOSKP3tgdFy/sk/bDVKZKRUwBYgGUXWG6Zi0dDNqcqYEV1i5UpD830QxXbfbYkrd0XdEhNeWCVRHp2vgyN318MU/CzrcZTEmRR4qmwRMnUwcwtfbBKvx2w7Afrxcd/etZq+v1TZX3MOvFkVfwMVUVgeaOgsECejpsjNd8eGrTUn/iCfJ3yI2ABFmABVvAY0n+xTO06QxYP/FTS9qZV+n0VgbXh0E5pNq27/GL0bUHLvXMHS9Lpw5xhARZgAVbFMXX4Mtm1fIcUFV5e5q48sE6cPyO9lo6TX45pFRSquhM7y+LdX4b1fSrAAizAuszIyaraEJqywIpaEiF/jL47KFS/GttGhq15T855siUcArAsB8tUxs3UBnR6IQ6noiywGrwXERSrdrOeksS0ZCHMtl1TfdUJUAELsCoFVteFd5QL1TVvd5R/f7dSiqQIpQALsADLLFh941pI7QntLoHKex/rmZXRkp6diU6ABViApQOse2LbXoJVi5gesjl1NyoBFmABlh6wei9vKb8ff+Fy8Hfj75JJGxdIfmEBIgGWO8EytfGd+H5Ow+Y0WK1mXji7evTTFyX1bBoSVbLtmALBFGIahqQBVhiDFbXkH3LVuNbScMrDsubHjegEWIAFWHrBajm9g4xZ+6Hk5HuQCbAAC7D0gnXifJokp6ciEmABFmDpB4sArLAFy4mdpAmd6mwIhD1wae/8Ng4nAizAIgALsAALsAALsAALsAjAAizAAiwCsABLGQimGq+mObcIZ/a19gN1qPughvYMWIBFABZgARZgARZgARZgEYAFWIAFWARghQVYTvxgTfNXVefnEnZjpulAbaq/VSdigAVYBGABFmABFmABFmABFgFYgAVYgEUAltVgacLJ1Iq1mhqgE43SiU7jxD534mBmCkVNJxJObyvAAizAAizAAizAAizAAizAAizAAizAAizAAizXgaUpC6dpjiJTHc7GzJJ2PLXDq+nA6vTvBSzAAizAAizAAizAAizAAizAAizAAizAAizAshosTUMKtGdaNHUQUx3Oxm1vKmum6QBnU/YUsAALsAALsAALsAALsAALsAALsAALsAALsADLarBMNWjtGUZTmRu3DHMx1da0Z/U0gOBkOwUswAIswAIswAIswAIswAIswAIswAIswAIswAIsF3UGJ7J62ocxadqX2r9LuAEIWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWNUAllsam/ahEZo6jakskpuzpzZms00dqAELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlhMZPO2LD5iCSHvmVRN22r+zJpxszMADFmABFmABFmABFmABFmABFmABFmABFmABFmC5BixT2TVT2GnPfGlfpCDc5q9yc+Za6xAjwAIswAIswAIswAIswAIswAIswAIswAIswAIsq8FyItOifSVaG4dp2FhPe9vQPreZjVnWqvw9wAIswAIswAIswAIswAIswAIswAIswAIswAIs14GlKYOnfaiFqU5jY4ZMawdxEg7tC2yYOmkALMACLMACLMACLMACLMACLMACLMACLMACLMByDVjaG5abV5d28+INNs4FpWneMRtXsDY2HxZgARZgARZgARZgARZgARZgARZgARZgARZgAZZ2sLQ3Sicah1t+r6kO55bQPk+Ypow5YAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYLmoITjxXk1waJ+/StOq1po+w4n3ajooq5oPC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAy81gaYdNU8My9fdCvd9YhEIXlFqzooAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWFaDpT07pH0nac8waloIwdSiEdpXv7bxt1VnuwcswAIswAIswAIswAIswAIswAIswAIswAIswHIdWJqyf6FuCNqzk6bm4bJx+7k5k6u9HajKEgIWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYNkIlo0ZmVDvOFPzPtk4p5WNbUPDAgxuy+gbyxICFmABFmABFmABFmABFmABFmABFmABFmABFmABlq5GZOPQIaezOaaznW4BWlObBCzAAizAAizAAizAAizAAizAAizAAizAAizAAqwwBEvThP9uWViBYSnuWfnZ9gAswAIswAIswAIswAIswAIswAIswAIswAIswAoLsEL+pSycD8vUkBsntoumoUM2dkyGQAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAGWug1tKvPlBDDaF6vQhI5b5h1zoj1rOsAZW/kZsAALsAALsAALsAALsAALsAALsAALsAALsABLE1gEQRCqMq5sAoIgAIsgCAKwCIIALIIgCMAiCIIALIIgAIsgCEJn/B/u92LX9SrJTQAAAABJRU5ErkJggg==" } } }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "actions": { "confirm": "2024-02-07T23:59:53.310721Z" } } }' ``` 5. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the payment result from Bank 131. The `succeeded` status indicates a successful payment. The webhook also contains the customer's phone number. Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_123456789", "status": "accepted", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_12345678", // highlight-next-line "status": "succeeded", "created_at": "2024-02-07T23:59:52.977041Z", "finished_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "lucky", "contacts": [{ "phone": "7965*****85" }] }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "actions": { "confirm": "2024-02-07T23:59:52.977041Z", "capture": "2024-02-07T23:59:52.977041Z" }, "transaction_info": { "fp_message_id": "A50581324524670W0000040011450701" } } }' ``` ### How to make a refund via FPS To make refunds using the FPS, follow the [standard procedure](/payments/payment-refund.mdx). ### 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: ""session/start/payment"" note left URL to take customer back after payment: ""payment_options.return_url"" end note Partner Bank_131: ""200 OK"" Partner -> Bank_131: ""session/confirm"" 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: ""200 OK"" @enduml ``` --- - [Delayed capture payments](https://developer.131.ru/en/payments/payment-hold): Delayed payment deductions You can place a hold on the payment: first authorize or hold the amount of payment on the user’s card and then capture it with a separate request. There is time between the funds being put on hold and the funds being debited so you can send the order to the customer, for example. ### How it works All in all, all payments made with bank cards consist of two key phases: authorization (when the bank verifies if the needed amount is actually available and places a hold for this amount on the bank card, essentially blocking it) and capture (when the bank clears the payment and writes off the blocked or authorized amount from the bank card balance). There is almost no time gap between the two phases for the standard card payment flow, it looks immediate to the user. However, if you decide to use the delayed capture payment flow, you can decide on the timing when to capture the blocked funds. In this case the bank will not capture the amount immediately, but will do so on your command. It is possible to write off the full amount put on hold or a portion of it. :::info For MIT payments with [YooMoney wallets](/payments/p-yoomoney) you can only write off the full amount put on hold. ::: ### How to enable delayed capture Bank 131 manages the delayed capture feature. All your payments may have immediate or delayed capture. If captured immediately, the amount of payment will be cleared automatically right after the authorization. If you would like to perform delayed capture payments, please contact your Bank 131 manager. ### Hold period The money is held for up to **5 days**. If you do not debit or unblock it before the end of this period, the money will get unblocked automatically. If you need the money to be debited rather than unblocked after the hold period end, please contact your Bank 131 manager. ### Later capture payment scenario To create a delayed capture payment, complete the following steps: 1. Create a payment session that is separate from the actual payment ([`session/create`](/reference/reference-methods.mdx#sessioncreate)) or a single combined session ([`session/init/payment`](/reference/reference-methods.mdx#sessioninitpayment)). 1. If you have created the session separately from the start of the payment, send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request. 1. Bank 131 will then send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook, which means that the Bank is ready to perform the payout and is waiting for your confirmation. 1. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). 1. If you get an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook from Bank 131, this means that you will need to take additional action to perform the payment. For instance, the user might need to go through 3D Secure. Redirect the user to the address for 3D Secure. 1. Wait for a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook from Bank 131. It means the required amount is held on the bank card successfully. It can be captured immediately or later. You can capture the full amount or a portion of it—see [`amount_details`](/reference/reference-objects.mdx#amount_details). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CAPTURE) { $session = $hook->getSession(); //do your logic here } ``` 2. Capture the full amount that is on hold, a portion of the amount ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)), or decline the payment ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). 3. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. 1. Complete [Steps 1–5](/payments/payment-with-form). > If you receive an `action_required` webhook, send the HTTP 200 OK in response—the user will be redirected for 3D Secure within the widget. 1. Wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook from Bank 131. It means the required amount is held on the bank card successfully. It can be captured immediately or later. You can capture the full amount or a portion of it—see [`amount_details`](/reference/objects#amount_details). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CAPTURE) { $session = $hook->getSession(); //do your logic here } ``` 2. Capture the full amount that is on hold, a portion of the amount ([`session/capture`](/reference/methods#sessioncapture)), or decline the payment ([`session/cancel`](/reference/methods#sessioncancel)). 3. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. ### Sequence diagram ![Payment diagram with holding](/img/docs/payments/schema_payment_hold_en.png) ```plantuml @startuml PaymentHold 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 ``` ![Payment diagram with holding](/img/docs/payments/schema_payment_with_form_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 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 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 You can send a payment as single request, with no interim steps (if they are not necessary). You will shortly get the payment result in response. This option can work if you don't use the [payment form widget](/payments/widget-payment.mdx) Here, a payment with immediate capture is described. [More about delayed capture payments >](/payments/payment-hold.mdx) ### How to enable For such payments, there is a special method, [`session/init/payment/sync`](/reference/reference-methods.mdx#sessioninitpaymentsync). Inform the Bank 131 manager that you want to use it. In this case, **you will not receive webhooks** from Bank 131. You can learn the transaction status with the [`session/status`](/reference/reference-methods.mdx#sessionstatus) request. ### How to perform a payment Send a [`session/init/payment/sync`](/reference/reference-methods.mdx#sessioninitpaymentsync) request. >Please be aware that we do not recommend implementing this method unless you have already used it before. In the `type` field of the `payment_details` object, specify `card`. In the [`bank_card`](/reference/reference-objects.mdx#bankcard) object, specify user bank card details. In the `payment_options.return_url` field, specify the address to which the user should be redirected after the payment is processed (**it is required**). The payment result will be returned in response to the request in the `status` field of the `payments`/`payout_list` array: - `succeeded` – the payment has completed successfully - `failed` – the payment has not gone through because of an [error](/reference/reference-errors.mdx) - `pending` – the user needs to go through 3D Secure verification [More about the payment statuses >](/reference/reference-objects.mdx#payment_status) Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment/sync \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "card", "card": { "type": "bank_card", // highlight-start "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "123" } // highlight-end } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" } }' ``` ### If no result is returned Sometimes, the final payment status is not returned in response to a request. For instance, if a payment is being processed for a very long time or the user card requires 3D Secure. #### Too long payment If payment processing lasts more than 40 seconds, the `in_progress` intermediate [payment status](/reference/reference-objects.mdx#payment_status) will be included in the response. To learn the final payment status, send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request. #### 3D Secure card If a user card requires 3D Secure, [redirection details](/reference/reference-objects.mdx#redirect) will be returned in response to the request. Redirect the user to `customer_interaction.redirect.url`. After that, send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request to learn the final payment status. --- - [Payments by bank cards](https://developer.131.ru/en/payments/payment-pcidss): Payments by bank cards for services collecting and storing bank card details on their side 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 ```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 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { // highlight-start "type": "card", "card": { "type": "bank_card", // highlight-start "bank_card": { "number": "2200774546102058", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } // highlight-end } }, "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; 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_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": "2058", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { $session = $hook->getSession(); //do your logic here } ``` ### 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` ### Step 5. Wait for a webhook 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": { // highlight-next-line "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::ACTION_REQUIRED) { $session = $hook->getSession(); //do your logic here } ``` ### 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 user 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": "token_value", // highlight-next-line "initiator": "client" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" } }' ``` 1. Wait for an [`action_required`](/reference/webhooks#action_required) webhook from Bank 131 that contains the [customer redirect data](/reference/objects#redirect). Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "GET", "qs": { "foo": "bar" }, "params": { "paReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } } }] } }' ``` 3. Redirect the customer to the URL passed as `customer_interaction.redirect.url`. Note that the redirect method can be GET or POST. 4. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131. The webhook contains the recurring payment status information. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "recurrent": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "rub" } }] } }' ``` 5. Note that after completion of 3D Secure verification, the customer returns to the URL that was passed as `return_url`. According to the method used, POST or GET, you might be required to convert the POST format to GET to avoid possible format processing issues. ### 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 Partner: ""action_required"" note left Settings for 3DS verification end note Bank_131 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 1. Create a payment session [`session/create`](/reference/reference-methods.mdx#sessioncreate). 2. Send a payment request using the [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) method. The `payment_options.recurrent` parameter contains the `true` value. 3. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook to confirm the payment with [`session/confirm`](/reference/reference-methods.mdx#sessionconfirm) or cancel the payment with [`session/cancel`](/reference/reference-methods.mdx#sessioncancel). 4. Wait for an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook. The `customer_interaction.inform.qr.content` parameter contains a deeplink which you can either display to the customer as QR code in a web browser, or use it to forward the customer to the issuer's mobile application. 5. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the transaction result from Bank 131. In case of a successful transaction, the webhook will contain `status=accepted` (`session` object) and `status=succeeded` (`payments`/`payout_list` array) along with a recurring token within the `recurrent.token` parameter. If the transaction fails, the webhook will contain `status=cancelled` (`session` object), `status=failed` (`payments`/`payout_list` array), and no recurring token. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_713610", // highlight-next-line "status": "accepted", "created_at": "2024-08-08T08:06:51.841432Z", "updated_at": "2024-08-08T08:14:56.168219Z", "acquiring_payments": [{ "id": "pm_308906", // highlight-next-line "status": "succeeded", "created_at": "2024-08-08T08:06:51.931193Z", "finished_at": "2024-08-08T08:14:55.996273Z", "customer": { "reference": "user123", "contacts": [{ "phone": "7123*****45" }] }, "payment_details": { "type": "faster_payment_system" }, "recurrent": { // highlight-next-line "token": "6a6a29c4193a8e1049231e1497a3c5f180e120b20db81b39f53ec478029b53cf", "created_at": "2024-08-08T10:10:27+03:00", "finished_at": "2034-08-08T10:10:27+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 1000, "currency": "RUB" }, "amounts": { "net": { "amount": 1000, "currency": "RUB" }, "gross": { "amount": 1000, "currency": "RUB" } } }], "actions": { "confirm": "2024-08-08T08:06:52.184593Z", "capture": "2024-08-08T08:14:55.699095Z" } } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_713610", // highlight-next-line "status": "cancelled", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "acquiring_payments": [{ "id": "pm_308906", // highlight-next-line "status": "failed", "created_at": "2022-03-01T11:57:31.895773Z", "finished_at": "2022-03-01T11:57:31.895773Z", "customer": { "reference": "user123" }, "payment_details": { "type": "faster_payment_system" }, "amount_details": { "amount": 229600, "currency": "RUB" }, "amounts": { "fee": { "merchant_fee": { "amount": 1607, "currency": "RUB" } } }, "metadata": { "parent_session_id": "ps_1667788995" }, "error": { "description": "QR expired", "code": "qr_expired" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "error": { "description": "Session cancelled", "code": "session_cancelled" }, "actions": { "confirm": "2022-03-01T11:57:31.895773Z" } } }' ``` Diagram ![](/img/docs/payments/recurring_fps_en.png) ### How to get a token for recurring payments without charging To get a token for recurring payments via FPS without charging, you need to complete [all the standard steps required to make a payment via FPS](#with_charge). When sending a [`session/start/payment`](/reference/methods#sessionstartpayment) or [`session/init/payment`](/reference/methods#sessioninitpayment) request, specify `"type": "faster_payment_system_binding"` and `"recurrent": true`. In the `amount_details` object specify 1 ruble (the amount will not be charged). The `payment_finished` webhook will return a token for recurring payments. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "faster_payment_system_binding" }, "amount_details": { "amount": 100, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` Once you have a token, accept recurring payments in a standard way. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` ### How to create multiple FPS subscriptions for the same payer and bank Each time an SBP subscription is additionally created for the same payer and the same issuing bank, the bank may show a message saying: "You have already linked an account." This confuses the payer, who cannot tell whether a new subscription was actually created. To allow an unlimited number of unique subscriptions to be created correctly and to avoid the confusion described above, it is necessary to additionally pass the [`subscription_service_info`](/reference/objects#subscription_service_info) object containing the subscription identifier and name. To enable this functionality, please contact your manager at Bank 131. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "faster_payment_system", "faster_payment_system": { // highlight-start "subscription_service_info": { "id": "54f731a9f86b46188b7961cb933fb3ff", // subscription identifier "name": "subscription2" // subscription name } // highlight-end } }, "amount_details": { "amount": 1000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` --- - [MIT recurring payments](https://developer.131.ru/en/payments/payment-recurring): MIT recurring payments A recurring payment (or repeated payment) enables you to accept a payment and debit money in the following ways: - With a token, without involving the user, those recurring payments are called **Merchant Initialized Transaction** (MIT). - Requesting 3D Secure verification from the user, those recurring payments are called **Customer Initialized Transaction** (CIT). This page only overlooks the MIT recurring payments. [Learn more about CIT recurring payments >](/payments/payment-recurring-cit.mdx) Recurring payments are currently supported for bank cards and the methods below. Other options will be available later. [How to make recurring payments via FPS >](/payments/payment-recurring-fps) [How to make recurring payments via SberPay >](/payments/payment-sber-pay#r-payments) [How to make recurring payments via T-Pay >](/payments/payment-tpay#r-payments) [How to make recurring payments via YooMoney >](/payments/p-yoomoney#r-payments) **How to create a recurring payment** 1. [Obtain the user's consent](#agreement) to recurring payments. 2. [Perform a successful payment](#first_payment) that will recur, and get a [token](#token). 3. [Perform payments using this token](#recurring_payment). ## User consent ### Why you need it Recurring payments are pre-authorized by a user and can be made without any future confirmation from them. The user only sees funds debited from their card. This is why you assume full responsibility for such payments: their amount, frequency, and user's consent to them. You need user's consent for dispute situations (e.g. if the user complaints about an unauthorized debit). ### How to obtain user's consent You can do it in any way you find convenient. The main point is that you need to verify the user had been aware of automatic debits when they made the first payment, and agreed to them. How to do it: 1. Describe the payment terms to make sure the user will read them. 2. Ask the user to confirm they understand and agree to the terms (e.g. add an unambiguous checkbox like **Save card**, **Enable automatic payments**, **Enable recurring donations**, etc.). If the user checks the box, thus verifying their consent, recurring payments become enabled. If they don't, recurring payments are not activated. The checkbox can be on your side (in this case, you will decide how it looks and where it is located) or on our side—in our [payment widget](#first_payment). ## Token for recurring payments You need to perform one payment successfully, selecting the option to save bank card details. In response to this payment, you will receive a [token](/reference/reference-objects.mdx#recurrent_token_info). This token can be saved and used to accept future payments. ### How to get a token **When creating a payment session** Send `recurrent=true` (in [`payment_options`](/reference/reference-objects.mdx#payment_options)). You can do this when [creating a payment session](/reference/reference-methods.mdx#sessioncreate) or in any payment request. If such a payment is successfully performed, you will receive a token for recurring payments with which you will be able to repeat the payment. > In this case, you need to get the user's consent on your side beforehand. **In our payment widget** If you perform a payment with the widget, you can show the **I agree to recurring payments** checkbox to the user. If the user ticks this checkbox and the payment is performed successfully, you will receive a token for recurring payments. :::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 Send a [`token/info`](/reference/reference-methods.mdx#token_info) request. In the `type` parameter, pass `recurrent_token`, in the `recurrent_token.token` parameter, pass the token. In return, you will get [`info`](/reference/reference-objects.mdx#info_recurrent) with the date of token expiration (`finished_at`) and status (`is_active`). The token expiration setting (`finished_at`) isn't processed by the Bank, i.e. the token will remain active even after the specified expiration date. If `is_active: true`, you can perform payments with this token. Please note that an active token won't guarantee a successful payment, since the payment can be, for some reason, rejected by the card issuer. **How to disable a token** If you don't want to use a token for payments anymore (e.g. a user disabled recurring payments), send a [`recurrent/disable`](/reference/reference-methods.mdx#recurrentdisable) request. In response, you will receive [`recurrent`](/reference/reference-objects.mdx#recurrent_token_info). If `is_active: false`, it means the token is disabled and you cannot perform payments with this token anymore. > After the token is disabled, the token expiration setting (`finished_at`) may contain a date of the year 2000. This value won't affect anything, so please disregard it. ## How to accept recurring payments ### Step 1. Successfully perform a payment with an instruction to create a token >[How to make a payment without our widget >](/payments/payment-pcidss.mdx) When creating a payment session or sending a payment request, pass `true` in the `recurrent` parameter of the [`payment_options`](/reference/reference-objects.mdx#payment_options) object. Example of a payment request with an instruction to create a token ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "087" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-next-line "recurrent": true } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); // highlight-next-line $paymentOptions->setRecurrent(true); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '01', '22', '087')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayment($request); ``` >[How to make a payment with our widget >](/payments/payment-with-form.mdx) If you perform a payment with our widget, you can show the user the **I agree to recurring payments** checkbox. To do this, in the [widget token creation request](/reference/reference-methods.mdx#token), pass `true` in the `show_recurrent_checkbox` field. > This is optional. You can obtain the user's consent earlier, pass `recurrent: true` when creating a payment session, and show the user the widget with no checkboxes—the same as for one-time payments. Example of creating a token for the widget with a checkbox to agree to recurring payments ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_34851", // highlight-next-line "show_recurrent_checkbox": true } }' ``` Then, [create a payment form](/payments/widget-payment.mdx) with this token. If the user ticks the **I agree to recurring payments** checkbox (i.e. agrees to enable recurring debiting from their card), you will receive a token. Example of a widget with an option to enable or disable recurring payments ![Recurring payment widget](/img/docs/payments/payment_form_recurrent_en.png) ### Step 2. Save the token If the payment is performed successfully (and the user enables recurring debiting when paying through the form), you will get the token in the [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "recurrent": { "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": true, "type": "recurrent_token" }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "recurrent": true } }] } }' ``` ### Step 3. Accept payments using the token Send a request to accept a payment with the `recurrent` payment type. Instead of a bank card, pass the token you saved after the previously accepted payment. Example of a request for a recurring payment ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Customer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->initPaymentSession() // highlight-next-line ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39') ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->build(); $response = $client->session()->initPayment($request); ``` --- - [Refunds](https://developer.131.ru/en/payments/payment-refund): Total, partial refunds, and refunds from reimbursements You can return a successful payment to the sender as follows: - Within the **refund** operation – this is the most commonly encountered situation, the payment can be returned totally or partially. - Within the **chargeback** procedure – this procedure cannot be initiated by the client, a notification about it is sent by Bank 131. In this case, the amount is withdrawn from the compensation. In both cases, a record is added to the [registry](/finance/finance-payment-daily-report.mdx). :::info[] A refund cannot be undone. Please make sure this action is necessary. ::: ### How to perform a refund #### Step 1. Send a refund request >Please note that you can only send a request for a **refund**, not a **chargeback**. To perform a refund, send a [`session/refund`](/reference/reference-methods.mdx#sessionrefund) request. In the `session_id` field, pass the identifier of the [payment session](/reference/reference-objects.mdx#payment_session) for the payment you need to refund. In `amount_details.amount`, specify the amount of the refund. If you leave this blank, the money will be refunded in full (i.e. for the full amount of the payment in question). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->refundSession('ps_3230') ->build(); $response = $client->session()->refund($request); ``` #### Step 2. Wait to be notified of the results of the refund After the refund has been issued, Bank 131 will send you a [`payment_refunded`](/reference/reference-webhooks.mdx#payment_refunded) webhook with the results. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "amount_details": { "amount": 1000, "currency": "rub" } }], "transaction_info": { "fp_message_id": "A50581324524670W0000040011450701" } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_REFUNDED) { $session = $hook->getSession(); //do your logic here } ``` If a commission was paid during payment, it is never returned in case of a refund. --- - [SberPay](https://developer.131.ru/en/payments/payment-sber-pay): Payments via SberPay This scenario describes how to receive payments via SberPay. These payments, one-time and recurring, do not require card details from customers. >You should confirm a payment within 20 minutes by sending [`session/confirm`](/reference/methods#sessionconfirm). Otherwise, the session terminates within 20 minutes with the `canceled` status. ### Payment scenario The payment scenario depends on the customer's payment channel: mobile application (app), mobile browser (mobile_web), or desktop browser (web). 1. Create a 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 `onlineios-app://sbolpay/...` deeplink. 2. Wait 50ms. 3. Reload the page to hide a possible alert if the deeplink could not open properly. 4. Redirect back to your page with the new request settings. 5. Open the `startonline://sbolpay/...` deeplink. 6. Wait 50ms. 7. Reload the page to hide a possible alert if the deeplink could not open properly. 8. Redirect back to your page with the new request settings. 9. Open the `onlineappmobile://sbolpay....` deeplink. 10. Wait 50ms. 11. Reload the page to hide a possible alert if the deeplink could not open properly. 12. Redirect back to your page with the new request settings. 13. Open the `budgetonline-ios://sbolpay/...` deeplink. 14. Wait 50ms. 15. Reload the page to hide a possible alert if the deeplink could not open properly. 16. Redirect back to your page with the new request settings. 17. Open the `btripsexpenses://sbolpay/...` deeplink. 18. Wait 50ms. 19. Reload the page to hide a possible alert if the deeplink could not open properly. 20. Redirect back to your page with the new request settings. 21. Open the `ios-app-smartonline://sbolpay/...` deeplink. 22. Wait 50ms. 23. Reload the page. 24. Follow the deeplink to the Sber landing page. 6. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the `return_url` parameter. 7. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the transaction results. You can also send requests (no more than once in 5 seconds) to obtain the transaction status. >If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the customer's order expires. 8. Pass the transaction status to the customer. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "sber_pay", "sber_pay": { "phone": "71234567890", // highlight-next-line "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://t.me/bank131" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` 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 `onlineios-app://sbolpay/...` deeplink. 2. Wait 50ms. 3. Reload the page to hide a possible alert if the deeplink could not open properly. 4. Redirect back to your page with the new request settings. 5. Open the `startonline://sbolpay/...` deeplink. 6. Wait 50ms. 7. Reload the page to hide a possible alert if the deeplink could not open properly. 8. Redirect back to your page with the new request settings. 9. Open the `onlineappmobile://sbolpay....` deeplink. 10. Wait 50ms. 11. Reload the page to hide a possible alert if the deeplink could not open properly. 12. Redirect back to your page with the new request settings. 13. Open the `budgetonline-ios://sbolpay/...` deeplink. 14. Wait 50ms. 15. Reload the page to hide a possible alert if the deeplink could not open properly. 16. Redirect back to your page with the new request settings. 17. Open the `btripsexpenses://sbolpay/...` deeplink. 18. Wait 50ms. 19. Reload the page to hide a possible alert if the deeplink could not open properly. 20. Redirect back to your page with the new request settings. 21. Open the `ios-app-smartonline://sbolpay/...` deeplink. 22. Wait 50ms. 23. Reload the page. 24. Follow the deeplink to the Sber landing page. 5. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the `return_url` parameter. 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook from Bank 131 with the transaction results. You can also send requests (no more than once in 5 seconds) to obtain the transaction status. >If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the customer's order expires. 7. Pass the transaction status to the customer. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "sber_pay", "sber_pay": { "phone": "71234567890", // highlight-next-line "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "mobile_web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://t.me/bank131" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` 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": { // highlight-start "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "web" // highlight-end } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { // highlight-next-line "return_url": "https://131.ru" } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-09-29T05:42:10.549869Z", "updated_at": "2023-09-29T05:42:10.948457Z", "acquiring_payments": [{ "id": "pm_131", "status": "in_progress", "created_at": "2023-09-29T05:42:10.973559Z", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "order123", "payment_options": { "return_url": "https://t.me/bank131", "recurrent": false } }] } } ``` ### Sequence diagram Show diagrams ![](/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: ""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 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 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 Sber: sends PUSH Bank_131 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 ``` ![](/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: ""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 Customer: payment rejected by Sber \n or no customer's activity \nwithin 20 minutes 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 Sber: send PUSH Bank_131 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 ``` ![](/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: ""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 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 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 Sber: send PUSH Bank_131 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 Code example for selection logic implementation ```c showLineNumbers const openOnlineiosApp = () => { window.location.href = "onlineios-app://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openStartOnline = () => { window.location.href = "startonline://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openAppOnline = () => { window.location.href = "onlineappmobile://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openBuget = () => { window.location.href = "budgetonline-ios://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openBtripExp = () => { window.location.href = "btripsexpenses://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openAppSmart = () => { window.location.href = "ios-app-smartonline://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0"; }; const openLandingpage = () => { window.location.href = "https://www.sberbank.ru/ru/person/payments/online_sberpay"; }; const clearMessage = () => { window.location.href = "./same_page.html"; }; if (platform == "android") { setTimeout(openSberpay, 100); clearMessage(); setTimeout(openLandingpage, 800); } else if (platform == "iPhone") { setTimeout(openOnlineiosApp, 50); clearMessage(); setTimeout(openStartOnline, 50); clearMessage(); setTimeout(openAppOnline, 50); clearMessage(); setTimeout(openBuget, 50); clearMessage(); setTimeout(openBtripExp, 50); clearMessage() setTimeout(openAppSmart, 50); clearMessage(); setTimeout(openLandingpage, 800); } ``` ### Recurring payments >CIT recurring payments via SberPay are not supported. To make [MIT recurring payments](/payments/payment-recurring) via SberPay: 1. Get a token by sending `recurrent=true` (in the [`payment_options`](/reference/objects#payment_options) object) in the request. If the payment is successful, you will get the token in the [`payment_finished`](/reference/webhooks#payment_finished) webhook in the `recurrent.token` parameter. Example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "return_url": "https://t.me/bank131", // highlight-next-line "recurrent": true } }' ``` 2. Use the token to make recurring payments. Example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", // highlight-next-line "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" } }' ``` --- - [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 `canceled` 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 const publicToken = 'publicToken'; // public token from the token request document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131SberPayPayment) { return; } const widget = new Bank131SberPayPayment(publicToken); widget.onReady = function () { console.log('SberPayPayment is ready.'); }; widget.onSberPayStart = function () { console.log('SberPayPayment started.'); }; widget.onSberPayFail = function (error) { console.log('SberPayPayment failed', error); }; widget.onSberPaySuccess = function () { console.log('SberPayPayment succeeded.'); }; widget.render(); }); ``` ### 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 [payout form widget](/payments/widget-payment.mdx), you will need to send a request for token creation to access the JavaScript library. >3. Show the widget to the user and obtain their card details. 4. **If you are not using the widget** and have created the session separately from the start of the payment, you need to send a [`session/start/payment`](/reference/reference-methods.mdx#sessionstartpayment) request. 5. Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook, which means that the Bank is ready to make the payment and is waiting for your confirmation. 6. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). >#### These steps are necessary only when paying without the widget >7. If you are making a payment without a payment form, Bank 131 will send you an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook. This means that you will need to take additional action to perform the payment. For instance, the user might need to go through 3D Secure. >8. Redirect the user to the address for payment confirmation (3D Secure). >#### These steps are only required for delayed capture payments >Upon a delayed capture payment, funds are frozen on the user card and debited on your command. If you don't want to perform delayed capture payments, you can skip these steps. To follow this scenario, contact a Bank 131 manager. >9. Bank 131 will send you a [`ready_to_capture`](/reference/reference-webhooks.mdx#ready_to_capture) webhook. This means the funds to be used for the payment are frozen on the user's bank card. >10. Debit the captured amount ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) or cancel the hold ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). 11. Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook containing the result of the payment. If the status is `succeeded`, this tells you that the payment was successful. ## Payment statuses The status of the payment is returned in the `status` field of the [`acquiring_payments`/`payment_list`](/reference/objects#payment_status) array. To query it, wait for a webhook from Bank 131 or send a [`session/status`](/reference/reference-methods.mdx#sessionstatus) request with the identifier of the session containing this payment. --- - [Payments via T-Pay](https://developer.131.ru/en/payments/payment-tpay): Payments via T-Pay During payments via T-Pay the payer authentication is performed through logging into the T-Bank app. 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. 1. Create a session separately using the [`session/create`](/reference/methods#sessioncreate) method and then start the payment ([session/start/payment](/reference/methods#sessionstartpayment)), or create a session along with the payment using the [`session/init/payment`](/reference/methods#sessioninitpayment) method. Pass all the required parameters: - Pass the `tpay` value in the `type` parameter of the [`internet_banking`](/reference/objects#internet_banking) object. - Pass the `mobile` value in the `type` parameter of the [`platform_details`](/reference/objects#platform_details) object. Specify one of the acceptable values in the `os` and `browser` parameters. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { // highlight-next-line "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-start "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } // highlight-end } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:14:28.236854Z", "updated_at": "2025-09-05T07:14:28.298522Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-05T07:14:28.310910Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 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": { // highlight-next-line "url": "https://o.tbank.ru/tpay/3000000000000021275", "base_url": "https://o.tbank.ru/tpay/3000000000000021275", "method": "GET", "params": {} } } }], "actions": { "confirm": "2025-09-05T07:49:24.148058Z" } } }' ``` 5. Forward the 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 `canceled` 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. 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": { // highlight-next-line "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { // highlight-start "platform_details": { "type": "desktop", "os": "windows", "browser": "chrome" } // highlight-end } }' ``` 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": { // highlight-next-line "url": "https://www.tinkoff.ru/tpay/3000000000000021275", "base_url": "https://www.tinkoff.ru/tpay/3000000000000021275", "method": "GET", "params": {} } } }], "actions": { "confirm": "2025-09-05T07:49:24.148058Z" } } }' ``` 5. 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 `canceled` 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 ![](/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: ""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 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 ``` ![](/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: ""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 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 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": { // highlight-next-line "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 ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", "initiator":"merchant" // highlight-end } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "android", "browser": "chrome" } } }' ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3812845", "status": "in_progress", "created_at": "2025-09-03T11:04:27.322539Z", "updated_at": "2025-09-03T11:04:27.381848Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-03T11:04:27.394705Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } ``` ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", "initiator":"client" // highlight-end } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } } }' ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-03T11:04:27.322539Z", "updated_at": "2025-09-03T11:04:27.381848Z", "acquiring_payments": [{ "id": "pm_2769254", "status": "in_progress", "created_at": "2025-09-03T11:04:27.394705Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } ``` ### How to make a refund To make refunds using T-Pay, follow the [standard procedure](/payments/payment-refund.mdx). --- - [Payments using our payment form](https://developer.131.ru/en/payments/payment-with-form): Payments for those who do not store card details on their side This scenario describes how to perform a payment to a bank card through the payment form. You should consider this option if you decided not to collect bank card details and not to store them on your side. You can obtain tokenized card details using the [payment form widget](/payments/widget-payment.mdx) and then perform the payment securely. > This scenario does not include the payment capture step. [How to make a delayed capture payment](/payments/payment-hold) 1. Create a payment session ([`session/create`](/reference/reference-methods.mdx#sessioncreate)). You will receive a payment session identifier in response. [More about request format >](/reference/reference-format.mdx) Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPaymentSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` 2. Generate a public token to work with the widget. Send a [`token`](/reference/reference-methods.mdx#token) request specifying in it the session identifier and the type of the widget you are going to call. You will receive a token in response. > If you want to add the checkbox **Enable Automatic Payments** to the payment form, specify `true` in the `show_recurrent_checkbox` field. It's required to perform [recurring debiting](/payments/payment-recurring.mdx). Request example ```json showLineNumbers curl -X POST \ 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 showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setAcquiringWidget( 'test_ps_id', 'https://success.url', 'https://failed.url', false ) ->build(); $publicTokenResponse = $client->widget()->issuePublicToken($request); $publicToken = $publicTokenResponse->getPublicToken(); ``` 3. Show the payment form to the recipient. To do this, you need to access our JavaScript library and add the payment form widget. The customer enters their card details and clicks **Pay**, and Bank 131 initiates the payment, without getting you involved. [How to add the payment form >](/payments/widget-payment.mdx) 4. Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook—this means that the payment can be performed and the Bank is waiting for you to confirm (or cancel). The webhook body will contain all the data needed for the payment, which you need to check. You then reply with the 200 HTTP code. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { $session = $hook->getSession(); //do your logic here } ``` 5. Confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payment. >If you receive an `action_required` webhook, send the HTTP 200 OK in response—the user will be redirected for 3D Secure within the widget. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` 6. Wait for a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The webhook body will contain all the details of the payment. The result of the payment can be found in the `status` field of the `acquiring_payments/payment_list` array. If the status is `succeeded`, then the payment has been successful. If the status is `failed`, then the payment has not been completed because of an [error](/reference/reference-errors.mdx). [More about the payment statuses >](/reference/reference-objects.mdx#payment_status) ### 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 user 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 ``` --- - [Payments with YooMoney wallets](https://developer.131.ru/en/payments/p-yoomoney): Payments with YooMoney wallets You can accept payments with YooMoney wallets, including: - [one-time payments](#yoo_payment) - [recurring payments](#r-payments) - [delayed capture payments](/payments/payment-hold) Payments made with YooMoney wallets are refunded in [a standard way](/payments/payment-refund). ### How to make a payment All parameters are passed in plain text. Do not use our widgets. 1. Send a [`/session/init/payment`](/reference/methods#sessioninitpayment) request. Optionally, you can pass a URL in `payment_options.return_url` for redirecting the payer back after the payment. >The payment amount limits depend on the [YooMoney wallet level](https://yookassa.ru/docs/support/payments/limits). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} // highlight-end } }, "amount_details": { "amount": 25420, "currency": "rub" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, // highlight-start "payment_options": { "return_url": "https://www.131.ru", "description": "description" // highlight-end } }' ``` 2. Wait for a [`ready_to_confirm`](/reference/webhooks#ready_to_confirm) webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:33:46.290108Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "next_action": "confirm" } }' ``` 3. Confirm ([`session/confirm`](/reference/methods#sessionconfirm)) or cancel ([`session/cancel`](/reference/methods#sessioncancel)) the payment. 4. Wait for an [`action_required`](/reference/webhooks#action_required) webhook from Bank 131 and redirect the payer using the link from `customer_interaction.redirect.url`. :::info After the `action_required` webhook arrives, the payer has 20 minutes to confirm the payment. ::: Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:34:31.887997Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, // highlight-start "customer_interaction": { "type": "redirect", "redirect": { "url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=309d1fd7-000f-5001-8000-1e9f64506f41", "base_url": "https://yoomoney.ru/checkout/payments/v2/contract", "method": "GET", "qs": { "orderId": "309d1fd7-000f-5001-8000-1e9f64506f41" }, "params": {} } }, // highlight-end "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z" } } }' ``` 5. If you make delayed capture payments, wait for a [`ready_to_capture`](/reference/webhooks#ready_to_capture) webhook and then either confirm ([`session/capture`](/reference/methods#sessioncapture)) or cancel ([`session/cancel`](/reference/methods#sessioncancel)) the capture. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:44:33.115425Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "next_action": "capture", "actions": { "confirm": "2025-11-05T08:34:31.626530Z" } } }' ``` 6. Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook. See the payment results in the `status` parameter of the `acquiring_payments/payment_list` array. If the status is `succeeded`, the payment was successful. If the status is `failed`, an [error](/reference/errors) occurred during the payment. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3821809", "status": "accepted", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:45:19.857746Z", "acquiring_payments": [{ "id": "pm_2775568", // highlight-next-line "status": "succeeded", "created_at": "2025-11-05T08:33:46.190121Z", "finished_at": "2025-11-05T08:45:19.781451Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z", "capture": "2025-11-05T08:45:18.934056Z" } } }' ``` ### Recurring payments >CIT recurring payments with YooMoney wallets are not supported. To make [MIT recurring payments](/payments/payment-recurring) with YooMoney wallets: 1. Get a token by sending `recurrent=true` in the [`payment_options`](/reference/objects#payment_options) object. If the payment is successful, you will get the token in the [`payment_finished`](/reference/webhooks#payment_finished) webhook in the `recurrent.token` parameter. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-start "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} // highlight-end } }, "amount_details": { "amount": 25420, "currency": "rub" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_options": { "return_url": "https://www.131.ru", "description": "description", // highlight-start "recurrent": true // highlight-end } }' ``` 2. Use the token to make recurring payments. Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { // highlight-next-line "type": "recurrent", // highlight-next-line "recurrent": { // highlight-next-line "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] } }' ``` ### Sequence diagram ![](/img/docs/payments/yoomoney_en.png) ```plantuml @startuml autonumber "[00]" skinparam maxMessageSize 200 actor Payer participant Partner participant Bank_131 participant YooMoney Payer->Partner: chooses YooMoney as a payment method Partner->Bank_131: ""session/init/payment"" note left URL for redirecting the payer back after the payment in ""payment_options.return_url"" end note PartnerBank_131: http 200 Partner->Bank_131: ""session/confirm"" PartnerBank_131: http 200 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 PayerBank_131: http 200 Partner->Bank_131: ""session/capture"" PartnerBank_131: http 200 @enduml ``` --- - [Payment form widget](https://developer.131.ru/en/payments/payment-widget): Conducting payments with the widget You can use the payment form widget to perform payouts. You add the widget to the page, show it to the user, and the user then interacts with the widget, going through all the payment steps from beginning to end. The user first securely enters their card details, and then sees a message telling them that the payment has been successful (or an error message if anything goes wrong). You need to create a payment session, and the widget does the rest: it will send the payment request, redirect the user to the appropriate address, and show them the screen with the result of the operation. [How to perform a payment through the payment form >](/payments/payment-with-form.mdx) ### What the widget looks like ### Code example: a page with a widget ```html showLineNumbers Payment form widget document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131PaymentForm) { return; } const paymentForm = new Bank131PaymentForm('publicToken', { isCvcMasked: true, hideCardHolderField: false, customerInteractionRedirect: { target: "_blank", }}); paymentForm.render(); }); ``` ### How to add a widget to a page #### 1\. Link the scripts and styles ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2\. Add a container with the widget ```html showLineNumbers ``` #### 3\. Create an instance of the widget Once the script is linked to the page, the `Bank131PaymentForm` class will appear in the global scope. To create the payment form, pass the public token obtained to work with the widget to the constructor (the [`token`](/reference/reference-methods.mdx#token) method). ```js showLineNumbers const paymentForm = new Bank131PaymentForm('public token'); ``` To display the payment form, call the `render()` method: ```js showLineNumbers paymentForm.render(); ``` ### Widget API #### `Bank131PaymentForm` Payment form class constructor. ```js showLineNumbers const paymentForm = new Bank131PaymentForm(publicToken[, options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------- | | `publicToken` | string | Mandatory. Public token | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the form will be inserted. Default value: ``| #### Method: `paymentForm.render()` The method displays the form on the page, in the container defined by the `options.container` parameter. ```js showLineNumbers paymentForm.render([options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | --------------------------------------------------- | | `options` | object | Additional settings | | `options.container` | HTMLElement | Container into which the form will be inserted. Default value: ``| #### Event handler: `paymentForm.onReady` Handles the event of the form becoming ready for work. ```js showLineNumbers paymentForm.onReady = function () { /* handler */ } ``` #### Event handler: `paymentForm.onPaymentStart` Handles the event occurring at the start of the payment process. ```js showLineNumbers paymentForm.onPaymentStart = function () { /* handler */ } ``` #### Event handler: `paymentForm.onPaymentSuccess` Handles the event occurring when the payment process finishes successfully. ```js showLineNumbers paymentForm.onPaymentSuccess = function () { /* handler */ }; ``` #### Event handler: `paymentForm.onPaymentFail` Handles the event occurring when the payment process finishes unsuccessfully. ```js showLineNumbers paymentForm.onPaymentFail = function (error) { /* handler */ } ``` #### Event handler: `paymentForm.onDestroy` Handles the event of the widget getting closed. ```js showLineNumbers paymentForm.onDestroy = () => { /* handler */ } ``` ### Widget customization #### Hide CVV/CVC details You can customize the CVV/CVC field of the widget to make it display only the latest digit entered by customers and mask the others entered before with *. To do this, add the `isCvcMasked` flag into the widget constructor, as follows: ``` js showLineNumbers const paymentForm = new Bank131PaymentForm('publicToken', { isCvcMasked: true, }); ``` #### Open the 3D Secure window as required You can choose how to open the 3D Secure window for the user. Use the `target` parameter of the `customerInteractionRedirect ` object with the following options: - `_blank` — in a new tab - `_self` — in the same frame - `_parent` — in the next-level frame if the frames are nested in one another - `_top` — outside of all the frames as the top window Default: `_top`. >Note that: >- We do not recommend using the `_self` option for security reasons. >- If you use the `_blank` option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget. #### Hide the cardholder name To hide the **Cardholder** filed, pass `hideCardHolderField: true`. By default, the field is shown. #### 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 While interacting with our widget, end users may receive the errors stated below. >If you choose to translate the widget texts into other languages, for example, Spanish, note that for now end users will receive error descriptions still in English. | Error code | Error description | |------------|-------------------| | `3DS_error` | To complete the transaction successfully, 3DS authentication is required | | `activity_count_exceeded` | The activity/amount limit for the card is exceeded | | `bank_card_expired` | The bank card is past its expiration date | | `declined_by_issuer_bank` | The operation was declined by the emitting bank | | `insufficient_funds` | The card does not have enough funds | --- - [Widget for getting tokenized bank card details](https://developer.131.ru/en/payments/tokenize-widget): Secure transactions with bank cards with the widget --- ## Money Transfers - [Money transfers without opening an account](https://developer.131.ru/en/transfers/transfer-start): Transfers from Russia abroad without opening an account With this feature, individuals can transfer money from Russia abroad without opening an account. ### Countries to which you can make a transfer | Country | Country code | Transfer method | Transfer currency | Limitations | |------------|--------------|-----------------|----------------------|--------------------------| | Kazakhstan | KAZ | Bank card | Tenge (KZT) | No limitations | | Kyrgyzstan | KGZ | Bank card | Som (KGS) | Transfers to Elcart only | | Tajikistan | TJK | Bank card | Somoni (TJS) | No limitations | | Uzbekistan | UZB | Bank card | Uzbekistan sum (UZS) | No limitations | 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" } } }' ``` Response examples ```json showLineNumbers { "amounts": { "source": { "amount": 357913, "currency": "RUB" }, "destination": { "amount": 131426, "currency": "TRY" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 5400, "currency": "RUB" } }, "exchanges": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" }, "rate": { "fx_rate": 2.7233, "quantity": 1 } } } ``` ```json showLineNumbers { "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 9193, "currency": "RUB" } }, "exchanges": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "rate": { "fx_rate": 76.2433, "quantity": 10000 } } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ### Step 2. Starting the transfer Start the transfer using the [`session/multi/init`](/reference/reference-methods.mdx#session_multi_init) method. Once the multisession is created, the system will perform verifications on the sender, validate the recipient's payout eligibility, calculate and reserve the final exchange rate with the exact debit and payout amounts. The exchange rate is reserved for a maximum of **5 minutes**. If you attempt to complete the transaction after this period, the session will terminate with the `rate_has_changed` [error code](/reference/errors). Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 37700, "currency": "TJS" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "TRY", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TJK", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2204320396205389" } } } }] }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 1000, "currency": "TRY" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "RUS", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "issued_by": "ОВД ПО Кировскому району", "division_code": "123-543" }, "contacts": { "phone": { "full_number": "+992910011020" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 1000, "currency": "TRY" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TRY", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } } }] }' ``` Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808365", "status": "in_progress", "created_at": "2025-08-08T12:39:15.668563Z", "updated_at": "2025-08-08T12:39:16.388348Z", "payout_list": [{ "id": "po_955259", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439833Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765898", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439730Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808544", "status": "in_progress", "created_at": "2025-08-11T07:39:00.076932Z", "updated_at": "2025-08-11T07:39:00.476548Z", "payout_list": [{ "id": "po_955266", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528662Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TRY", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2766065", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528558Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "division_code": "123-543", "issued_by": "ОВД ПО Кировскому району" }, "citizenship_country_iso3": "RUS", "contacts": { "phone": { "full_number": "+992910011020" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` Wait for a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook confirming the transfer is ready to process at the specified exchange rate with the final debit and payout amounts. In the webhook, the [`confirm_information`](/reference/reference-objects.mdx#confirm_information).[`exchanges`](/reference/reference-objects.mdx#exchanges) object will contain the current exchange rate and the debit and payout amounts. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_3808364", "status": "in_progress", "created_at": "2025-08-08T12:30:02.616632Z", "updated_at": "2025-08-08T12:30:04.489651Z", "payout_list": [{ "id": "po_955258", "status": "pending", "created_at": "2025-08-08T12:30:03.401467Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765897", "status": "pending", "created_at": "2025-08-08T12:30:03.401320Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "exchanges": [{ "id": "pm_2765897", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 306237, "currency": "RUB" } }, { "id": "po_955258", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }] // highlight-end } }' ``` ### Step 3. Confirming the transfer Check the transfer details and confirm the transfer using the [`session/confirm`](/reference/reference-methods.mdx#sessionconfirm) method. You need to confirm the session within 5 minutes. You can cancel the transfer using the `session/cancel` method. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3808364", "confirm_information": { "exchanges": [{ "id": "pm_2765897", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }, { "id": "po_955258", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }] } }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808364", "status": "in_progress", "created_at": "2025-08-08T12:30:02.616632Z", "updated_at": "2025-08-08T12:32:05.891206Z", "payments": [{ "id": "po_955258", "status": "pending", "created_at": "2025-08-08T12:30:03.401467Z", "payment_method": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "acquiring_payments": [{ "id": "pm_2765897", "status": "in_progress", "created_at": "2025-08-08T12:30:03.401320Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }], "actions": { "confirm": "2025-08-08T12:32:05.949621Z" } } } ``` After the session is confirmed, the sender's funds will be frozen for debit, and the debit must be confirmed via 3D Secure: - Wait for an [`action_required`](/reference/reference-webhooks.mdx#action_required) webhook with a 3D Secure link and redirect the user to complete 3D Secure. - After successful 3D Secure completion, the funds will be frozen on the sender's card. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", // highlight-start "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", // highlight-end "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ### Step 4. Canceling the transfer (optional) If required, you can cancel the transfer using the [`session/cancel`](/reference/reference-methods.mdx#sessioncancel) method. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3808365" }' ``` Response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3809232", "status": "in_progress", "created_at": "2025-08-11T10:14:54.779728Z", "updated_at": "2025-08-11T10:14:58.370629Z", "payout_list": [{ "id": "po_955280", "status": "pending", "created_at": "2025-08-11T10:14:55.586736Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "citizenship_country_iso3": "TJK" } } }], "payment_list": [{ "id": "pm_2766741", "status": "pending", "created_at": "2025-08-11T10:14:55.586645Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` Wait for a `payment_finished` webhook with `status` = `cancelled`. The session is canceled. Create a new session if you need to restart the transfer. ### Step 5. Payout to the recipient Wait for a [`payment_finished`](/reference/webhooks#payment_finished) webhook with `status` = `accepted`. Upon successful payout, the frozen amount will be debited from the sender. If an error occurs during the transfer process, the `payment_finished` webhook will contain an error code. [View error codes >](/reference/errors) Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", // highlight-next-line "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [ { "name": "****", "amount_details": { "amount": 10000, "currency": "rub" }, "quantity": 1 } ], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ### 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. ### Features - Beneficiary identification. [Identify individual beneficiaries](/escrow-account/verification-intro) before payouts. - Payouts. To bank cards ([by card number](/escrow-account/escrow-payout-cards), [with our widget or by token](/escrow-account/escrow-payout-tokenized-card)), to Russian bank accounts ([by account number](/escrow-account/escrow-payout-accounts), [with our widget or by token](/escrow-account/escrow-payout-tokenized-accounts)), and also [by phone number via FPS](/payouts/payout-fps-phone#payout-nominal). - Balance info. Check your escrow account balance using the [`account_balance`](/statements/statements-balance) method. - Account statements. Request a statement on all transactions for any particular day using the [`report/account_statement`](/statements/statements-escrow) method. - Top-up notifications. Enable the [`nominal_topup`](/reference/webhooks#nominal_topup) webhook to receive instant notifications on your escrow account top-ups. ### Accounts for payouts Accounts allowed for payouts from escrow accounts ### General scenario on how to work with an escrow account Working with an escrow account via the API generally involves the following steps: 1. Verify beneficiaries. 2. Replenish your escrow account. 3. Make a payout. Note that the scenario may vary in some steps depending on the escrow account agreement. 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, individuals and self-employed individuals to accounts in Russian banks You can make payouts to bank accounts from an escrow account as follows: - [as a standard payout](#payout_account)—the money will be credited within a period from 2 hours to 3 banking days (this depends on the recipient's bank) - [as a speedy payout through the BESP system](/payouts/payout-account-sistema-besp)—the money will be credited within an hour Before initiating a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) ### Making a standard payout #### Step 1. Create a payment session Create a session using the [`session/create/nominal`](/reference/methods#sessioncreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/escrow-account/russian-account-parameters) and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Send the payout Send a [`session/start/payout/nominal`](/reference/methods#sessionstartpayoutnominal) request, specifying the session identifier alongside the [payout parameters](/escrow-account/russian-card). Example of a payout by account number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "inn": "1111111111", "kpp": "156605101", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt", "is_fast": false, "kpp": "156605101", "inn": "1111111111" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } }, "payment_options": { "recurrent": false, "is_subsequent": false } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156605101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. ### 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 the self-employed, sole proprietors, and individuals To make payouts by card number, you must comply with the PCI DSS standard. Before a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) ### Step 1. Create a payment session Create a session using the [`session/multi/create/nominal`](/reference/reference-methods.mdx#sessionmulticreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/nominal`](/reference/reference-methods.mdx#sessionmultiinitpaymentnominal) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/escrow-account/russian-card) and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ### Step 2. Send the payout Send a [`session/multi/start/payment/nominal`](/reference/reference-methods.mdx#sessionmultistartpaymentnominal) request, specifying the session identifier alongside the [payout parameters](/escrow-account/russian-card). Example of a payout by card number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "5536********8371" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` ### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-09-14T09:32:19.891392Z", "updated_at": "2025-09-14T09:32:20.494410Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-09-14T09:32:20.100149Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-09-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` ### 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 the self-employed, sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `account` | + | string | Bank escrow account to send the payout from | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `beneficiary_id` | + | string | INN of the beneficiary | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000` | |    `currency` | + | string | Currency code by ISO 4217. Case insensitive. Always: `rub` | | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000` | |    `currency` | + | string | Currency code by ISO 4217. Case insensitive. Always: `rub` | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `full_name` | - (mandatory if the sender is an individual) | string | Sender's name | |       `company_name` | - (mandatory if the sender is a legal entity) | string | Company name | |       `address_line` | + | string | Address. Important: a city and country should be specified in the following fields, do not duplicate them here | |       `country_iso3` | + | string | Country (ISO-3166-1 alpha-3) | |       `city` | + | string | City | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters #### Payout purpose example `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ### What next [Payouts by bank account number >](/escrow-account/escrow-payout-accounts) [Payouts using our widget or by token >](/escrow-account/escrow-payout-tokenized-accounts) --- - [Parameters for payouts to Russian bank cards](https://developer.131.ru/en/escrow-account/russian-card): Payouts to Visa, MasterCard, and Mir Which parameters to specify depends on how you send data. Mandatory parameters for payouts to a Russian bank card by token, hash, or via the Bank 131 widget. | Name | Mandatory | Type | Description | |-----------------------------------------------|-------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Values: `encrypted_card` or `tokenized_card` | |       `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Encrypted card details](/reference/reference-objects.mdx#encrypted_card) | |          `number_hash` | + | string | Card number hash | |       `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | |          `token` | + | string | Card number token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (тип, описание) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_nominal_account` | |       `transfer_from_nominal_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_nominal_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | Mandatory parameters for payouts to a Russian bank card by its number. | Name | Mandatory | Type | Description | |-----------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, account, etc.) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Value: `bank_card` | |       `bank_card` | + | object | [Card details](/reference/reference-objects.mdx#bankcard) | |          `number` | + | string | Card number | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | |       `beneficiary_id` | - | string | INN of the beneficiary. The parameter is mandatory in either of the following objects: `sender` or `recipient` | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (type, description) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_nominal_account` | |       `transfer_from_nominal_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_nominal_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | ### What next [Payouts by card number >](/escrow-account/escrow-payout-cards) [Payouts using our widget or by token >](/escrow-account/escrow-payout-tokenized-card) --- - [Payouts to accounts with our widget or by token](https://developer.131.ru/en/escrow-account/escrow-payout-tokenized-accounts): Payouts in rubles to bank accounts of the self-employed, sole proprietors, and individuals You can make payouts from an escrow account to bank accounts using a token instead of the account number. You can get the token as follows: - using our [`tokenize`](/reference/methods#tokenize) method - using our [widget](/payouts/tokenize-account-widget) Before making a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/create/nominal`](/reference/methods#sessioncreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout/nominal`](/reference/methods#sessionstartpayoutnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Step 1. Create a payment session Create a session using the [`session/create/nominal`](/reference/methods#sessioncreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/nominal`](/reference/methods#payout-nominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout/nominal`](/reference/methods#sessionstartpayoutnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Example of a payout by token ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Sequence diagram ![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 ``` ![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 the self-employed, sole proprietors, and individuals You can make payouts from an escrow account to bank cards using a token or a hash instead of the card number. You can get a token/hash as follows: - hash: [using our widget](/payouts/tokenize-widget) - token: using the [`tokenize/elements`](/reference/methods#tokenizeelements) method - token: by [processing a recurring payment](/payments/payment-recurring) The scope of PCI DSS requirements you must comply with depends on the method you choose. Before making a payout, [identify the beneficiary](/escrow-account/verification-intro). [How to enable a webhook to get notified on your escrow account top-ups >](/reference/webhooks#nominal_topup) #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/multi/create/nominal`](/reference/reference-methods.mdx#sessionmulticreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/nominal`](/reference/reference-methods.mdx#sessionmultiinitpaymentnominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/multi/start/payment/nominal`](/reference/reference-methods.mdx#sessionmultistartpaymentnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-card). :::info You can find information on the hash or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-14T09:32:20.099952Z", "updated_at": "2025-05-14T09:32:20.099911Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-14T09:32:20.099944Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-05-14T09:32:20.099966Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Payout requests require either a token or a hash, depending on what you use. #### Step 1. Create a payment session Create a session using the [`session/multi/create/nominal`](/reference/reference-methods.mdx#sessionmulticreatenominal) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/nominal`](/reference/reference-methods.mdx#sessionmultiinitpaymentnominal) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/escrow-account/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/multi/start/payment/nominal`](/reference/reference-methods.mdx#sessionmultistartpaymentnominal) method. Pass the session identifier along with all the [parameters for a payout](/escrow-account/russian-card). :::info You can find information on the token, hash, or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Example of a payout with tokenized data ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-14T09:32:20.094952Z", "updated_at": "2025-05-14T09:32:20.095952Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-14T09:32:20.029952Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": " ", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC", "beneficiary_id": "1234567890" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Sequence diagram ### 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 ``` ### 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). #### Request parameters | Name | Mandatory | Type | Description | |---------------------------|-----------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Recipient type: `FL_RESIDENT` | | `last_name` | + | string | Last name | | `first_name` | + | string | First Name | | `patronymic` | - | string | Patronymic | | `birthday` | + | string | Date of birth in the following format: `DD.MM.YYYY`. Should be 18 years old or older | | `birthplace` | + | string | Place of birth | | `citizenship` | + | string | Citizenship in **ISO 3166-1 alpha-2** format | | `inn` | + | string | INN: 12 digits | | `phone_number` | + | string | Phone number (any format) | | `email` | + | string | Valid email address | | `documents` | + | array | Russian passport: `PASSPORT_RF` | |   `type` | + | string | Document type: `PASSPORT_RF` for Russian passport | |   `number` | + | string | Passport series and number in the following format: `1234567890` | |   `issuer` | + | string |Issuing division | |   `issuer_date` | + | string | Date of issue in the following format: `DD.MM.YYYY` | |   `issuer_code` | + | string | Subdivision code | | `address` | + | string | Address of registration | | `postcode` | - | string | ZIP code | | `agent_contract_number` | + | string | Number of the agency agreement with the recipient | | `agent_contract_date` | + | string | Date of the agency agreement with the recipient in the following format: `DD.MM.YYYY`. Must be less than or equal to the current date | | `beneficial_owners` | + | string | Information on beneficiary owners. Always: `No BO` | | `public_officials` | + | string | Status as a public official. Always: `No` | Request example ```json showLineNumbers curl -X POST \ https://kyc.bank131.ru/api/v2/check \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "FL_RESIDENT", "last_name": "Dmitriev", "first_name": "Ivan", "patronymic": "Ivanovich", "birthday": "01.01.1970", "birthplace": "Novgorod", "citizenship": "RU", "inn": "065553161159", "phone_number": "+79000000000", "email": "name@email.com", "documents": [{ "type": "PASSPORT_RF ", "number": "0234567890", "issuer": "UFMS Russia", "issuer_date": "01.01.2010", "issuer_code": "123-000" }], "address": "Novgorod, Pribrezhnaya str., 53", "postcode": "365826", "agent_contract_number": "123456789-0", "agent_contract_date": "01.01.2020", "beneficial_owners": "No BO", "public_officials": "No" }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|--------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", "description": "request added to queue" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "partner_project_not_found", "description": "partner project not found" } } ``` Response example for a test request For testing, the value of the `status` field sent in the response strictly depends on the last digit in ID number of the `passport_number` field sent in the request. | Last digit in `passport_number` | `status` value | |---------------------------------|----------------| | Even, including 0 | `ok` | | Odd | `error` | #### Request parameters | Name | Mandatory | Type | Description | |---------------------------|-----------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `last_name` | + | string | Last name | | `first_name` | + | string | First Name | | `patronymic` | - | string | Patronymic | | `birthday` | + | string | Date of birth in the following format:` DD.MM.YYYY`. Should be 18 years old or older | | `birthplace` | + | string | Place of birth | | `inn` | + | string | INN: 12 digits | | `phone_number` | + | string | Phone number (any format) | | `email` | + | string | Valid email address | | `identity_document` | + | string | Document type: `Паспорт гражданина РФ` | | `passport_number` | + | string | Passport series and number in the following format: `1234567890` | | `issuer` | + | string |Issuing division | |   `issuer_date` | + | string | Date of issue in the following format: `DD.MM.YYYY` | |   `issuer_code` | + | string | Subdivision code | | `citizenship` | + | string | Citizenship: `РФ` | | `address` | + | string | Address of registration | | `postcode` | - | string | ZIP code | | `agent_contract_number` | + | string | Number of the agency agreement with the recipient | | `agent_contract_date` | + | string | Date of the agency agreement with the recipient in the following format: `DD.MM.YYYY` | | `beneficial_owners` | + | string | Information on beneficiary owners. Always: `No BO` | | `public_officials` | + | string | Status as a public official. Always: `No` | | `migration_card` | + | string | Always: `-` | | `right_to_stay_in_rf` | + | string | Always: `-` | Request example ```json showLineNumbers curl -X POST \ https://kyc.bank131.ru/api/v1/check \ -H 'x-partner-project: test-partner-project' \ -H 'Content-Type: application/json' \ -H 'accept: application/json' \ -d '{ "payload": { "inn": "065553161159", "email": "name@email.com", "issuer": "UFMS Russia", "address": "53, Pribrezhnaya Alley, Bldg. 9, Bobruisk, 365826", "birthday": "01.01.1970", "postcode": "365826", "birthplace": "Bobruisk", "last_name": "Ivanov", "first_name": "Ivan", "patronymic": "Ivanovich", "citizenship": "РФ", "issuer_code": "123-000", "issuer_date": "01.01.2010", "phone_number": "+79000000000", "migration_card": "-", "passport_number": "0234567890", "public_officials": "No", "beneficial_owners": "No BO", "identity_document": "Паспорт гражданина РФ", "agent_contract_date": "01.01.2020", "right_to_stay_in_rf": "-", "agent_contract_number": "123456789-0" }, "signature": "dkQzYwTExRc0RFWk1CY0dBMVVFQnd3UTBMTXVJTkNjMEw3Ug0NCmd..." }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|--------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", "description": "request added to queue" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "partner_project_not_found", "description": "partner project not found" } } ``` Response example for a test request For testing, the value of the `status` field sent in the response strictly depends on the last digit in ID number of the `passport_number` field sent in the request. | Last digit in `passport_number` | `status` value | |---------------------------------|----------------| | Even, including 0 | `ok` | | Odd | `error` | ### Verification results To get the verification result, use the `check/{id}` method. In the request, specify the ID you received in the response to the `check` request. Result processing may take anywhere from 10 minutes to 2 days. #### Request parameters The request body is empty. Request example ```json showLineNumbers curl -X GET \ https://kyc.bank131.ru/api/v2/check/7 \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|-------------------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `pending`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", // check request ID "description": "valid" } } ``` ```json showLineNumbers { "status": "pending", "data": { "id": "7", "description": "Check in progress" } } ``` Data already verified. ```json showLineNumbers { "status": "error", "error": { "code": "already_exists", "description": "Request with the same data already exists" }, "data": { "id": "7" } } ``` #### Request parameters The request body is empty. Request example ```json showLineNumbers curl -X GET \ https://kyc.bank131.ru/api/v1/check/7 \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ ``` #### Response parameters | Name | Mandatory | Type | Description | |---------------------------|-----------|--------|-------------------------------------------------------------------| | `status` | + | string | Identification status. Possible options: `ok`, `pending`, `error` | | `data` | - | Data | Response details | |   `id` | - | number | `check` request ID | |   `description` | - | string | Request status description | | `error` | - | Error | Error details | |   `code` | + | string | Error code | |   `description` | + | string | Error description | Response examples ```json showLineNumbers { "status": "ok", "data": { "id": "7", // check request ID "description": "valid" } } ``` Send another `check/{id}` request with the same data later. ```json showLineNumbers { "status": "pending", "data": { "id": "7", "description": "Check in progress" } } ``` Data already verified. ```json showLineNumbers { "status": "error", "error": { "code": "already_exists", "description": "Request with the same data already exists" }, "data": { "id": "7" } } ``` ### Error codes and statuses #### HTTP response codes | Code | Description | What you can do | |-------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `200` | Correct request | Check `status` | | `422` | Request error | See `error.description` for details:- `request_body_validation_error` — error in the request body- `request_header_validation_error` — `x-partner-project` header missing | | `500` | Error on Bank 131's side | Try again later | #### Response statuses Response statuses are passed in the `status` field. | Status | Description | Решение | |-----------|--------------------------------|-------------------------------------------------| | `ok` | Request processed successfully | Check `data` | | `pending` | Request is being processed | To find out the result, retry the request later | | `error` | Request processing error | Check `error` | #### Error codes Errors are passed in the `error` object: - `code` — error code - `description` — error description | Code | Description | What you can do | |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `invalid_sign` | `Запрос с указанным идентификатором подписан некорректно` | Verify the request signature is properly generated | | `passport_validation_failure` | `По данным МДВ предоставленный паспорт признан недействительным ` | The passport is invalid. Check the passport data | | `passport_validation_failure` | `В базе данных МВД отсутствуют сведения о предоставленном паспорте` | No information about the passport was found. Check the passport data | | `inn_validation_failure` | `По данным ФНС предоставленный паспорт не соответствует предоставленному ИНН` | The INN value is not linked to the passport specified. Check the INN | | `already_exists` | `Запрос на проверку с теми же данными был направлен ранее` | You have already submitted these data for identification. To see the result, send a `check{id}` request with the previous verification's ID that you received in the `data.id` field | | `request_not_found` | `Не найден запрос с указанным идентификатором` | The request with the given ID was not found. Check the ID | | `partner_project_not_found` | `Не найден проект с указанным в заголовке идентификатором` | The project ID sent in the `X-PARTNER-PROJECT` header does not exist. Check the ID | | `birthday_validation_failure` | `Возраст проверяемого лица ниже допустимого порога` | The verified subject must be an adult. If you receive this error when working with a nominal account, contact your manager | | `validation_error` | Request validation error. Example: `1 validation error for Request.body → payload → documents → 2 → expire_date. Document MIGRATION_CARD is expired (type=value_error)` | Invalid formats and/or controls in values. For detailed information see the `description` field | Response examples ```json showLineNumbers { "status": "error", "error": { "code": "passport_validation_failure", "description": "По данным МДВ предоставленный паспорт признан недействительным" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "passport_validation_failure", "description": "В базе данных МВД отсутствуют сведения о предоставленном паспорте" } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "inn_validation_failure", "description": "По данным ФНС предоставленный паспорт не соответствует предоставленному ИНН" } } ``` 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. ### Features - Payouts. To bank cards ([by card number](/settlement-account/settlement-payout-cards), [with our widget or by token](/settlement-account/settlement-payout-tokenized-card)), to Russian bank accounts ([by account number](/settlement-account/settlement-payout-accounts), [with our widget or by token](/settlement-account/settlement-payout-tokenized-accounts)), and also [by phone number via FPS](/payouts/payout-fps-phone). - Balance info. Check your settlement account balance using the [`account_balance`](/statements/statements-balance) method. - Account statements. Request a statement on all transactions for any particular day using the [`report/account_statement`](/statements/statements-escrow) method. ### Accounts for payouts Accounts allowed for payouts from settlement accounts --- - [Payouts from a settlement account by account number](https://developer.131.ru/en/settlement-account/settlement-payout-accounts): Payouts from a settlement account to bank accounts You can make payouts to bank accounts from a settlement account as follows: - [as a standard payout](#payout_account)—the money will be credited within a period from 2 hours to 3 banking days (this depends on the recipient's bank) - [as a speedy payout through the BESP system](/payouts/payout-account-sistema-besp)—the money will be credited within an hour ### Making a standard payout #### Step 1. Create a payment session Create a session using the [`session/create/rko`](/reference/methods#sessioncreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/rko`](/reference/reference-methods.mdx#payout-rko) method to create a session and a payout at the same time. In this case, specify all the [payout parameters](/settlement-account/russian-account-parameters) and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Send the payout Send a [`session/start/payout/rko`](/reference/methods#sessionstartpayoutrko) request, specifying the session identifier alongside the [payout parameters](/settlement-account/russian-account-parameters). Example of a payout by account number ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Transfer of funds under the agreement for December 2025. VAT exempt." }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 350000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "inn": "1111111111", "kpp": "156605101", "description": "Transfer of funds under the agreement for December 2025. VAT exempt." }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 350000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` #### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt.", "is_fast": false, "kpp": "156605101", "inn": "1111111111" } } }, "amount_details": { "amount": 350000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } }, "payment_options": { "recurrent": false, "is_subsequent": false } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156605101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822029205974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. ### 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 '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "5536********8371" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` ### Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-09-14T09:32:19.891392Z", "updated_at": "2025-09-14T09:32:20.494410Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-09-14T09:32:20.100149Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-09-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 293400, "currency": "RUB" }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` Canceling a payout ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 293400, "currency": "RUB" } } } // highlight-end }' ``` ### Step 5. Wait for a webhook with the results of the payout Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. The `succeeded` status means the payout has been successful. The `failed` status means the payout has not been completed because of an error. Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` ### 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 the self-employed, sole entrepreneurs, legal entities, and individuals The required parameters depend on whether you send a payout as a resident or non-resident. | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `account` | + | string | Bank escrow account to send the payout from | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000` | |    `currency` | + | string | Currency code by ISO 4217. Case insensitive. Always: `rub` | | Name | Mandatory | Type | Description | |------------------------------------|------------------------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `bank_account` | |    `bank_account` | + | object | [Bank account](/reference/reference-objects.mdx#bank_account) | |       `system_type` | + | string | Bank transfer system. Always: `ru` | |       `ru` | + | object | [Bank account object](/reference/reference-objects.mdx#ru) | |          `bik` | - (mandatory for payouts by account number) | string | Recipient's bank BIC | |          `account` | - (mandatory for payouts by account number) | string | Recipient's bank account | |          `full_name` | + | string | Payout recipient. Possible options:- the individual's full name- `ИП ` for payouts to sole proprietors- the entity's name, if it is provided in the agreement | |          `inn` | - (mandatory for payouts to sole proprietors and legal entities) | string | INN | |          `kpp` | - (mandatory for payouts to legal entities) | string | Recipient's Tax Registration Reason Code (KPP) | |          `description` | + | string | [Payout purpose](#target) | |          `token` | - (mandatory for payouts by token) | string | Bank account token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than 0. To send 100 rubles, specify `10000` | |    `currency` | + | string | Currency code by ISO 4217. Case insensitive. Always: `rub` | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `sender` | + | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | |       `full_name` | - (mandatory if the sender is an individual) | string | Sender's name | |       `company_name` | - (mandatory if the sender is a legal entity) | string | Company name | |       `address_line` | + | string | Address. Important: a city and country should be specified in the following fields, do not duplicate them here | |       `country_iso3` | + | string | Country (ISO-3166-1 alpha-3) | |       `city` | + | string | City | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name | ### How to specify the payout purpose In the `description` parameter, specify the following: - the transaction type (e.g. `service fee`) - the reason for the transaction (e.g. `under Agreement No. 123`) - the name of the products and/or services provided - whether or not VAT is applicable - for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: - disallowed characters: `?`, `!` - maximum length:210 characters #### Payout purpose example `Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt` `{VO99090} Wire for agreement № 5015553456 Ivanov Ivan Ivanovich VAT exempt` ### What next [Payouts by bank account number >](/settlement-account/settlement-payout-accounts) [Payouts using our widget or by token >](/settlement-account/settlement-payout-tokenized-accounts) --- - [Parameters for payouts to Russian bank cards](https://developer.131.ru/en/settlement-account/russian-card): Payouts to Visa, MasterCard, and Mir Which parameters to specify depends on how you send data. Mandatory parameters for payouts to a Russian bank card by token, hash, or via the Bank 131 widget. | Name | Mandatory | Type | Description | |-----------------------------------------------|-------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Values: `encrypted_card` or `tokenized_card` | |       `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Encrypted card details](/reference/reference-objects.mdx#encrypted_card) | |          `number_hash` | + | string | Card number hash | |       `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/objects#tokenized_card) | |          `token` | + | string | Card number token | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (тип, описание) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_nominal_account` | |       `transfer_from_nominal_account` | + | object | [Information about a transfer](/reference/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 | Mandatory parameters for payouts to a Russian bank card by its number. | Name | Mandatory | Type | Description | |--------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, account, etc.) | |    `type` | + | string | Value: `card` | |    `card` | + | object | [Bank card payment details](/reference/reference-objects.mdx#card) | |       `type` | + | string | Value: `bank_card` | |       `bank_card` | + | object | [Card details](/reference/reference-objects.mdx#bankcard) | |          `number` | + | string | Card number | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | |    `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To send 100 rubles, specify `10000` | |    `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` except for [payouts in a foreign currency](/payouts/payout-currency) | | `participant_details` | + | object | [Information on payout participants](/reference/reference-objects.mdx#participant_details) | |    `recipient` | + | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | |       `full_name` | + | string | Recipient's name (as it appears on the passport) | |    `sender` | + | object | [Sender's details](/reference/objects#participant_details_sender) | |       `full_name` | + | string | Possible options:- the individual's full name (as it appears on the passport)- `ИП `- the entity's name, if it is provided in the agreement | | `payment_details` | + | object | [Information about a transaction](/reference/reference-objects.mdx#payment_details) (type, description) | |    `type` | + | string | Value: `internal_transfer` | |    `internal_transfer` | + | object | [Information about an internal transfer](/reference/reference-objects.mdx#internal_transfer) | |       `type` | + | string | Value: `transfer_from_bank_account` | |       `transfer_from_bank_account` | + | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_from_bank_account) | |          `description` | + | string | Description | | `customer` | + | object | [Recipient's details in your system](/reference/objects#customer) | |    `reference` | + | string | Recipient's reference number in your system | ### What next [Payouts by card number >](/settlement-account/settlement-payout-cards) [Payouts using our widget or by token >](/settlement-account/settlement-payout-tokenized-card) --- - [Payouts from a settlement account with our widget or by token](https://developer.131.ru/en/settlement-account/settlement-payout-tokenized-accounts): Payouts in rubles to bank accounts of the self-employed, sole proprietors, and individuals You can make payouts from a settlement account to bank accounts using a token instead of the account number. You can get the token as follows: - using our [`tokenize`](/reference/methods#tokenize) method - using our [widget](/payouts/tokenize-account-widget) #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/create/rko`](/reference/methods#sessioncreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/rko`](/reference/reference-methods.mdx#payout-rko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/start/payout/rko`](/reference/methods#sessionstartpayoutrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Step 1. Create a payment session Create a session using the [`session/create/rko`](/reference/methods#sessioncreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/rko`](/reference/reference-methods.mdx#payout-rko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-account-parameters) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/start/payout/rko`](/reference/methods#sessionstartpayoutrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-account-parameters). :::info You can find information on the token or account through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the first 5 or the last 4 digits of the account number to show the recipient which account the payout will be made to. ::: Example of a payout by token ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_2643", "payment_method": { // highlight-start "type": "bank_account", "bank_account": { "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" }, "system_type": "ru" } // highlight-end }, "amount_details": { "amount": 300000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" } } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_2643", "status": "in_progress", "created_at": "2025-02-20T08:42:35.905869Z", "updated_at": "2025-02-20T08:42:36.382627Z", "payments": [{ "id": "po_513", "status": "pending", "created_at": "2025-02-20T08:42:35.965210Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "token": "3f03ee2580046153bb0aa859558e7ada10d3835270fdb4c4b70961239d37f31d", "full_name": "Vector LLC", "description": "Transfer of funds under the agreement for December 2025. VAT exempt" } } }, "amount_details": { "amount": 300000, "currency": "RUB" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" } } }], "next_action": "confirm", "session_metadata": {} }, // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2643", // highlight-start "confirm_information": { "account_details": { "sender": { "account_number": "40702810300200000013", "name": "ABC LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822029205131", "inn": "3316004790", "kpp": "156667101" }, "recipient": { "account_number": "40702810500000000001", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "044525974", "correspondent_account_number": "30101810822000000974", "inn": "1111111111", "kpp": "156605101" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Sequence diagram ![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 ``` ![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 the self-employed, sole proprietors, and individuals You can make payouts from a settlement account to bank cards using a token or a hash instead of the card number. You can get a token/hash as follows: - hash: [using our widget](/payouts/tokenize-widget) - token: using the [`tokenize/elements`](/reference/methods#tokenizeelements) method - token: by [processing a recurring payment](/payments/payment-recurring) The scope of PCI DSS requirements you must comply with depends on the method you choose. #### Step 1. Get a public token A public token is required to initialize the widget. Send a request to Bank 131 to create a token ([`token`](/reference/reference-methods.mdx#token)), specifying the widget type as `tokenize_widget`. The response will contain your public token. Example of getting a public token ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` #### Step 2. Initialize the widget on your site [Initialize the widget on your site](/payouts/widget-tokenize.mdx) using the public token obtained in the previous step. The payout recipient can then enter their bank card number into the data collection form. #### Step 3. Create a payment session Create a session using the [`session/multi/create/rko`](/reference/reference-methods.mdx#sessionmulticreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/rko`](/reference/methods#sessionmultiinitpaymentrko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-card) and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 4. Start the payout Start the payout using the [`session/multi/start/payment/rko`](/reference/reference-methods.mdx#sessionmultistartpaymentrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-card). :::info You can find information on the hash or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Payout example with the widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.109901Z", "updated_at": "2025-05-27T02:03:00.987002Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-27T02:03:00.456003Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-05-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Payout requests require either a token or a hash, depending on what you use. #### Step 1. Create a payment session Create a session using the [`session/multi/create/rko`](/reference/reference-methods.mdx#sessionmulticreaterko) method. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/multi/init/payment/rko`](/reference/methods#sessionmultiinitpaymentrko) method to create a session and a payout at the same time. In this case, specify all the [parameters for a payout](/settlement-account/russian-card) right away and skip the next step. This option is not recommended. Creating a session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` #### Step 2. Start the payout Start the payout using the [`session/multi/start/payment/rko`](/reference/reference-methods.mdx#sessionmultistartpaymentrko) method. Pass the session identifier along with all the [parameters for a payout](/settlement-account/russian-card). :::info You can find information on the token, hash, or card through the [`token/info`](/reference/reference-methods.mdx#token_info) method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to. ::: Example of a payout with tokenized data ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id": "ps_3230", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement" } } }, "payment_method": { // highlight-start "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } // highlight-end }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "123456789012" } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel. The webhook body will contain the `confirm_information` object. Save it, as you will need this object to confirm or cancel the transaction. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.302206Z", "updated_at": "2025-05-27T02:03:00.863207Z", "payments": [{ "id": "po_7639847", "status": "pending", "created_at": "2025-05-27T02:03:00.211108Z", "customer": { "reference": "123456789012" }, "payment_method": { "type": "card", "card": { "last4": "8371", "brand": "mastercard", "country_iso3": "RUS" } }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "acquiring_payments": [{ "id": "pm_6933973", "status": "pending", "created_at": "2025-05-14T09:32:20.099952Z", "customer": { "reference": "123456789012" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Transfer under the offer agreement", "card_mask": "553691******8371" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "full_name": "Vector LLC" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }], "next_action": "confirm" }, // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) the payout passing the `confirm_information` object. Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", // highlight-start "confirm_information": { "transfer_details": { "payment_method": { "type": "card", "card": { "brand": "mastercard", "last4": "8371", "country_iso3": "RUS" } }, "customer": { "account_number": "40702810700200000000", "name": "Vector LLC", "bank_name": "Bank 131", "bik": "049205131", "correspondent_account_number": "30101810822000000000" }, "recipient": { "account_number": "30233810000000000000", "name": "Ivanov Ivan Ivanovich", "bank_name": "Bank 131", "bik": "049205123", "correspondent_account_number": "30101810822000000974" }, "purpose": "Transfer under the offer agreement", "amount": { "amount": 10000, "currency": "rub" } } } // highlight-end }' ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. #### Sequence diagram ![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 ``` ![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) --- ## Self-Employed - [Connecting the self-employed to Bank 131](https://developer.131.ru/en/selfemployed/selfemployed-binding): Connecting self-employed people to Bank 131 for payouts with fiscalization To enable automatic fiscalization of receipts for your payouts via Bank 131, get the self-employed person's consent. To do this, create a connection request and send the received link to the self-employed person. By following the link, they will complete all the necessary steps and confirm their consent to fiscalization. If the self-employed person has already been identified and connected to Bank 131 before, skip the steps below. A self-employed person can give consent to the fiscalization of payouts from several partners, but each partner must create a separate connection request. The service is only available to citizens of the Russian Federation with a Russian phone number. ### Step 1. Create a connection request Send a [`self_employed/onboarding/create`](/reference/methods#self_employedonboardingcreate) request to create a connection request. There is no limit on the number of requests—you can create as many as you need. In the response, you will receive a link for the self-employed person and the request ID to check the connection status. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/self_employed/onboarding/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "return_url": "https://131.ru/" }' ``` ### Step 2. Send the link to the self-employed person Send the link to the self-employed person in any convenient way, for example, by email. > The link is not linked to a particular person, so any self-employed person can start connecting using it. But if someone has already started connection, the link cannot be reused. #### Self-employed person connection steps 1. Follows the link, accepts the connection terms, and agrees to be connected to you. 2. Registers in their account. From that moment, they have 24 hours to complete the connection, otherwise they will have to start over. 3. Passes identification. 4. Passes the Federal Tax Service check. There are two possible scenarios: - if the person is not yet registered as a self-employed person—Bank 131 registers them with the FTS and immediately receives the necessary fiscalization permissions - if the self-employed person is already registered—Bank 131 sends a request to the FTS to grant them the permissions for the fiscalization of receipts, and the self-employed person approves it [in their account)](https://lknpd.nalog.ru). After that, Bank 131 checks the status with the FTS, and the connection is completed > If the identification or FTS check is declined, the self-employed person can try again, but there is no guarantee the connection will be completed successfully. The decline reasons may not depend on Bank 131. #### Possible errors during connection - **No SMS code received** — check the phone number and request the code again - **Failed to confirm identity** — make sure the document is fully readable and the data is clearly visible, then try again - **Data mismatch FTS data** — clarify the reason with the tax authority. The passport data may differ from the tax data - **Tax authority refused registration** — clarify the reason with the tax authority. The self-employed status may be unavailable due to restrictions - **Access to account not confirmed** — return to the account and request access again - **More than 24 hours passed since connection started** — start the connection again ### Step 3. Check the connection status Send a [`self_employed/onboarding/status`](/reference/methods#self_employedonboardingstatus) request passing the request ID obtained during the first step. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/self_employed/onboarding/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de" }' ``` ### Self-employed connection diagram ![Self-employed person connection diagram](/img/docs/selfemployed/schema_connecting_selfemployed_en.png) ```plantuml @startuml ConnectSelfemployed autonumber participant Partner participant "Self-employed" as Selfemployed participant Bank_131 participant "Federal Tax Service" as FTS Partner -> Bank_131: ""self_employed/onboarding/create"" Bank_131 --> Partner: 200 OK Partner -> Selfemployed: sends the connection link Selfemployed -> Bank_131: follows the link and accepts the connection terms Selfemployed -> Bank_131: registers in the account Selfemployed -> Bank_131: passes identification alt Not yet registered as a self-employed person Bank_131 -> FTS: registers the self-employed person with the FTS Bank_131 -> FTS: receives fiscalization permissions else Already registered as a self-employed person Bank_131 -> FTS: sends a permission assignment request FTS -> Selfemployed: requests permissions confirmation Selfemployed -> FTS: confirms the permissions Bank_131 -> FTS: checks the request status end Partner -> Bank_131: ""self_employed/onboarding/status"" Bank_131 --> Partner: 200 OK @enduml ``` [How to make a payout with fiscalization >](/selfemployed/selfemployed-payout) --- - [Registering payouts with the Federal Tax Service](https://developer.131.ru/en/selfemployed/selfemployed-fiscalization): Registering payouts to a self-employed person with the tax authority and receipt issuance If a payout to a self-employed person was made without fiscalization, a receipt must be issued within 9 calendar days of receiving the money. If you issued a receipt by mistake, the fiscalization can be [canceled](#cancel). To use this functionality, contact your account manager at Bank 131. ### How to perform fiscalization #### Step 1. Create a payment session Send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request leaving the request body empty. You will get the session identifier in response. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ // highlight-start -d '{ }' // highlight-end ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPayoutSession() ->build(); $response = $client->session()->create($request); ``` #### Step 2. Send a fiscalization request Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2704", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "123456789012", "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }, // highlight-end { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }] } } }' ``` Successful response example ```json showLineNumbers { "status": "ok", "session": { "id": "ps_2704", "status": "in_progress", "created_at": "2025-05-27T08:13:33.736384Z", "updated_at": "2025-05-27T08:13:33.871729Z", "payments": [{ "id": "po_2705", "status": "in_progress", "created_at": "2025-05-27T08:13:33.860754Z", "amount_details": { "amount": 15000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 2 }, { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "123456789012", "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC" } } }] } } ``` #### Step 3. Wait to be notified of the results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` field of the `payments/payout_list` array. If the status is `succeeded`, then the fiscalization was successful. The link to the receipt from the FTS is returned in the `fiscalization_details.receipt` object. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_2704", "status": "accepted", "created_at": "2025-06-08T09:07:34.689353Z", "updated_at": "2025-06-08T09:07:53.491653Z", "payments": [{ "id": "po_23695", // highlight-next-line "status": "succeeded", "created_at": "2025-06-08T09:07:42.591416Z", "finished_at": "2025-06-08T09:07:53.319963Z", "amount_details": { "amount": 15000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 2 }, { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "123456789012", // highlight-start "receipt": { "id": "203zpt6nu5", "link": "https://himself-ktr.nalog.ru/api/v1/receipt/645493572846/203zpt6nu5/print" }, // highlight-end "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC" } } }] } }' ``` ### How to cancel fiscalization Occasionally it's necessary to cancel fiscalization and annul the issued receipt. For example, if the payout failed or the receipt was issued by mistake. #### Step 1. Send a fiscalization cancellation request Send a [`session/refund`](/reference/reference-methods.mdx#sessionrefund) request specifying the session identifier from the fiscalization request that you are canceling in the `session_id` parameter and the receipt amount in the `amount` parameter. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/refund \ -H 'content-type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_2704", // highlight-start "amount_details": { "amount": 15000, "currency": "rub" } // highlight-end }' ``` #### Step 2. Wait to be notified of the results Bank 131 will send you a [`payment_refunded`](/reference/reference-webhooks.mdx#payment_refunded) webhook with a link to the annulled receipt. :::info When fiscalization is canceled, Bank 131 specifies that the receipt was generated by mistake as a cancellation reason. ::: Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_2704", "status": "accepted", "created_at": "2025-06-08T09:07:34.689353Z", "updated_at": "2025-06-08T09:16:48.624196Z", "payments": [{ "id": "po_2705", "status": "succeeded", "created_at": "2025-06-08T09:07:42.591416Z", "finished_at": "2025-06-08T09:07:53.319963Z", "amount_details": { "amount": 15000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 2 }, { "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "123456789012", // highlight-start "receipt": { "id": "203zpt6nu5", "link": "https://himself-ktr.nalog.ru/api/v1/receipt/645493572846/203zpt6nu5/print" }, // highlight-end "payer_type": "legal", "payer_tax_number": "3316004777", "payer_name": "Vector LLC" } }, "refunds": [{ "id": "rf_249", "status": "accepted", "created_at": "2025-06-08T09:16:42.897606Z", "finished_at": "2025-06-08T09:16:48.517040Z", "amount_details": { "amount": 15000, "currency": "rub" } }] }] } }' ``` --- - [API features](https://developer.131.ru/en/selfemployed/intro): General information about payouts to self-employed individuals Self-employed individuals are people who work for themselves and pay the professional income tax. For example, tutors. Every payout to a self-employed person is considered their income and must be recorded with the Federal Tax Service (FTS). Through our API, you can process payouts with fiscalization, i.e. with automatic receipt registration at the FTS. Before making the first payout, make sure the self-employed person is [connected to Bank 131](/selfemployed/selfemployed-binding). [How to make a payout with fiscalization >](/selfemployed/selfemployed-payout) ### Notifications from the Federal Tax Service Through your website's interface, you can inform self-employed people about accrued taxes, bonuses, and other important information from the Federal Tax Service (FTS). [How to work with notifications from the FTS >](/selfemployed/selfemployed-notification) --- - [Notifications from the Federal Tax Service](https://developer.131.ru/en/selfemployed/selfemployed-notification): Information about alerts from the Federal Tax Service via website or mobile app You can inform self-employed people about accrued tax, bonuses, and other important information directly through your website's interface. ### Getting the number of unread notifications 1. Send an [`npd/notifications/count`](/reference/reference-methods.mdx#count) request to get the number of unread notifications for a selected self-employed person. 2. Show the number from the `count` parameter to the self-employed person on your website. 3. Send an [`npd/notifications/read`](/reference/methods#read) request to get the list of unread notifications. 4. Show the notifications to the self-employed person. 5. Send an [`npd/notifications/mark_as_delivered`](/reference/reference-methods.mdx#mark_as_delivered) request to inform the FTS that the notifications have been delivered to the self-employed person. 6. Send an [`npd/notifications/update`](/reference/methods#update) request to inform the FTS that the self-employed person has read the notifications. ### Getting information about tax accruals and bonuses To get information about the bonus account balance, amount of unpaid bills, and current debt, use the [`npd/taxpayer/account_status`](/reference/methods#account_status) method. To get more details, use the [`npd/accruals`](/reference/reference-methods.mdx#accruals) method. --- - [Payouts to a self-employed person with a fiscal receipt](https://developer.131.ru/en/selfemployed/selfemployed-payout): Sending payouts to a self-employed person with fiscalization To avoid accounting issues for you and problems with the Federal Tax Service for the self-employed person, payouts must be fiscalized. To do this, you will need: the payer's INN, the self-employed person's INN, and receipt details (description and cost of services). Before making a payout, verify the following: - the recipient has an active self-employed status - the recipient is connected to Bank 131 - the recipient's annual income, including the current payout, does not exceed 2.4 million rubles (otherwise, the recipient will lose their self-employed status) If at least one condition is not met, the payout will not go through. ### How to make a payout :::info When working with bank cards, you must comply with the PCI DSS requirements depending on the selected payout option. ::: The steps depend on whether or not you use our widget. #### Step 1. Get a public token A public token is required to initialize the widget. Send a token creation request ([`token`](/reference/reference-methods.mdx#token)) specifying `tokenize_widget` as the widget type. In the response you will get a public token. Example ```json showLineNumbers curl -X POST \ 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 '{ // highlight-next-line "tokenize_widget": { "access": true } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setTokenizeWidget() ->build(); $response = $client->widget()->issuePublicToken($request); $publicToken = $response->getPublicToken(); ``` #### Step 2. Initialize the widget Initialize the widget on your website using the public token you received in the previous step. After that, the payee can enter their bank card or account details into the widget form. [How to initialize our card tokenization widget >](/payouts/tokenize-widget) [How to initialize our account tokenization widget >](/payouts/tokenize-account-widget) #### Step 3. Create a payment session Send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/fiscalization`](/reference/methods#sessioninitpayoutfiscalization) method to create a session and a payout at the same time. In this case, specify all the [data for fiscalization](/reference/objects#fiscalization_details), parameters for a payout to a [card](/payouts/russian-card) or [account](/payouts/russian-account-parameters) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 4. Start the payout Send a [`session/start/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization) request specifying the session identifier, [data for fiscalization](/reference/objects#fiscalization_details), and parameters for a payout to a [card](/payouts/russian-card) or [account](/payouts/russian-account-parameters). Request example for a payout to a card with fiscalization using our widget ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { // highlight-next-line "number_hash": "3589c9cad4c0e939f6e01a91710b1bef2db5a7a0a9dca274981511120268d420" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` #### Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.102445Z", "updated_at": "2025-05-27T02:03:00.986650Z", "next_action": "confirm", "payments": [{ "id": "po_2909", "status": "pending", "created_at": "2025-05-27T02:03:00.808800Z", "payment_method": { "type": "card", "card": { "brand": "mir", "last4": "4940", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { $session = $hook->getSession(); //do your logic here } ``` #### Step 6. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 7. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` parameter of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Also, the webhook will return the `receipt` object containing the FTS receipt identifier and a link to it. Follow the link to download the receipt. Receipt example Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` You can make payouts: to a card—by card number, token or hash; to an account—by account number or token; to a YooMoney wallet—by wallet number only. Create a token for a card using the [`tokenize/elements`](/reference/methods#tokenizeelements) method or for an account using the [`tokenize`](/reference/methods#tokenize) method. Alternatively, you can get a hashed number for a card using our [card tokenization widget](/payouts/tokenize-widget) or a token for an account using our [account tokenization widget](/payouts/tokenize-account-widget). #### Step 1. Create a payment session Send a [`session/create`](/reference/reference-methods.mdx#sessioncreate) request. You will receive the payment session identifier in response. You will need it in the subsequent steps. > Alternatively, you can use the [`session/init/payout/fiscalization`](/reference/methods#sessioninitpayoutfiscalization) method to create a session and a payout at the same time. In this case, specify all the [data for fiscalization](/reference/objects#fiscalization_details), parameters for a payout to a [card](/payouts/russian-card), [account](/payouts/russian-account-parameters) or [YooMoney wallet](/payouts/yoomoney) right away and skip the next step. This option is not recommended. Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPayoutSession() ->setMetadata('good') ->build(); $response = $client->session()->create($request); ``` #### Step 2. Start the payout Send a [`session/start/payout/fiscalization`](/reference/reference-methods.mdx#sessionstartpayoutfiscalization) request specifying the session identifier, [data for fiscalization](/reference/objects#fiscalization_details), and parameters for a payout to a [card](/payouts/russian-card), [account](/payouts/russian-account-parameters) or [YooMoney wallet](/payouts/yoomoney). Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\Participant; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Goods delivery', new Amount(10000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590613976192' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('3316004710'); $recipient = new Participant(); $recipient->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230') ->setIncomeInformation($incomeInformation) ->setCard(new BankCard('2200********4940')) ->setAmount(10000, 'rub') ->setRecipient($recipient) ->setMetadata('good') ->build(); $response = $client->session()->startPayoutWithFiscalization($request); ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { // highlight-next-line "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-next-line "session_id":"ps_3230", "fiscalization_details": { // highlight-start "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } // highlight-end }, "payment_method": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": { "account": "410012411727100" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' ``` #### Step 3. Wait for a webhook saying the payout is ready Bank 131 will send you a [`ready_to_confirm`](/reference/reference-webhooks.mdx#ready_to_confirm) webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2025-05-27T02:03:00.705430Z", "updated_at": "2025-05-27T02:03:00.613000Z", "next_action": "confirm", "payments": [{ "id": "po_2909", "status": "pending", "created_at": "2025-05-27T02:03:00.578000Z", "payment_method": { "type": "card", "card": { "last4": "4940", "brand": "mir", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "good", "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }] } }' ``` Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) { $session = $hook->getSession(); //do your logic here } ``` #### Step 4. Confirm or cancel the payout Check the payout details and confirm that you are ready to perform the payout ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). Confirming the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` Canceling the session ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Step 5. Wait for a webhook with the payout results Bank 131 will send you a [`payment_finished`](/reference/reference-webhooks.mdx#payment_finished) webhook. The result of the payout can be found in the `status` parameter of the `payments/payout_list` array. If the status is `succeeded`, then the payout was successful. If the status is `failed`, then an error occurred during the payout. Also, the webhook will return the `receipt` object containing the FTS receipt identifier and a link to it. Follow the link to download the receipt. Receipt example Handling the webhook using SDK ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } ``` #### Sequence diagram ![Payout scheme with fiscalization using our widget](/img/docs/payouts/schema_payout_selfemployed_with_widget_en.png) ```plantuml @startuml PayoutSelfemployedWidget 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 the card or account details ... Partner -> Bank_131: ""session/create"" Bank_131 -> Bank_131: creates a session Bank_131 --> Partner: 200 OK Partner -> Bank_131: ""session/start/payout/fiscalization"" 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"" with a FTS check in the ""receipt"" object Partner --> Bank_131: 200 OK @enduml ``` ![Payout scheme with fiscalization without our widget](/img/docs/payouts/schema_payout_selfemployed_without_widget_en.png) ```plantuml @startuml PayoutSelfemployedNoWidget 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/fiscalization"" 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"" with a FTS check in the ""receipt"" object 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) --- - [Verifying data of a self-employed person](https://developer.131.ru/en/selfemployed/selfemployed-verification): Method for verifying self-employed person data Before making a payout with fiscalization, ensure that the self-employed person's details match those in the Federal Tax Service (FTS) database. Otherwise, the payout will not go through. To verify the details: 1. Send an [`npd/taxpayer/check_personal_info`](/reference/reference-methods.mdx#selfemployed_check) request specifying the self-employed person's INN, full name, and phone number. You will get a request identifier within the `request_id` parameter in the response. 2. Send an [`npd/request/status`](/reference/reference-methods.mdx#selfemployed_check) request specifying the request identifier. The response will show if there is a data mismatch. In case a data mismatch was found, notify the self-employed person so they can update their details with the Federal Tax Service. --- ## API Reference - [Error codes](https://developer.131.ru/en/reference/errors): Errors for all products of Bank 131 :::info * The error codes may be changed without prior notice. * Below are all the errors you can encounter when making either payments or payouts. * The table below provides general descriptions for error codes (`code`), one error code can correlate with different values in the `description` field. * The [`error`](/reference/objects#payment-session-statuses-status) status of the payment session is not final. Please contact Bank 131's support team and wait for a final transaction status. ::: | Error code (`code`) | Error description | What you can do | | ------------------------------------ | ------------------------------------- |--------------------| | `3DS_error` | 3DS authentication failed | 3DS authentication have failed. Retry the operation | | `account_not_found` | Account not found | Check the account number for correctness. If the account number is correct and the account belongs to you, but you receive this error anyway, contact our support team | | `activity_count_exceeded` | The activity limit for the card has been exceeded | Check if the used card has any restrictions and retry the operation. If the error persists, contact our support team | | `amount_is_large` | The transaction amount is too large | Reduce the amount to be received | | `amount_is_small` | The transaction amount is too small | Increase the amount to be received | | `amount_less_allowed_provider` | The payment amount is less than acceptable | Change the payment amount | | `authentication_error` | Authentication error | Check the [`X-PARTNER-SIGN`](/reference/format#authentication) signature | | `authorization_error` | Authorization error | You do not have enough privileges for the operation. Check your projects (`X-PARTNER-PROJECT`). Contact our support team | | `bank_card_expired` | The bank card is past its expiration date | Check the input data for correctness and retry the attempt | | `binding_is_deactivated` | The card is not verified for this agent | Binding is disabled. Contact the support team of the emitting bank | | `capture_timeout` | The transaction was canceled due to the confirmation timeout | No response came from you. Check the transaction status and the session status. If these statuses are unsuccessful and final, retry the operation | | `card_number_does_not_exist` | Invalid card number | Check the card number for correctness and retry the attempt | | `check_error` | Verification error | Retry the request later | | `confirm_timeout` | Transaction canceled due to timeout | Retry the transaction | | `contact_support` | Contact support | Contact our support team | | `declined_by_issuer_bank` | The operation was canceled by the emitting bank | Contact the support team of the emitting bank | | `format_error_amount` | (FPS) Invalid format – amount to pay | Check the amount format and retry the attempt | | `format_error_description` | (FPS) Invalid format – purpose of payout | Check the payout purpose format and retry the attempt | | `format_error_full_name` | (FPS) Invalid format – recipient's full name | Check the recipient's full name format and retry the attempt | | `format_error_phone_number` | (FPS) Invalid format – recipient's phone number | Check the recipient's phone number format and retry the attempt | | `format_error_recipient_bank_id` | (FPS) Invalid format – recipient's bank ID in FPS | Check the recipient's bank ID format and retry the attempt | | `idempotency_key_already_exists` | The previous request with the same key is still in progress | Wait till the previous request is processed | | `idempotency_key_not_supported` | This method cannot be used with an idempotency key | Do not use an idempotency key for this method. Check the list of [methods supporting the idempotency key feature](/reference/format#idempotency-key) | | `idempotency_key_params_mismatch` | The key has already been used for another session | Use another idempotency key | | `identification_error` | Partner identification error | Check that the data is correct and retry the attempt | | `incorrect_amount` | Incorrect amount | Change the amount ot be received | | `incorrect_card_data` | Incorrect card data | Retry the operation with correct card data | | `incorrect_phone_number` | Incorrect phone number | The phone number should contain a country code and 10 digits. For example: 71234567890 | | `insufficient_funds` | The card does not have enough funds | The buyer does not have enough funds, retry the operation later | | `insufficient_wallet_balance` | The wallet does not have enough funds. You will get this error until the balance is replenished | Top up the balance and retry the operation | | `internal_error` | Internal error | Retry the operation later. If the error persists, contact our support team | | `invalid_account` | Invalid account/Inactive account | Check whether the account is on the list of accounts allowed for payouts from the [settlement](/settlement-account/settlement-intro#list_of_accounts), [escrow](/escrow-account/escrow-intro#list_of_accounts), or [collateral account](/payouts/collateral-intro#list_of_accounts) respectively, and retry.If the account is inactive, it either does not exist or has been blocked. Provide a different account | | `invalid_recipient_full_name` | (FPS) Incorrect recipient's full name details | Check the recipient's full name for correctness and retry the attempt | | `invalid_request` | Invalid request | Check your request and retry the attempt (see [Methods](/reference/methods)) | | `invalid_transaction` | Invalid transaction | Check the data and retry the operation later. If the error persists, contact our support team | | `limits_exceeded` | The allowed recipient's limits have been exceeded | Change the amount or abandon the operation | | `not_permitted_by_issuer_bank` | The operation was not permitted by the emitting bank | Contact the support team of the emitting bank | | `not_permitted_to_card` | The transaction is not permitted to the card holder | Contact the support team of the emitting bank | | `npd_service_internal_error` | Self-employed service error | Retry the operation later. If the error persists, contact our support team | | `operation_rejected` | The operation has been rejected for security reasons | Contact our support team | | `phone_number_is_not_associated` | The phone number is not linked to this card | Link the card to the phone number of abandon the operation | | `phone_number_not_belong_card` | Phone number check failed |The operation was canceled by the emitting bank. Contact the support team of the emitting bank | | `provider_exceeds_amount_limit` | Exceeds the one-time deposit limit or the maximum amount of deposits (per day or per month) | Specify a smaller amount or a different period and retry the attempt | | `provider_foreign_transfer_prohibited` | Transfer to a foreign card for this provider is prohibited | Select another card and retry the attempt | | `provider_internal_error` | Provider error | Retry the operation later. If the error persists, contact our support team | | `provider_issuer_unavailable` | The provider issuer is unavailable | Retry the operation later. If the error persists, contact our support team | | `provider_timeout` | Provider response timeout, transaction canceled | Retry the operation later. If the error persists, contact our support team | | `provider_wallet_invalid_account` | An account (wallet) with this ID does not exist or is closed | Check the account ID for correctness | | `provider_wallet_is_blocked` | The wallet is blocked | Contact the support team of the emitting bank | | `provider_wallet_not_identified` | The wallet is not identified. Anonymous wallets cannot be topped up | Choose an identified wallet and retry the attempt | | `qr_expired` | (FPS) QR code expired | Start the operation again | |`rate_has_changed`|The conversion rate has changed |Retry the operation| |`recipient_account_not_found`|The recipient's account is inactive|The account is not found or blocked. Specify another account| |`recipient_activity_count_exceeded`|The allowed recipient's balance has been exceeded |Abandon the operation or decrease the amount to be received | | `recipient_full_name_not_specified` | Missing payee's full name | [Specify a payee's full name](/reference/reference-objects.mdx#participant_details_recipient) | |`recipient_is_blocked` |Recipient blocked|Abandon the operation| |`recipient_not_found`|Recipient not found | Make sure the recipient's details are correct | | `refund_amount_too_large` | The refund amount exceeds the maximum permitted amount | Correct the refund amount and retry the operation | | `routing_internal_error` | Payment condition determination error | Contact our support team | | `sender_account_not_found` |Payer's account not found | Make sure the payer's account is correct| |`sender_is_blocked`|Payer blocked|Abandon the operation| |`sender_not_found` | Payer not found | Make sure the payer's details are correct | | `session_cancelled` | The session has been canceled | If you did not canceled the session, contact our support team | | `session_cancelled_by_partner` | The session has been cancelled by the partner | If you canceled the session, start it again.If you did not canceled the session, contact our support team | | `session_lock_failed` | Operation canceled for security reasons | Abandon your transaction or contact the support team | | `session_wrong_state` | Cannot perform a transaction in this status | Check the [session status](/reference/objects#payment-session-statuses-status). If the session status is `error`, you cannot cancel it. To learn the reasons, contact our support team | | `suspected_fraud` | Suspicious transaction | The operation cannot be performed, contact our support team | | `taxpayer_already_bound` | The self-employed person is already linked to Bank 131 | Check the input data for correctness | | `taxpayer_income_exceeds_amount_limit` | This ticket cannot be registered, it would exceed the self-employed annual amount limit (2,4 mln rubles) | Check the input data for correctness | | `taxpayer_not_bound` | The self-employed person is not linked to Bank 131 | [Link](/selfemployed/selfemployed-binding) the self-employed person to Bank 131 | | `taxpayer_unknown` | The person with this INN is not self-employed | Check the self-employed person's INN and status for correctness. Retry the attempt | | `wallet_internal_error` | Balance operation error | Retry the operation later. If the error persists, contact our support team | --- - [Methods](https://developer.131.ru/en/reference/methods): Commands, addresses, and parameters 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/recurrent/disable \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->disableRecurrentRequestBuilder() ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39') ->build(); $response = $client->recurrent()->disable($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|----------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `recurrent` | + | object | [Token information](/reference/reference-objects.mdx#recurrent_token_info) | Response example ```json showLineNumbers { "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": false, "type": "recurrent_token" }, "status": "ok" } ``` ### `session/cancel` #### 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. #### Endpoint `/api/v1/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/cancel` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/cancel \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->cancel('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/capture` #### Debiting amounts put on hold 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. #### Endpoint `/api/v1/session/capture` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------- | | `session_id` | + | string | Bank 131 session identifier | | `amount_details` | - | object | Amount to be debited. Can be less than the amount on hold, but greater than 0. If not specified, the full amount of the payment will be debited | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->capture('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` #### Endpoint `/api/v2/session/capture` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------- | | `session_id` | + | string | Bank 131 session identifier | | `amount_details` | - | object | Amount to be debited. Can be less than the amount on hold, but greater than 0. If not specified, the full amount of the payment will be debited | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/capture \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->capture('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "updated_at": "2024-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_1313", "status": "succeeded", "created_at": "2024-05-27T02:03:00.000000Z", "finished_at": "2024-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "usd" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2024-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "usd" } }] }] } } ``` ```json showLineNumbers { "error": { "code": "error code", "description": "error description" }, "status": "error" } ``` ### `session/confirm` #### 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. #### 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/confirm` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ------------------ | | `session_id` | + | string | Session identifier | | `confirm_information` | - (mandatory for money transfers, for the transactions with an escrow account or when `requier_confirm_information = true`) | object | [Transaction confirmation information](/reference/reference-objects.mdx#confirm_information) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/confirm \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/create` #### 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. #### Endpoint `/api/v1/session/create` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------| | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `amount_details` | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - (mandatory for payouts) | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - (mandatory for payments) | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPaymentSession() //OR ->createPayoutSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z" } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/create` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------| | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `amount_details` | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - (mandatory for payouts) | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - (mandatory for payments) | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->createPaymentSession() //OR ->createPayoutSession() ->setAmount(10000, 'rub') ->setMetadata('order123') ->build(); $response = $client->session()->create($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z" } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment` #### 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)). #### Endpoint `/api/v1/session/init/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Client data in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Client data in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "05", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('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 ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payment/sync` > 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) #### Endpoint `/api/v1/session/init/payment/sync` #### Request parameters Only required request parameters are listed here. You can find additional parameters by following the links in the object descriptions. | Name | Mandatory | Type | Description | |--------------------------------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | |   `type` | + | string | Payment method type. Possible values: `card` | |   `card` | + | object | [Bank card details](/reference/reference-objects.mdx#card) | |     `type` | + | string | Method of card information transmission. Value: `bank_card` | |     `bank_card` | + | object | [Card information](/reference/reference-objects.mdx#bankcard) | |       `number` | + | string | Card number | |       `expiration_month` | + | string | Month of card expiration, `MM`. Example: `01` | |       `expiration_year` | + | string | Year of card expiration, `YY`. Example: `22` | |       `security_code` | + | string | CVC/CVV code | | `amount_details` | + | object | [Payment amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To pay 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Information about payment sender on your side](/reference/reference-objects.mdx#customer) | |   `reference` | + | string | Payment sender ID in your system | | `payment_options` | + | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | |   `return_url` | + | string | URL to which the user is redirected after the payment has been performed. The URL must be valid | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment/sync \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_203", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payment/sync` #### Request parameters Only required request parameters are listed here. You can find additional parameters by following the links in the object descriptions. | Name | Mandatory | Type | Description | |--------------------------------------------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Payment data](/reference/objects#payment_details) | |   `type` | + | string | Payment method type. Possible values: `card` | |   `card` | + | object | [Bank card details](/reference/reference-objects.mdx#card) | |     `type` | + | string | Method of card information transmission. Value: `bank_card` | |     `bank_card` | + | object | [Card information](/reference/reference-objects.mdx#bankcard) | |       `number` | + | string | Card number | |       `expiration_month` | + | string | Month of card expiration, `MM`. Example: `01` | |       `expiration_year` | + | string | Year of card expiration, `YY`. Example: `22` | |       `security_code` | + | string | CVC/CVV code | | `amount_details` | + | object | [Payment amount](/reference/reference-objects.mdx#amount_details) | |   `amount` | + | int | Amount in ruble decimal format. The value must be greater than zero. To pay 100 rubles, specify `10000` | |   `currency` | + | string | ISO 4217 currency code. Case insensitive. Always: `rub` | | `participant_details` | - | object | [Participants information](/reference/objects#participant_details) | | `customer` | + | object | [Information about payment sender on your side](/reference/reference-objects.mdx#customer) | |   `reference` | + | string | Payment sender ID in your system | | `payment_options` | + | object | [Additional payment parameters](/reference/reference-objects.mdx#payment_options) | |   `return_url` | + | string | URL to which the user is redirected after the payment has been performed. The URL must be valid | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v2/session/init/payment/sync \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://131.ru" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_203", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } ``` ### `session/init/payout` #### 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)). #### Endpoint `/api/v1/session/init/payout` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 1000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->initPayoutSession() ->setCard(new BankCard('4242424242424242')) ->setAmount(1000, 'rub') ->build(); $response = $client->session()->initPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [ { "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/init/payout` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 1000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->initPayoutSession() ->setCard(new BankCard('4242424242424242')) ->setAmount(1000, 'rub') ->build(); $response = $client->session()->initPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/fiscalization` #### Creating a session with a simultaneous payout with fiscalization A method for running a payout to a self-employed person with fiscalization, without creating a session separately. In this case, you pass all the data at once, including the information for fiscalization. The response contains the parameters of the created session and information about the payout ([`payments`/`payout_list`](/reference/objects#payments)) with the data necessary to send the receipt. #### Endpoint `/api/v1/session/init/payout/fiscalization` | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "3300000000", "payer_name": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\Participant; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; use Bank131\SDK\DTO\Amount; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $recipient = new Participant(); $recipient->setFullName('Ivanov Ivan'); $request = RequestBuilderFactory::create() ->initPayoutSessionWithFiscalization() ->setIncomeInformation($incomeInformation) ->setCard(new BankCard('4242424242424242')) ->setAmount(5000, 'rub') ->setRecipient($recipient) ->setMetadata('good') ->build(); $response = $client->session()->initPayoutWithFiscalization($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2909", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "3300000000", "payer_name": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "participant_details.recipient.full_name.not_blank" }, "status": "error" } ``` #### Endpoint `/api/v2/session/init/payout/fiscalization` | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://proxy.bank131.ru/api/v2/session/init/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "3300000000", "payer_name": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\Participant; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; use Bank131\SDK\DTO\Amount; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $recipient = new Participant(); $recipient->setFullName('Ivanov Ivan'); $request = RequestBuilderFactory::create() ->initPayoutSessionWithFiscalization() ->setIncomeInformation($incomeInformation) ->setCard(new BankCard('4242424242424242')) ->setAmount(5000, 'rub') ->setRecipient($recipient) ->setMetadata('good') ->build(); $response = $client->session()->initPayoutWithFiscalization($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2909", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "3300000000", "payer_name": "Vector LLC", "services": [{ "name": "Service description", "amount_details": { "amount": 10000, "currency": "rub" } }] } }, "metadata": "order123", "participant_details": { "recipient": { "full_name": "Ivanov Ivan" } } }] } } ``` ```json showLineNumbers { "error": { "code": "invalid_request", "description": "participant_details.recipient.full_name.not_blank" }, "status": "error" } ``` ### `session/refund` #### Creating a refund A method for returning money to the user after a successful payment. You can return the amount fully or partially. A refund cannot be canceled—before sending the request, make sure that it is really necessary. After completing the refund, Bank 131 will send you a [`payment_refunded`](/reference/webhooks#payment_refunded) webhook with the refund result. #### Endpoint `/api/v1/session/refund` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Identifier of a successful payment session which needs to be refunded | | `amount_details` | - | object | [Amount of the refund](/reference/reference-objects.mdx#amount_details). If not specified, the refund will be made for the full amount of the payment | | `metadata` | - | \* | Additional information | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->refundSession('ps_3230') ->build(); $response = $client->session()->refund($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/refund` #### Request parameters | Name | Mandatory | Type | Description | | --------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Identifier of a successful payment session which needs to be refunded | | `amount_details` | - | object | [Amount of the refund](/reference/reference-objects.mdx#amount_details). If not specified, the refund will be made for the full amount of the payment | | `metadata` | - | \* | Additional information | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/refund \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->refundSession('ps_3230') ->build(); $response = $client->session()->refund($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "refunds": [{ "id": "rf_23", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "amount_details": { "amount": 10000, "currency": "rub" } }] }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/start/payment` #### 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. #### Endpoint `/api/v1/session/start/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | - | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the payer and the recipient) | | `customer` | - | object | [Payment sender information in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment settings](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('return_url'); $request = RequestBuilderFactory::create() ->startPaymentSession('session_id') ->setCard( new BankCard( 'number', 'expiration_month', 'expiration_year', 'security_code' ) ) ->setCustomer( new Customer('reference') ) ->setPaymentOptions($paymentOptions) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "acquiring_payments": [{ "id": "pm_3232", "status": "in_progress", "created_at": "2024-08-21T06:21:56.846204Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` #### Endpoint `/api/v2/session/start/payment` #### Request parameters | Name | Mandatory | Type | Description | |----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | - | object | [Payment data](/reference/objects#payment_details) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the payer and the recipient) | | `customer` | - | object | [Payment sender information in your system](/reference/reference-objects.mdx#customer) | | `payment_options` | - | object | [Additional payment settings](/reference/reference-objects.mdx#payment_options) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "26", "security_code": "123" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('return_url'); $request = RequestBuilderFactory::create() ->startPaymentSession('session_id') ->setCard( new BankCard( 'number', 'expiration_month', 'expiration_year', 'security_code' ) ) ->setCustomer( new Customer('reference') ) ->setPaymentOptions($paymentOptions) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2024-08-21T06:21:36.913863Z", "updated_at": "2024-08-21T06:21:56.832509Z", "payment_list": [{ "id": "pm_3232", "status": "in_progress", "created_at": "2024-08-21T06:21:56.846204Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "country_iso3": "RUS" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://www.131.ru" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } ``` ### `session/start/payout` #### 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. #### Endpoint `/api/v1/session/start/payout` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payment_method` | - | object | [Payout details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->startPayoutSession('session_id') ->build(); $response = $client->session()->startPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout` #### Request parameters | Name | Mandatory | Type | Description | | -------------------- | --------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payout_details` | - | object | [Payout details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->startPayoutSession('session_id') ->build(); $response = $client->session()->startPayout($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/start/payout/fiscalization` #### Starting a payout with fiscalization A method for starting a payout to a self-employed person with fiscalization within an existing session. In the request, you can pass the missing data or replace the ones that have already been passed. #### Endpoint `/api/v1/session/start/payout/fiscalization` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object |[Amount](/reference/reference-objects.mdx#amount_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "330000000000", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }] } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230', $incomeInformation) ->build(); $response = $client->session()->startPayoutWithFiscalization($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout/fiscalization` #### Request parameters | Name | Mandatory | Type | Description | | ---------------------- | --------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `session_id` | + | string | Payment session identifier | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `amount_details` | - | object |[Amount](/reference/reference-objects.mdx#amount_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object | [Information on payout participants](/reference/objects#participant_details) | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/fiscalization \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "fiscalization_details": { "professional_income_taxpayer": { "tax_reference": "590000000000", "payer_type": "legal", "payer_tax_number": "330000000000", "payer_name": "Vector LLC", "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" } }] } } }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230', $incomeInformation) ->build(); $response = $client->session()->startPayoutWithFiscalization($request); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_203", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "4242" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "Goods delivery", "amount_details": { "amount": 5000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "590613976192", "payer_type": "legal", "payer_tax_number": "3316004710", "payer_name": "Vector LLC" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `token` #### Getting a token to work with 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 ```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 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 ```json showLineNumbers { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539" } ``` ```json showLineNumbers { "status": "error", "error": { "description": "acquiring_widget.session_id.not_unique", "code": "invalid_request" } } ``` ### `tokenize` #### Tokenizing a bank account number 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 ```json showLineNumbers { "status": "ok", "token": "2c6ebe1368407b922057efee0fed58360dae1d28af50fa6734bb54c61a763c24", "data": { "masked_account": "40817***9535" } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "The public token is not found", "code": "public_token_invalid" } } ``` ### `tokenize/elements` #### Tokenizing a card number A method for tokenizing a bank card number. As a result, the card number is stored in the Bank 131 system, and you receive a token for making multiple payouts to this card. The token has no expiration date. >To start using this method, please contact your manager in Bank 131. #### Endpoint `/api/v1/tokenize/elements` #### Request parameters | Name | Mandatory | Type | Description | | ------------------ |---------- | ------ | ------------------------------------------------------------------------------ | | `card_elements` | + | object | [Card number](/reference/reference-objects.mdx#card_elements) | Request example ```json showLineNumbers curl -X POST \ https://proxy-stage.bank131.ru/api/v1/tokenize/elements \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "card_elements": [ { "ref": "number", "type": "card_number", "card_number": "4242424242424242" } ] }' ``` #### Response parameters | Name | Mandatory | Type | Description | |--------|-----------|--------|------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `data` | + | object | [Card data](/reference/objects#tokenize_data) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "data": { "number": { "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919", "info": { "masked_card_number": "424242******4242", "card_network": "visa", "card_type": "visa" } } } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Information ### `fps/banks` #### 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 ```json showLineNumbers curl -X GET \ https://demo.bank131.ru/api/v1/fps/banks \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{}' ``` ```php showLineNumbers use Bank131\SDK\Client; $response = $client->fps()->getBanks(); foreach ($response->getBanks() as $bank) { echo $bank->getId(), ' ', $bank->getRuName(), ' ', $bank->getEngName(), PHP_EOL; } ``` Response example ```json showLineNumbers { "banks": [{ "id": "100000000243", "eng_name": "National Standard Bank", "ru_name": "Национальный стандарт" }, { "id": "100000000056", "eng_name": "Khlynov", "ru_name": "Хлынов" },...] } ``` ### `fps/customer_verification` #### 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). #### Endpoint `/api/v1/fps/customer_verification` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------| | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/fps/customer_verification \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_109941", "status": "in_progress", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "payments": [{ "id": "po_31668", "status": "in_progress", "created_at": "2022-03-01T11:57:31.895773Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/fps/customer_verification` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------| | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/fps/customer_verification \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_109941", "status": "in_progress", "created_at": "2022-03-01T11:57:31.652396Z", "updated_at": "2022-03-01T11:57:31.861329Z", "payout_list": [{ "id": "po_31668", "status": "in_progress", "created_at": "2022-03-01T11:57:31.895773Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system_verification", "faster_payment_system_verification": { "phone": "79261234567", "bank_id": "100000000069" } } }, "participant_details": { "recipient": { "first_name": "Иван", "last_name": "Иванов", "middle_name": "Иванович" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `report/account_balance` #### 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 ```json showLineNumbers { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { "current_balance": 20900 } } ``` ```json showLineNumbers { "status": "error", "error": { "code": "Error code", "description": "Error description" } } ``` ### `report/account_statement` #### 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 `date_from` does not match `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (max interval is 1 day)", "code": "invalid_request" } } ``` `date_from` is greater than `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (date_to must be greater than date_from); (max interval is 1 day)", "code": "invalid_request" } } ``` Invalid date in `date_from` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_from", "code": "invalid_request" } } ``` Invalid date in `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_to", "code": "invalid_request" } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` This response is returned in the following cases: - the account number is specified incorrectly - the specified account does not exist - the specified account does not belong to the user who initiated the request ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` ### `session/status` #### 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. #### Endpoint `/api/v1/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->status('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa", "bin": "220220" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/status` #### Request parameters | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | -------------------------- | | `session_id` | + | string | Payment session identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->status('session_id'); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "bin": "220220" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `token/info` #### 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 You send a card number hash and receive information about it. ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "card_number_hash (token)" } } }' ``` You send a public token and receive information about it. ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "public_token", "public_token": { "token": "your_token" } }' ``` You send a token and receive information about it. ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "recurrent_token", "recurrent_token": { "token": "your_token" } }' ``` You send a token and receive information about it. ```json showLineNumbers curl -X POST \ https://proxy-stage.bank131.ru/api/v1/token/info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "bank_account_ru", "bank_account_ru": { "token": "4371c4633033d3e7f468c8ca5f50f7dd10c00fe8655563c3da759c16b505ba93" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | | ------ | --------- | ------------ | ------------------------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok` | | `info` | - | object | Information about the token, depending on the type of request (`type`): [tokenized bank card](/reference/reference-objects.mdx#card_token_info), [public token](/reference/reference-objects.mdx#public_token_info), [token for recurring payments or payouts](/reference/reference-objects.mdx#info_recurrent), or [bank account token](/reference/reference-objects.mdx#bank_account_ru_info) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "info": { "number_hash": "card_number_hash", "brand": "visa", "last4": "4242", "type": "card" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2021-03-17T14:10:56+03:00", "finished_at": "2021-03-18T14:10:56+03:00", "is_active": true, "type": "public_token" } } ``` ```json showLineNumbers { "status": "ok", "info": { "token": "your_token", "created_at": "2021-03-17T14:19:05+03:00", "finished_at": "2021-04-17T14:19:05+03:00", "is_active": true, "type": "recurrent_token" } } ``` ```json showLineNumbers { "status": "ok", "info": { "masked_account": "40817***9535", "created_at": "2024-02-08T17:17:44+03:00", "finished_at": "2124-02-08T17:17:44+03:00", "type": "bank_account_ru" } } ``` ### `wallet/balance` #### 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/wallet/balance \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_datetime": "2019-10-14T19:53:00+03:00" }' ``` ```php showLineNumbers use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $walletBalanceResponse = $client->wallet()->balance(); $wallets = $walletBalanceResponse->getWallets(); ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `wallets` | - | object | [List of guarantee payment accounts available at Bank 131](/reference/reference-objects.mdx#wallets) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "wallets": [{ "id": "131", "amount_details": { "amount": 13100, "currency": "rub" } }] } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Self-employed people ### `self_employed/onboarding/create` #### Creating a connection request A method for creating a connection request to connect a self-employed person to Bank 131. #### Request endpoint `/api/v1/self_employed/onboarding/create` #### Request parameters | Parameter | Mandatory | Type | Description | |---------------|-----------|--------|-------------------------------------------------------------------| | `return_url` | - | string | URL to redirect the self-employed person after connecting | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/self_employed/onboarding/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "return_url": "https://131.ru/" }' ``` #### Response parameters | Parameter | Mandatory | Type | Description | |-----------------|-----------|---------|----------------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `onboarding` | + | object | [Connection request data](/reference/reference-objects.mdx#onboarding) | | `npd_status` | + | string | [Federal Tax Service (NPD) status](/reference/reference-objects.mdx#npd_status) | | `binding_status`| + | boolean | Self-employed person connection status. Values: `true` — connected, `false` — not connected | | `description` | - | string | Populated if the connection fails | Response example ```json showLineNumbers { "status": "ok", "onboarding": { "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de", "redirect_url": "https://smz.131.ru/onboarding/019fd6ca-b080-798e-a1bf-eb7dc096e1de", "onboarding_status": "created", "kyc_status": "not_started" }, "npd_status": "not_started", "binding_status": false, "description": "ok" } ``` ### `self_employed/onboarding/status` #### Checking the connection status A method for checking the connection status. #### Request endpoint `/api/v1/self_employed/onboarding/status` #### Request parameters | Parameter | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------| | `id` | + | string | Connection request identifier | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/self_employed/onboarding/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de" }' ``` #### Response parameters | Parameter | Mandatory | Type | Description | |-----------------|-----------|---------|----------------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `onboarding` | + | object | [Connection request data](/reference/reference-objects.mdx#onboarding) | | `npd_status` | + | string | [Federal Tax Service (NPD) status](/reference/reference-objects.mdx#npd_status) | | `binding_status`| + | boolean | Self-employed person connection status. Values: `true` — connected, `false` — not connected | | `description` | - | string | Populated if the connection fails | Response example ```json showLineNumbers { "status": "ok", "onboarding": { "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de", "redirect_url": "https://smz.131.ru/onboarding/019fd6ca-b080-798e-a1bf-eb7dc096e1de", "onboarding_status": "created", "kyc_status": "not_started" }, "npd_status": "not_started", "binding_status": false, "description": "ok" } ``` ### `npd/accruals` and `npd/request/status` #### Checking the self-employed person's tax debt and bonus in detail A method for getting detailed information about tax arrears and bonus amount for a self-employed person. The request consists of two steps: 1. Send an `npd/accruals` request, passing a self-employed person's tax ID, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive detailed information about tax accruals and bonus amount for the self-employed. #### Endpoint to send the `npd/accruals` request `/api/v1/npd/accruals` #### Request parameters for `npd/accruals` | Name | Mandatory | Type | Description | | --------------------- | -------------- | ------ | --------------------------------------------------------------------------- | | `tax_reference_list` | + | array | List of tax reference numbers (INN). Limited to 100 INNs per single request| Request example for npd/accruals ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/accruals \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference_list": [ "111111111111" ] }' ``` #### Response parameters for `npd/accruals` | Name | Mandatory | Type | Description | |--------------|-----------|--------|---------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | - | string | Identifier | Response example for npd/accruals ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/accruals` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `accruals` | - | jagged array | | |   `tax_charge_list`| - | array | List of various taxes accrued | |     `amount` | - | string | Accrued amount | |     `due_date` | - | string | Payment due date | |     `tax_period_id` | - | string | Tax period identifier. The value format: YYYYMM | |     `oktmo` | - |string | Russian National Classification of Municipal Territories (OKTMO) of the activity region | |     `kbk` | - | string | Budgetary classification code | |     `paid_amount` | - |string | Amount of payments received in Automated Information System (AIS) Tax 3 by this accrual | |     `create_time` | - | string | Date and time of the tax accrual | |     `id` | - | string | Internal identifier of the tax accrual in the Self-employment tax (NPD) Payment order (PP) | |   `krsb_list` | - | array | Debt data by the fiscal compliance card | |     `debt` | - | string | Debt amount by the fiscal compliance card | |     `penalty` | - | string | Penalty amount by the fiscal compliance card | |     `overpayment` | - |string | Overpayment amount by the fiscal compliance card | |     `oktmo` | - | string | Russian National Classification of Municipal Territories (OKTMO) of the activity region related to the fiscal compliance card (KRSB) | |     `kbk` | - | string | Budgetary classification code related to the fiscal compliance card (KRSB) | |     `tax_organ_code` | - | string | Code of the tax authority related to the fiscal compliance card (KRSB) | |     `update_time` | - | string | Date / Time of card revision in the Self-employment tax (NPD) Payment order (PP) | |     `id` | - | string | Internal identifier of the card in the Self-employment tax (NPD) Payment order (PP) | |   `inn` | - | string | Tax reference number (INN) | Response example for npd/request/status ```json showLineNumbers { "status": "ok", "accruals": [{ "tax_charge_list": [{ "amount": "", "due_date": "", "tax_period_id": "", "oktmo": "", "kbk": "", "paid_amount": "", "create_time": "", "id": "" }], "krsb_list": [{ "debt": "", "penalty": "", "overpayment": "", "oktmo": "", "kbk": "", "tax_organ_code": "", "update_time": "", "id": "" }], "inn": "111111111111" }] } ``` ### `npd/notifications/count` and `npd/request/status` #### Checking the number of unread notifications from the Federal Tax Service for the self-employed A method for getting the number of unread notifications from the Federal Tax Service to the self-employed. The request consists of two steps: 1. Send an `npd/notifications/count` request, passing a self-employed person's tax ID, and receive the `request_id` identifier in response. 2. Periodically send an `npd/request/status` request with this identifier. In response, you will receive the number of unread notifications. If the status is `pending`, retry the request later. #### Endpoint to send the `npd/notifications/count` request `/api/v1/npd/notifications/count` #### Request parameters for `npd/notifications/count` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `tax_reference_list` | + | array | List of tax reference numbers (INN) (limited to 1000 per single request) | Request example for npd/notifications/count ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/count \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference_list": [ "123456789012" ] }' ``` #### Response parameters for `npd/notifications/count` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | + | string | Identifier | Response example for npd/notifications/count ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/count` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | --------- | --------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `info` | - | array | [Number of notifications](/reference/reference-objects.mdx#notification_count_info) | Response example for npd/request/status ```json showLineNumbers { "status": "ok", "info": [{ "tax_reference": "123456789012", "count": 0 }] } ``` ### `npd/notifications/mark_as_delivered` and `npd/request/status` #### Sending a notification to the Federal Tax Service regarding the delivery of a notification to the self-employed A method for informing the Federal Tax Service that notifications were delivered to a self-employed person. This method must be used after the [`npd/notifications/read`](/reference/methods#read) method. The request consists of two steps: 1. Send an `npd/notifications/mark_as_delivered` request, passing a self-employed person's tax ID, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive the status of the delivery. #### Endpoint to send the `npd/notifications/mark_as_delivered` request `/api/v1/npd/notifications/mark_as_delivered` #### Request parameters for `npd/notifications/mark_as_delivered` | Name | Mandatory | Type | Description | | ------------------ | ----------| ----- | --------------------------------- | | `notification_list` | + | array | [Information about notifications](/reference/reference-objects.mdx#notification_list) | Request example for npd/notifications/mark_as_delivered ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/mark_as_delivered \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "notification_list": [{ "message_id_list": [ "123", "234" ], "tax_reference": "123456789012" }] }' ``` #### Response parameters for `npd/notifications/mark_as_delivered` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier | Response example for npd/notifications/mark_as_delivered ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/read` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | Response example for npd/request/status ```json showLineNumbers { "status": "ok" } ``` ### `npd/notifications/read` and `npd/request/status` #### Fetching detailed information on unread notifications from the Federal Tax Service for the self-employed A method for getting detailed information on unread notifications from the Federal Tax Service to the self-employed. The request consists of two steps: 1. Send an `npd/notifications/read` request, passing a self-employed person's tax ID, and receive the `request_id` identifier in response. 2. Periodically send an `npd/request/status` request with this identifier. In response, you will receive detailed information about unread notifications. If the status is `pending`, retry the request later. #### Endpoint to send the `npd/notifications/read` request `/api/v1/npd/notifications/read` #### Request parameters for `npd/notifications/read` | Name | Mandatory | Type | Description | |----------------------|-----------|---------|---------------------------------------------------------------------------------------------------------| | `tax_reference_list` | + | array | List of tax reference numbers (INN) | | `get_read` | + | boolean | Send the already read notifications in response. Possible values: `true` – send; `false` – do not send | | `get_archived` | + | boolean | Send the archived notifications in response. Possible values: `true` – send; `false` – do not send | Request example for npd/notifications/read ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/read \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference_list": [ "123456789012" ], "get_read": false, "get_archived": false }' ``` #### Response parameters for `npd/notifications/read` | Name | Mandatory | Type | Description | |--------------|-----------|--------|---------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | + | string | Identifier | Response example for npd/notifications/read ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/read` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `info` | - | array |[ List of parameters for each tax reference number (INN)](/reference/reference-objects.mdx#notification_info)| Response example for npd/request/status ```json showLineNumbers { "status": "ok", "info": [{ "tax_reference": "123456789012", "notifications": [{ "id": "132313", "title": "131.ru is asking for permission to act on your behalf", "message": "131.ru has asked you for permission to perform certain operations on your behalf. You can view the list of the operations and grant the permission by clicking Allow, or deny by clicking Deny", "status": "NEW", "created_at": "2023-03-22T13:29:55+00:00" }] }] } ``` ### `npd/notifications/update` and `npd/request/status` #### Informing the Federal Tax Service regarding the reading of a notification by the self-employed A method for informing the Federal Tax Service that notifications were read by the self-employed. The method must be used after the [`npd/notifications/mark_as_delivered`](/reference/methods#mark_as_delivered) method. The request consists of two steps: 1. Send an `npd/notifications/update` request, passing a self-employed person's tax ID, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive the status of the request. #### Endpoint to send the `npd/notifications/update` request `/api/v1/npd/notifications/update` #### Request parameters for `npd/notifications/update` | Name | Mandatory | Type | Description | | ------------------ | --------- | ------ | ------------------------------ | | `notification_list` | + | array | [Information about notifications](/reference/reference-objects.mdx#notification_list) | Request example for npd/notifications/update ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/notifications/update \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "notification_list": [{ "tax_reference": "123456789012" }] }' ``` #### Response parameters for `npd/notifications/update` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | - | string | Identifier | Response example for npd/notifications/update ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/notifications/update` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | Response example for npd/request/status ```json showLineNumbers { "status": "ok" } ``` ### `npd/taxpayer/account_status` and `npd/request/status` #### Checking the self-employed person's tax debt and bonus A method for getting general information about tax arrears and bonus amount for the self-employed. The request consists of two steps: 1. Send an `npd/taxpayer/account_status` request, passing a self-employed person's tax ID, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive general information about tax accruals and bonus amount for the self-employed. #### Endpoint to send the `npd/taxpayer/account_status` request `/api/v1/npd/taxpayer/account_status` #### Request parameters for `npd/taxpayer/account_status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `tax_reference` | + |string | Tax reference number (INN). Limited to 1 INN per single request | Request example for npd/taxpayer/account_status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/taxpayer/account_status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tax_reference": "123456789012" }' ``` #### Response parameters for `npd/taxpayer/account_status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `request_id` | - | string | Identifier | Response example for npd/taxpayer/account_status ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/taxpayer/account_status` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------ | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `bonus_amount`| - | string | Bonus amount | | `unpaid_amount` | - | string | Total unpaid amount | | `debt_amount`| - | string | Unpaid debt, included into total unpaid amount| Response example for npd/request/status ```json showLineNumbers { "status": "ok", "bonus_amount": "9972.3624", "unpaid_amount": "0", "debt_amount": "0" } ``` ### `npd/taxpayer/check_personal_info` and `npd/request/status` #### Verifying a self-employed person's data A method for verifying with the Federal Tax Service if there is any inconsistency in data (INN, full name, phone number) provided by a self-employed person. The request consists of two steps: 1. Send an `npd/taxpayer/check_personal_info` request, passing a self-employed person's tax ID, full name, and phone number, and receive the `request_id` identifier in response. 2. Send an `npd/request/status` request with this identifier. In response, you will receive a list of inconsistent parameters if any. If the status is `pending`, retry the request later. #### Endpoint to send the `npd/taxpayer/check_personal_info` request `/api/v1/npd/taxpayer/check_personal_info` #### Request parameters for `npd/taxpayer/check_personal_info` | Name | Mandatory | Type | Description | | ------------- | -------------- | ------ | ----------- | | `first_name` | + | string | First name | | `second_name` | + | string | Family name | | `patronymic` | + | string | Patronymic name | | `tax_reference` | + | string | Tax reference number (INN) | | `phone` | + | string | Phone number in the "7ХХХХХХХХХХ" format | Request example for npd/taxpayer/check_personal_info ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/taxpayer/check_personal_info \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "bonus_amount": "9972.3624", "unpaid_amount": "0", "debt_amount": "0" }' ``` #### Response parameters for `npd/taxpayer/check_personal_info` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier | Response example for npd/taxpayer/check_personal_info ```json showLineNumbers { "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } ``` #### Endpoint to send the `npd/request/status` request `/api/v1/npd/request/status` #### Request parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | ------------------------------------------------------- | | `request_id` | + | string | Identifier passed in response at `npd/taxpayer/check_personal_info` | Request example for npd/request/status ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/npd/request/status \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" }' ``` #### Response parameters for `npd/request/status` | Name | Mandatory | Type | Description | | ------------------------------- | -------------- | ------------ | ---------------------------------------------------- | | `status` | + | string | Status. Possible values: `error`, `ok`, `pending` | | `success` | - | bool | Inconsistency in data. `true` - consistent data; `false` - inconsistent data | | `violations` | - | array[string] | Parameters with inconsistent data. Possible values: "first_name", "second_name", "patronymic", "tax_reference", "phone"| | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response example for npd/request/status ```json showLineNumbers { "status": "ok", "success": false, "violations": [ "first_name", "second_name", "phone" ] } ``` ## Escrow account ### `session/create/nominal` #### Creating a payment session 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. #### Endpoint `/api/v1/session/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payments": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payout_list": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/nominal` #### Creating a session with a simultaneous payout to a bank account 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. #### Endpoint `/api/v1/session/init/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payments": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/init/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." }, "system_type": "ru" } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payout_list": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/multi/create/nominal` #### Creating a payment session 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. #### Endpoint `/api/v1/session/multi/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/create/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transfer details](/reference/objects#payment_details) | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | - | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | - | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/create/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/init/payment/nominal` #### Creating a session with a simultaneous payout to a bank card 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. #### Endpoint `/api/v1/session/multi/init/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/init/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/init/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" }, "sender": { "full_name": "Ivan Ivanovich Ivanov", "beneficiary_id": "123412341234" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/start/payment/nominal` #### Starting a payout to 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. #### Endpoint `/api/v1/session/multi/start/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/start/payment/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_details` | + | object | [Transfer details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (card, customer account, etc.) | | `fiscalization_details` | + | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `customer` | + | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/start/payment/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_nominal_account", "transfer_from_nominal_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 30000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/start/payout/nominal` #### Starting a payout to a bank account 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. #### Endpoint `/api/v1/session/start/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payment_method": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payments": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout/nominal` #### Request parameters | Name | Mandatory | Type | Description | |---------|-----------|--------------------------------------------------------------|----------------------------------------| | `session_id` | + | string | Payment session identifier | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details). Transmitted in the ruble decimal format. To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Information about the participants](/reference/objects#participant_details) (the sender and the recipient) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | Request examples ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payout_details": { "type": "bank_account", "bank_account": { // highlight-start "system_type": "ru", // for FPS payouts, use the faster_payment_system object // highlight-end "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40702810500000000001", "full_name": "Company name", "inn": "1111111111", "kpp": "156605101", "description": "Funds transfer according to the contract for December of 2022 VAT exempt." } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------| | `status` | + | string | Status. Valid values: `error`, `ok` | | `session` | - | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2023-05-10T16:58:43.586072Z", "updated_at": "2023-05-10T16:58:43.705620Z", "payout_list": [{ "id": "po_72265", "status": "in_progress", "created_at": "2023-05-10T16:58:43.781934Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810900000000001", "full_name": "Company name", "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt", "is_fast": false, "kpp": "156605001", "inn": "3111104710" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "paymentMetadata": {}, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Settlement account ### `session/create/rko` #### Creating a payment session 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. #### Endpoint `/api/v1/session/create/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/create/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | - | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/init/payout/rko` #### Creating a session with a simultaneous payout to a bank account 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. #### Endpoint `/api/v1/session/init/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, // highlight-start "participant_details": { "sender": { "account": "40702810900000000011" } // highlight-end } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/init/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, // highlight-start "participant_details": { "sender": { "account": "40702810900000000011" } // highlight-end } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Session details](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ### `session/multi/create/rko` #### 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. #### Endpoint `/api/v1/session/multi/create/rko` | Name | Mandatory | Type | Description | |-----------------------|-----------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transaction details](/reference/objects#payment_details) | | `payment_method` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory for payouts to bank cards) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "****************" } } }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/create/rko` | Name | Mandatory | Type | Description | |-----------------------|-----------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | - | object | [Transaction details](/reference/objects#payment_details) | | `payout_details` | - | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory for payouts to bank cards) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `amount_details` | - | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `customer` | - | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/create/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "****************" } } }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "123456789012" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/init/payment/rko` #### Creating a session with a simultaneous payout to a bank card 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. #### Endpoint `/api/v1/session/multi/init/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/init/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/init/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/multi/start/payment/rko` #### Starting a payout to a bank card 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. #### Endpoint `/api/v1/session/multi/start/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session id | | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payments": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "acquiring_payments": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` #### Endpoint `/api/v2/session/multi/start/payment/rko` #### Request parameters | Name | Mandatory | Type | Description | |-----------------------|---------------------------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session id | | `payment_details` | + | object | [Transaction details](/reference/objects#payment_details) | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank card, bank account, etc.) | | `customer` | + | object | [Recipient's details in your system](/reference/reference-objects.mdx#customer) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details). Mandatory for payouts to the self-employed. | | `participant_details` | - (mandatory when making a payout to a bank card) | object | [Transaction participants details](/reference/objects#participant_details) (sender and recipient) | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/start/payment/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_12345", "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242" } } }, "participant_details": { "recipient": { "full_name": "Ivan Ivanovich Ivanov" }, "sender": { "full_name": "Ivan Ivanovich Ivanov" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer": { "reference": "test" } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_12345", "status": "in_progress", "created_at": "2021-08-06T11:34:51.274416Z", "updated_at": "2021-08-06T11:34:51.466550Z", "payout_list": [{ "id": "po_25657", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545329Z", "customer": { "reference": "lucky" }, "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "0002" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }], "payment_list": [{ "id": "pm_15174", "status": "in_progress", "created_at": "2021-08-06T11:34:51.545232Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internal_transfer", "internal_transfer": { "type": "transfer_from_bank_account", "transfer_from_bank_account": { "description": "test payout", "card_mask": "400000******0002" } } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "metadata": { "key": "value" }, "participant_details": { "sender": { "full_name": "Ivan Ivanovich Ivanov" }, "recipient": { "full_name": "Ivan Ivanovich Ivanov", "reference": "1234" } } }] } } ``` ```json showLineNumbers { "error": { "description": "error description", "code": "error code" }, "status": "error" } ``` ### `session/start/payout/rko` #### Starting a payout to a bank account 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. #### Endpoint `/api/v1/session/start/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payment_method` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` #### Endpoint `/api/v2/session/start/payout/rko` #### Request parameters | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Payment session identifier | | `payout_details` | + | object | [Payment details](/reference/reference-objects.mdx#payment_method) (bank account) | | `amount_details` | + | object | [Amount in kopecks](/reference/reference-objects.mdx#amount_details). To send 100 rubles, specify `10000` | | `participant_details` | + | object | [Sender's details](/reference/objects#participant_details) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details); only for payouts to the self-employed | | `metadata` | - | * | Any additional details required for the transaction. The details return within responds and webhooks. | Request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------| | `status` | + | string | Status. Possible values: `error`, `ok` | | `session` | - | object | [Payment session details](/reference/objects#payment_session) | | `error` | - | object | [Error](/reference/objects#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme ", "inn": "1234567890", "kpp": "165801002", "description": "Description of payment" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "error description", "code": "error code" } } ``` ## Money transfers ### `calculate` #### 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" } } }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/calculate \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "amounts": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" } } }' ``` #### Response parameters | Name | Mandatory | Type | Description | |----------------------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amounts` | + | object | [Exchange rate calculation](/reference/reference-objects.mdx#amounts_transfers) | |   `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | |     `amount` | + | number | Amount calculated in the sender's currency (rubles) | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | |     `amount` | + | number | Calculated amount to be received | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `transfer_fee` | + | object | [Sender's fee for money transfer](/reference/reference-objects.mdx#transfer_fee) | |     `amount` | + | number | Fee amount to be paid by the sender for the money transfer | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub` | |   `sms_fee` | + | object | [Sender's fee for SMS notification to the recipient](/reference/reference-objects.mdx#sms_fee) | |     `amount` | + | number | Fee amount to be paid for SMS notification to the recipient | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub` | |   `payment` | + | object | [Total amount to write off of the sender](/reference/reference-objects.mdx#payment) | |     `amount` | + | number | Total amount to be written off the sender including all fees. Calculated as `source` + `transfer_fee` + `sms_fee` | |     `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub` | | `exchanges` | + | object | [Exchange rate data](/reference/reference-objects.mdx#exchanges) | |   `source` | + | object | [Amount and currency to write off of the sender (passed in the request)](/reference/reference-objects.mdx#source) | |     `amount` | + | number | Amount in decimal format (kopecks) to calculate the direct exchange rate, or the `null` value to calculate the inverse exchange rate | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `destination` | + | object | [Amount and currency to be paid to the recipient (passed in the request)](/reference/reference-objects.mdx#destination) | |     `amount` | + | number | Amount in decimal format (kopecks) to calculate the inverse exchange rate, or the `null` value to calculate the direct exchange rate | |     `currency` | + | string | ISO 4217 currency code. Case insensitive | |   `rate` | + | object | [Exchange rate](/reference/reference-objects.mdx#rate) | |     `fx_rate` | + | number | Ratio of the currency to ruble (of the target currency to the write-off currency), displayed to 4 decimals. Example: `75.0145` | |     `quantity` | + | number | Quantity of currency units. Some currencies are calculated in tens, hundreds or thousands of units, [the current rates are available on the Bank of Russia website](https://cbr.ru/currency_base/daily) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "amounts": { "source": { "amount": 357913, "currency": "RUB" }, "destination": { "amount": 131426, "currency": "TRY" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 5400, "currency": "RUB" } }, "exchanges": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": null, "currency": "TRY" }, "rate": { "fx_rate": 2.7233, "quantity": 1 } } } ``` ```json showLineNumbers { "amounts": { "source": { "amount": 357912, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "transfer_fee": { "amount": 0, "currency": "RUB" }, "sms_fee": { "amount": 0, "currency": "RUB" }, "payment": { "amount": 9193, "currency": "RUB" } }, "exchanges": { "source": { "amount": null, "currency": "RUB" }, "destination": { "amount": 46943404, "currency": "UZS" }, "rate": { "fx_rate": 76.2433, "quantity": 10000 } } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ### `session/multi/init` #### 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 ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 37700, "currency": "TJS" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "TRY", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "contacts": { "phone": { "full_number": "+79376151530", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TJK", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2204320396205389" } } } }] }' ``` ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v2/session/multi/init \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_list": [{ "amount_details": { // The same as in the payout_list, the amount and currency should be the same "amount": 1000, "currency": "TRY" }, "customer": { "reference": "lucky" }, "participant_details": { "sender": { "citizenship_country_iso3": "RUS", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "state": "Московская область", "city": "Уренгой", "postal_code": "119900", "street": "Конаковская", "building": "99", "flat": "1", "date_of_birth": "1998-03-15", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "issued_by": "ОВД ПО Кировскому району", "division_code": "123-543" }, "contacts": { "phone": { "full_number": "+79376151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/" }, "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4111111111111111" } } } }], "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same "amount_details": { "amount": 1000, "currency": "TRY" }, "participant_details": { "recipient": { "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "date_of_birth": "2000-11-08", "country_iso3": "TRY", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } } }] }' ``` #### Response parameters | Name | Mandatory | Type | Description | |---------|-----------|--------|--------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `session` | + | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Response examples ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808365", "status": "in_progress", "created_at": "2025-08-08T12:39:15.668563Z", "updated_at": "2025-08-08T12:39:16.388348Z", "payout_list": [{ "id": "po_955259", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439833Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765898", "status": "in_progress", "created_at": "2025-08-08T12:39:16.439730Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+79376151530", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "ok", "session": { "id": "ps_3808544", "status": "in_progress", "created_at": "2025-08-11T07:39:00.076932Z", "updated_at": "2025-08-11T07:39:00.476548Z", "payout_list": [{ "id": "po_955266", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528662Z", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "iban", "iban": { "account": "TR12312312" } } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "payment_metadata": {}, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TRY", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TRY", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2766065", "status": "in_progress", "created_at": "2025-08-11T07:39:00.528558Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 1000, "currency": "TRY" }, "amounts": {}, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт гражданина Российской Федерации", "id_number": "8008 579120", "issue_date": "2010-03-01", "division_code": "123-543", "issued_by": "ОВД ПО Кировскому району" }, "citizenship_country_iso3": "RUS", "contacts": { "phone": { "full_number": "+79376151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }] } } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ## Other methods ### `sberpay/push` #### 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 ```json showLineNumbers { "status": "ok" } ``` ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` --- - [Objects](https://developer.131.ru/en/reference/objects): List of objects ## `accept_code` Data for sending a code. | Name | Mandatory | Type | Description | |------------------|----------------|--------|---------------------------------------------------| | `rest_of_attempts` | + | string | Number of code sending attempts | | `active_to` | + | string | Code lifetime | | `callback_url` | + | string | Address to which to send the code | ## `account_details` Information about the sender and recipient accounts. | Name | Mandatory | Type | Description | | ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------ | | `sender` | + | object | [Information about the sender account](/reference/reference-objects.mdx#nominal_payment_sender) | | `recipient` | + | object | [Information about the recipient account](/reference/reference-objects.mdx#nominal_payment_recipient) | ## `account_statement` Statement details. | Name | Mandatory | Type | Description | | -------------- | --------- | ------ | --------------------------------------------------------------- | | `date_from` | + | date | Statement start date | | `date_to` | + | date | Statement end date | | `account_number` | + | string | Account number (20 digits) for which the statement is generated | | `total_turnover` | - | object | [Information on funds movement](/reference/reference-objects.mdx#total_turnover) | | `total_balance` | - | object | [Balance information](/reference/reference-objects.mdx#total_balance) | | `transactions` | - | array | [Information on transactions](/reference/reference-objects.mdx#transactions) | It is not possible to get a list of transactions filtered by date range, amount, or status. ## `acquiring_payments` = `payment_list` >Use `acquiring_payments` for API v1, and `payment_list` for API v2. An array with all the payment details. | Name | Mandatory | Type | Description | |----------------------|-----------|--------|-----------------------------------------------------------------------------------------------------------------| | `id` | + | string | Unique payment identifier | | `status` | + | string | Payment status Possible values: `succeeded`, `in_progress`, `pending`, `failed` | | `created_at` | + | string | Creation date in ISO 8601 format | | `payment_details` | + | object | [Payment data](/reference/reference-objects.mdx#payment_details) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `amounts` | - | object | [Transaction fee](/reference/reference-objects.mdx#amounts) | | `finished_at` | - | string | Completion date in ISO 8601 format | | `customer` | + | object | [User (payer) details](/reference/reference-objects.mdx#customer) | | `recurrent` | - | object | [Details needed to perform recurring payments](/reference/reference-objects.mdx#recurrent_token_info) | | `participant_details` | - | object | [Participants' details](/reference/reference-objects.mdx#participant_details) | | `refunds` | - | array | [Refund list](/reference/reference-objects.mdx#refunds) | | `customer_interaction` | - | object | [Data needed for user interaction](/reference/reference-objects.mdx#customer_interaction) | | `transaction_info` | - | object | [Transaction details](/reference/reference-objects.mdx#transaction_info) | | `metadata` | - | object | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | | `error` | - | object | [Error description](/reference/reference-objects.mdx#error) | #### Payment statuses (`status`) - `in_progress` – the payment is being processed. - `pending` – awaiting your confirmation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancellation ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). - `succeeded` – the payment has been completed successfully. - `failed` – the payment has not gone through due to an error. ## `acquiring_widget` Settings for the payout form widget (for performing bank card payments). | Name | Mandatory | Type | Description | |-------------------------|-----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session_id` | + | string | Identifies the payment session for which the payment will be performed | | `show_recurrent_checkbox` | - | bool | Whether to display the **Enable automatic payments** checkbox in the widget interface | | `success_return_url` | - | string | URL to which the user is redirected after the payment has been successfully completed | | `failure_return_url` | - | string | URL to which the user is redirected when an error occurs during the payment | | `success_on_hold` | - | bool | Whether to show a message about a successful payment to a payer when holding. By default, `false` and the widget shows a loading screen until the end of the hold | | `redirect_target` | - | string | Redirect link open options: - `top` — outside of all the frames as the top window - `self` — in the same frame - `parent` — in the next-level frame if the frames are nested in one another. Default: `top` | ## `actions` Information about actions taken. | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------| | `confirm` | - | string | Confirmation date in ISO 8601 format | | `capture` | - | string | Capture date in ISO 8601 format | ## `amount` Amount object. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub`, `eur` | ## `amount_details` Amount object. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount in minor currency units. For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Example: `rub` | ## `amounts` Information on the transaction fee. | Name | Mandatory | Type | Description | | ---- | --------- | ------ | --------------------------------------------------------------------------------- | | `fee` | - | object | [Information on the applicable fee](/reference/reference-objects.mdx#fee) | ## `amounts` (for money transfers) The exchange amount, currency, and fees for money transfers. | Name | Mandatory | Type | Description | |--------------|-----------|--------|----------------------------------------------------------------------------------------------------| | `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | | `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | | `transfer_fee` | - | object | [Sender's fee for money transfer](/reference/reference-objects.mdx#transfer_fee) | | `sms_fee` | - | object | [Sender's fee for SMS notification to the recipient](/reference/reference-objects.mdx#sms_fee) | | `payment` | - | object | [Total amount to write off of the sender](/reference/reference-objects.mdx#payment) | ## `balance` Account balance details. | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | --------------------------- | | `current_balance` | - | string | Current account balance (the value can be positive or equal to 0). The value is specified in minor currency units (ruble decimal format). For 100 rubles, the value is `10000` | ## `bank_account` The payout recipient's account description. | Name | Mandatory | Type | Description | |------------------------------------|----------------------------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------| | `system_type` | + | string | Bank payment system. Options: `ru`, `faster_payment_system`, `faster_payment_system_verification` | | `ru` | - (mandatory for `system_type = ru`) | object | [Recipient's Russian bank account (region: ru)](/reference/reference-objects.mdx#ru) | | `faster_payment_system` | - (mandatory for `system_type = faster_payment_system`) | object | [Recipient's data in the Faster Payment System](/reference/reference-objects.mdx#faster_payment_system) | | `faster_payment_system_verification` | - (mandatory for `system_type = faster_payment_system_verification`) | object | [Data for the recipient verification in the Faster Payment System](/reference/reference-objects.mdx#faster_payment_system_verification) | | `iban` | - | object | [Money transfer recipient's IBAN](/reference/reference-objects.mdx#iban) | ## `bank_account_ru` Bank account details. | Name | Mandatory | Type | Description | | ----------- | --------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `bik` | - (mandatory for the `tokenize` method) | string | Recipient’s Bank Identification Code | | `account` | - (mandatory for the `tokenize` method) | string | Recipient's bank account | | `token` | - (mandatory for the `token/info` method) | string | Bank account token | ## `bank_card` An unencrypted card object. | Name | Mandatory | Type | Description | |------------------|------------------------------------------|--------|---------------------| | `number` | + | string | Card number | | `expiration_month` | - (mandatory for payments if available) | string | Month | | `expiration_year` | - (mandatory for payments if available) | string | Year | | `security_code` | - (mandatory for payments if available) | string | CVC (security code) | | `cardholder_name` | - | string | Cardholder's name | ## `card` The payout recipient's bank card details. | Name | Mandatory | Type | Description | |----------------|-------------------------------------------|--------|--------------------------------------------------------------------------------------------------| | `type` | + (not returned in responses) | string | Card details transmission type. Possible values: `bank_card`, `encrypted_card`, `tokenized_card` | | `bank_card` | - (mandatory for `type = bank_card`) | object | [Unencrypted card](/reference/reference-objects.mdx#bankcard) | | `encrypted_card` | - (mandatory for `type = encrypted_card`) | object | [Card with encrypted fields (tokenized)](/reference/reference-objects.mdx#encrypted_card) | | `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Tokenized card number](/reference/reference-objects.mdx#tokenized_card) | | `brand` | - | string | Card information. Returned in notifications, needed for user display | | `last4` | - | string | Card information. Returned in notifications, needed for user display | | `bin` | - | string | Bank Identification Number (BIN) (the first 6 digits of a card number). To start getting this parameter, contact your account manager at Bank 131 | | `card_id` | - | string | [Card identifier](/payments/payment-intro#cross-identifier-card) | | `country_iso3` | - | string | Country code (ISO 3166-1 alpha-3) | ## `card_elements` The number of a card for tokenizing. | Name | Mandatory | Type | Description | |-------------|-----------|--------|-----------------------------------| | `ref` | + | string | Fixed value, always `number` | | `type` | + | string | Fixed value, always `card_number` | | `card_number` | + | string | Card number | ## `commission` The amount and currency of the commission for money transfers. | Name | Required | Type | Description | |----------|----------|--------|---------------------------------------------------------| | `amount` | + | number | Amount in decimal format to calculate the exchange rate | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `confirm_information` Confirmation information for a transaction. | Name | Mandatory | Type | Description | |------------------|----------------------------------|--------|--------------------------------------------------------------------------------------------------------| | `transfer_details` | + (for payouts to cards) | object | [Information about a transfer](/reference/reference-objects.mdx#transfer_details) | | `account_details` | + (for payouts to bank accounts) | object | [Information about the sender and recipient accounts](/reference/reference-objects.mdx#account_details) | | `exchanges` | + (for money transfers) | object | [Information about exchange rates](/reference/reference-objects.mdx#exchanges) | ## `contacts` An array with the contacts of a user (payout recipient or payment sender). Parent objects: [`customer`](/reference/objects#customer). | Name | Mandatory | Type | Description | | ------ | --------- | ------ | ------------------- | | `email` | - | string | User's email | | `phone` | - | string | User's phone number | ## `contacts` (for money transfers) Contacts of a user (money transfer sender or recipient). Parent objects: [sender](/reference/objects#participant_details_sender), [recipient](/reference/objects#participant_details_recipient). | Name | Mandatory | Type | Description | |--------|-----------|--------|--------------------------------------------------------------| | `email` | - | string | User's email | | `phone` | - | object | [User's phone number](/reference/reference-objects.mdx#phone) | ## `counter_party` Counterparty details. | Name | Mandatory | Type | Description | |----------------|-----------|--------|-------------------------------| | `kpp` | - | string | Counterparty's KPP | | `inn` | - | string | Counterparty's INN | | `name` | + | string | Counterparty's name | | `account_number` | + | string | Counterparty's account number | | `bank_code` | + | string | Counterparty's bank BIK | ## `customer` (user in your system) Data about the user (payout recipient or payment sender) in your system, E.g. the login that lets you identify the user. Also includes their contact details. Parent arrays: [`acquiring_payments`/`payment_list`](/reference/reference-objects.mdx#acquiring_payments), [`payments`/`payout_list`](/reference/reference-objects.mdx#payments). | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------------------------------------------| | `reference` | + | string | Identifier of the user (payout recipient or payment sender) in your system (up to 128 characters) | | `contacts` | - | array | [User contacts](/reference/reference-objects.mdx#contacts) | ## `customer` (payer) Information about the payer of a payout from an escrow account. Parent objects: [`transfer_details`](/reference/reference-objects.mdx#transfer_details). | Name | Mandatory | Type | Description | | ---------------------------- | --------- | ------ | ---------------------------------------------------------- | | `account_number` | - | string | Account number | | `name` | - | string | Name | | `bank_name` | - | string | Bank's name | | `bik` | - | string | Bank's BIC | | `correspondent_account_number` | - | string | Correspondent account number | | `inn` | - | string | Bank's INN (for cash and settlement only) | | `kpp` | - | string | Bank's KPP (for cash and settlement only) | ## `customer_authorization` Information required for payments by Uzcard or Humo cards. | Name | Mandatory | Type | Description | |-------------|----------------|--------|--------------------------------------------------------------------------------------------------| | `type` | + | string | Authentication type. Always: `sms` | | `suspend_key` | + | string | Confirmation key required when sending a code | | `accept_code` | + | object | [Data for sending a code](/reference/reference-objects.mdx#accept_code) | | `resend_sms` | + | object | [Data for requesting a new code](/reference/reference-objects.mdx#resend_sms) | ## `customer_interaction` An object describing customer interaction. | Name | Mandatory | Type | Description | |----------|-------------------------------------|--------|------------------------------------------------------------------| | `type` | + | string | Customer interaction type. Possible values: `redirect`, `inform` | | `redirect` | - (mandatory for `type = redirect`) | object | [User redirect data](/reference/reference-objects.mdx#redirect) | | `inform` | - (mandatory for `type = inform`) | object | [Payment option data](/reference/reference-objects.mdx#inform) | ## `data` (user account) Masked user account data. | Name | Mandatory | Type | Description | | -------------- | -------------- | ------------------ | ------------------------------------------------- | | `masked_account` | + | string | First 5 and last 4 digits of an account | ## `data` (token and card number) Token and tokenized card details. Returns in response to the [`tokenize/elements`](/reference/reference-methods.mdx#tokenizeelements) request. | Name | Required | Type | Description | |--------|----------|--------|--------------------------------------------------------------| | `number` | + | object | [Token information](/reference/reference-objects.mdx#number) | ## `destination` The amount and currency to be paid to the recipient for money transfers. | Name | Required | Type | Description | |----------|----------|--------|---------------------------------------------------------| | `amount` | + | number | Amount in decimal format to calculate the exchange rate | | `currency` | + | string | ISO 4217 currency code. Case insensitive | Additional money transfer data. | Name | Required | Type | Description | |--------------------|-----------|--------|-------------------------------------------------------- | | `tcn_code_encoded` | + | string | Money transfer reference number. BASE64-encoded | */} ## `encrypted_card` Card with encrypted fields (tokenized). Transmitted during payouts or payments through the widget. | Name | Mandatory | Type | Description | | -------------------- | --------- | ------ | ---------------------- | | `number_hash` | + | string | Card number hash | | `expiration_date_hash` | - | string | Expiration date hash | | `security_code_hash` | - | string | CVC code hash | | `cardholder_name_hash` | - | string | Cardholder's name hash | ## `error` Error description object. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------------- | | `code` | - | string | Error code | | `description` | - | string | Error description | [View error codes ](/reference/reference-errors.mdx) ## `exchanges` The exchange rate data for money transfers. | Name | Mandatory | Type | Description | |-------------|-----------|--------|--------------------------------------------------------------------------------------------------| | `id` | + | string | ID of the transaction (payout/payment) where the exchange rate was applied | | `source` | + | object | [Amount and currency to write off of the sender](/reference/reference-objects.mdx#source) | | `destination` | + | object | [Amount and currency to be paid to the recipient](/reference/reference-objects.mdx#destination) | | `fx_rate` | + | number | Exchange rate, displayed to 4 decimals | | `commission` | + | object | [Amount and currency of the commission for transfer](/reference/reference-objects.mdx#commission) | ## `faster_payment_system` Data of a user of the Faster Payment System for payouts and payments. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | --------------------------------------------------------------------------------------------- | | `phone` | - (mandatory for payouts) | string | Recipient's phone number | | `bank_id` | - (mandatory for payouts) | string | Identifier of the recipient's bank in the FPS. To get the identifier, use the [`fps/banks`](/reference/reference-methods.mdx#banks_fps) method | | `description` | - (mandatory for payouts) | string | Payout or payment purpose (15 to 140 characters) | | `subscription_service_info` | - | object | [Subscription details](/reference/objects#subscription_service_info) | ## `faster_payment_system_verification` Data for the recipient verification in the Faster Payment System. | Name | Mandatory | Type | Description | |---------|-----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `phone` | + | string | Recipient's phone number | | `bank_id` | + | string | Identifier of the recipient's bank in the FPS. To get the identifier, use the [`fps/banks`](/reference/reference-methods.mdx#banks_fps) method | ## `fee` Information on the applicable fee. The number of objects matches the number of applicable fees. | Name | Mandatory | Type | Description | |----------|-----------|--------|--------------------------------------------------------------------------------------------| | `amount` | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter `10000` | | `currency` | + | string | ISO 4217 currency code. Case insensitive. Options: `rub`, `eur` | ## `fiscalization_details` Fiscalization details. | Name | Mandatory | Type | Description | |------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------| | `professional_income_taxpayer` | + | object | [Fiscalization details for the self-employed](/reference/reference-objects.mdx#professional_income_taxpayer) | ## `iban` Recipient's IBAN for a money transfer. | Name | Mandatory | Type | Description | |----------|----------------|--------|--------------------------------| | `account` | + | string | IBAN of a money transfer recipient | ## `identity_document` Identity document of a money transfer participant. | Name | Mandatory | Type | Description | |--------------------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `id_type` | + | string | Type of the recipient's identity document. Valid values:- Passport of a foreign citizen- Passport of a citizen of the Russian Federation | | `id_number` | + | string | Recipient's identity document series and number (without spaces) | | `issue_date` | + | string | Recipient's identity document issue date in the *YYYY-MM-DD* format | | `id_expiration_date` | - | string | Recipient's identity document expiry date in the *YYYY-MM-DD* format. **Required if available in the document. Otherwise, do not send this field** | | `division_code` | - | string | Code of the division that issued the recipient's identity document. **Required if available in the document** | | `issued_by` | - | string | Name of the division that issued the recipient's identity document. **Required if available in the document** | ## `info` (bank account token) Bank account token details. | Name | Mandatory | Type | Description | |----------------|-----------|--------|---------------------------------------| | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format | | `masked_account` | + | string | Masked bank account | | `type` | + | string | Token type. Always: `bank_account_ru` | ## `info` (tokenized bank card) Details of a tokenized bank card. Returns in response to the [`token/info`](/reference/reference-methods.mdx#token_info) request. | Name | Mandatory | Type | Description | |-------------|-----------|--------|-----------------------------| | `number_hash` | + | string | Token (tokenized bank card) | | `brand` | + | string | Payment system, i.e. `visa` | | `last4` | + | string | Last 4 card numbers | | `type` | + | string | Token type. Always: `card` | ## `info` (notifications number) The number of unread notifications for a self-employed person's tax reference number (INN). | Name | Mandatory | Type | Description | | ------------- | --------- | ------ | ------------------------------------------------------------- | | `tax_reference` | + | string | Tax reference number (INN) | | `count` | - | int | Number of unread notifications per each `tax_reference` value | ## `info` (notifications information) Detailed information about notifications for a self-employed person's tax reference number (INN). | Name | Mandatory | Type | Description | |---------------|-----------|--------|----------------------------------------------------------------------------------------------------| | `tax_reference` | + | string | Tax reference number (INN) | | `notifications` | - | array | [Notifications](/reference/reference-objects.mdx#notifications) for the value from `tax_reference` | ## `info` (public token) Information about a public token. Returns in response to the `token/info` request. | Name | Mandatory | Type | Description | |-------------|-----------|--------|--------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format | | `is_active` | + | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `type` | + | string | Token type. Always: `public_token` | ## `info` (token for recurring payments or payouts) Information about a token for recurring payments or payouts. [More information about recurring payments and token settings](/payments/payment-recurring.mdx). Returns in response to the `token/info` request. | Name | Mandatory | Type | Description | |-------------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format. The setting isn't processed by the Bank | | `is_active` | + | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | | `type` | + | string | Token type. Always: `recurrent_token` | ## `info` (tokenized card details) Tokenized card details. Returns in response to the [`tokenize/elements`](/reference/reference-methods.mdx#tokenizeelements) request. Parent objects: [`number`](/reference/reference-objects.mdx#number). | Name | Required | Type | Description | |--------------------|----------|--------|---------------------| | `masked_card_number` | + | string | Masked card number | | `card_network` | + | string | Card payment system | | `card_type` | + | string | Card type | ## `inform` Payment option data. | Name | Mandatory | Type | Description | |------|-----------|--------|---------------------------------------------------------------------| | `qr` | - | object | [QR code for payments via FPS](/reference/reference-objects.mdx#qr) | ## `internal_transfer` Information about an internal transfer | Name | Mandatory | Type | Description | |-------------------------------|----------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Transfer type. Possible values: `transfer_from_nominal_account`, `transfer_from_bank_account` | | `transfer_from_nominal_account` | - (mandatory for `type = transfer_from_nominal_account`) | object | [Information about a transfer from an escrow account](/reference/reference-objects.mdx#transfer_from_nominal_account) | | `transfer_from_bank_account` | - (mandatory for `type = transfer_from_bank_account`) | object | [Information about a transfer from a settlement account](/reference/reference-objects.mdx#transfer_from_bank_account) | ## `internet_banking` Details on payments via payment systems. | Name | Mandatory | Type | Description | |----------|-------------------------------------|--------|---------------------------------------------------------------------------------------| | `type` | + | string | Payment system. Possible values: `sber_pay`, `tpay` | | `sber_pay` | - (mandatory for `type = sber_pay`) | object | [SberPay payment system transaction details](/reference/reference-objects.mdx#sberpay) | ## `method` Method details. | Name | Mandatory | Type | Description | |-------------------|-----------|--------|------------------------------------------------------------------------| | `name` | + | string | Method name (`account_statement`) | | `account_statement` | + | object | [Statement details](/reference/reference-objects.mdx#account_statement) | | ## `notification_list` The array contains data for informing the Federal Tax Service about statuses of notifications sent to the self-employed. | Name | Mandatory | Type | Description | | --------------- | --------- | --------------- | -------------------------- | | `message_id_list` | - | array[string] | Array with message IDs | | `tax_reference` | + | string | Tax reference number (INN) | ## `notifications` The array contains detailed information about notifications the Federal Tax Service sends to a self-employed person. | Name | Mandatory | Type | Description | |------------|-----------|----------|--------------------------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Identifier | | `title` | + | string | Notification header | | `message` | + | string | Notification body | | `status` | + | string | Status. Possible values:`NEW` – new and unread notification`ACKNOWLEDGED` – read notification`ARCHIVED` – archived notification | | `created_at` | + | dateTime | Notification date | ## `number` Token and tokenized card details. | Name | Required | Type | Description | |-------|----------|--------|-----------------------------------------------------| | `token` | + | string | Token | | `info` | + | object | [Card information](/reference/objects#tokenize_info) | ## `onboarding` Data of the self-employed person's connection request to Bank 131. | Name | Mandatory | Type | Description | |---------------------|-----------|--------|----------------------------------------------------------| | `id` | + | string | Connection request identifier | | `redirect_url` | + | string | Connection link to send to the self-employed person | | `onboarding_status` | + | string | [Connection status](#onboarding_status) | | `kyc_status` | + | string | [Identification status](#kyc_status) | #### Connection statuses (`onboarding_status`) - `created` — the request is created, the self-employed person has no registered account yet. - `need_kyc` — identification is expected - `need_npd` — the Federal Tax Service check is expected - `failed` — the connection failed - `completed` — the connection completed successfully #### Identification statuses (`kyc_status`) - `not_started` — identification has not started yet or will be repeated - `pending` — identification is in progress - `completed` — identification passed - `failed` — identification declined or failed (including due to the connection time limit). You can retry #### Federal Tax Service statuses (`npd_status`) - `not_started` — self-employed status verification and permission assignment not performed - `started` — searching for INN by personal data and checking for possible restrictions - `personal_info_mismatch` — connection declined: the FTS did not match personal data with INN - `registration_required` — INN found, no restrictions. A region (OKTMO) for registration needs to be selected - `registration_pending` — registration application sent, awaiting confirmation of receipt from the FTS - `registration_status_pending` — registration application accepted by the FTS, awaiting a decision - `registration_failed` — registration failed: FTS declined, incorrect data or the connection time limit expired - `binding_pending` — a request to connect the self-employed person to you and assign permissions sent - `binding_status_pending` — a connection request created in the FTS. The self-employed person needs to confirm the permission assignment [in their account](https://lknpd.nalog.ru) - `pending` — connection request result requested, awaiting a response from the FTS - `permissions_missing` — the permission assignment request declined or not confirmed in time. You can restart the connection process - `completed` — the self-employed person is successfully connected, the fiscalization permission granted ## `participant_details` Payout participant details. | Name | Mandatory | Type | Description | |-----------|-----------|--------|-------------------------------------------------------------------------------------| | `sender` | - | object | [Sender's details](/reference/reference-objects.mdx#participant_details_sender) | | `recipient` | - | object | [Recipient's details](/reference/reference-objects.mdx#participant_details_recipient) | ## `payee` Recipient data for tax payments with extended parameters. | Name | Required | Type | Description | | ----------- | -------- | ------ | --------------------------- | | `bik` | + | string | Recipient bank's BIK | | `account` | + | string | Account number | | `account_eks` | + | string | Unified Treasury Account | | `name` | + | string | Recipient name | | `inn` | + | string | Recipient's INN, 10 digits | ## `payer` Sender data for tax payments with extended parameters. | Name | Required | Type | Description | | ---- | -------- | ------ | ------------------------ | | `kpp` | + | string | Sender's KPP, 9 digits | | `inn` | + | string | Sender's INN, 10 digits | ## `payment` The total amount to write off of the sender for money transfers. | Name | Required | Type | Description | |----------|----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amount` | + | number | Total amount to be written off of the sender including all fees. Calculated as [`source`](/reference/reference-objects.mdx#source) + [`transfer_fee`](/reference/reference-objects.mdx#transfer_fee) + [`sms_fee`](/reference/reference-objects.mdx#sms_fee) | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `payment_details` The description of the method for performing the payment. | Name | Mandatory | Type | Description | |-----------------------|--------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Payment method type. Possible values: `card`, `recurrent`, `internet_banking`, `internal_transfer`, `faster_payment_system`, `wallet`, `moneysend` | | `card` | - (mandatory for `type = card`) | object | [Bank card details](/reference/reference-objects.mdx#card) | | `recurrent` | - (mandatory for `type = recurrent`) | object | [Details for repeating the payment using the token](/reference/reference-objects.mdx#recurrent) | | `internet_banking` | - (mandatory for `type = internet_banking`) | object | [Details on payments via payment systems](/reference/objects#internet_banking)| | `internal_transfer` | - (mandatory for `type = internal_transfer`) | object | [Internal transfer details](/reference/reference-objects.mdx#internal_transfer) | | `faster_payment_system` | - (mandatory for `type = faster_payment_system`) | object | [Payment via FPS](/reference/reference-objects.mdx#faster_payment_system) | | `wallet` | - (mandatory for `type = wallet`) | object | [Payment via wallet](/reference/reference-objects.mdx#wallet) | | `moneysend` | - (mandatory for `type = moneysend`) | object | Details of payment via Moneysend | ## `payment_method` = `payout_details` >Use `payment_method` for API v1, and `payout_details` for API v2. The description of the method for receiving the payout. | Name | Mandatory | Type | Description | |----------------|-------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Type of method for receiving the payout. Possible values: `card`, `bank_account`, `wallet`, `tax `, `recurrent`, `tokenized_card`, `moneysend` | | `card` | - (mandatory for `type = card`) | object | [Recipient's bank card](/reference/reference-objects.mdx#card) | | `bank_account` | - (mandatory for `type = bank_account`) | object | [Recipient's bank account](/reference/reference-objects.mdx#bank_account) | | `wallet` | - (mandatory for `type = wallet`) | object | [Recipient's electronic wallet](/reference/reference-objects.mdx#wallet) | | `tax` | - (mandatory for `type = tax`) | object | [ Payouts to the Russian Federal Tax Agency](/reference/reference-objects.mdx#tax) | | `recurrent` | - (mandatory for `type = recurrent`) | object | [Payout with token](/reference/reference-objects.mdx#recurrent) | | `tokenized_card` | - (mandatory for `type = tokenized_card`) | object | [Payout with tokenized card number](/reference/reference-objects.mdx#tokenized_card) | | `moneysend` | - (mandatory for `type = moneysend`) | object | Details of payment via Moneysend | ## `payment_options` Parameters needed to perform the payment. :::warning Do not use `localhost` or `127.0.0.1` as the value of the `return_url` parameter—requests with these values will not be processed. ::: | Name | Mandatory | Type | Description | |------------|-----------|--------|-------------------------------------------------------------------------------------------------| | `return_url` | - | string | URL to which the user is redirected after the payment is performed **Mandatory for payments made without our payment widget** | | `recurrent` | - | bool | Determines whether the payment is to be performed using the saved token | |`platform_details`|- | object|[User's device data](/reference/reference-objects.mdx#platform_details) ## `payments` = `payout_list` >Use `payments` for API v1, and `payout_list` for API v2. An array of payout details. | Name | Mandatory | Type | Description | | --------------------- | --------- | ----------| ------------------------------------------------------------------------------------------------------------------------------- | | `id` | + | string | Payout identifier | | `status` | + | string | Status. Possible values: `succeeded`, `in_progress`, `pending`, `failed` | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | - | string | Completion date in ISO 8601 format | | `customer` | - | object | [Recipient's data in your system](/reference/reference-objects.mdx#customer), e.g. the login that lets you verify the recipient on your side | | `payment_method`/`payout_details` | + | object | [Method of receiving the payout](/reference/reference-objects.mdx#payment_method) | | `amount_details` | + | object | [Amount](/reference/reference-objects.mdx#amount_details) | | `amounts` | - | object | [Transaction fee](/reference/reference-objects.mdx#amounts) | | `fiscalization_details` | - | object | [Fiscalization details](/reference/reference-objects.mdx#fiscalization_details) | | `participant_details` | - | object |[ The details of payout participants](/reference/reference-objects.mdx#participant_details) required to perform the payout, e.g. the names and addresses of the payer and the recipient | | `refunds` | - | array | [Refund list](/reference/reference-objects.mdx#refunds) | | `transaction_info` | - | object | [Transaction details](/reference/reference-objects.mdx#transaction_info) | | `metadata` | - | \* | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks | | `error` | - | object | [Error description](/reference/reference-objects.mdx#error) |   #### Payout statuses (`status`) - `in_progress` – the payment is being processed. - `pending` – awaiting your confirmation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancellation ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). - `succeeded` – the payout has been completed successfully. - `failed` – the payout has not gone through because of an error. ## `period` Tax period description. | Name | Mandatory | Type | Description | |--------|-----------|--------|------------------------------------------------------------------------------------------------| | `type` | + | string | Period type. Possible values: `month`, `quarter` | | `number` | + | number | Depends on the period type. Number from 1 to 12 for `month`, number from 1 to 4 for `quarter` | | `year` | + | string | Year, 4 digits. Example: `2021` | ## `phone` User's phone number details (money transfer sender or recipient). | Name | Mandatory | Type | Description | |---------------|-----------|--------|------------------------------------------------------------------------------------------------------| | `full_number` | + | string | User's full phone number in the `+` format | | `country_iso3` | - | string | User's phone number country code (ISO 3166-1 alpha-3). For transfers to Turkey with cash pickup only | | `operator_code` | - | string | Operator code of the user's phone number. For transfers to Turkey with cash pickup only | | `short_number` | - | string | User's phone number without the operator code. For transfers to Turkey with cash pickup only | ## `platform_details` User's device data. | Name | Mandatory | Type | Description | |---------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | User's device type. Acceptable values: `desktop`, `mobile` | | `os` | + | string | User's operating system. Acceptable values: `ios`, `android`, `windows`, `linux` | | `browser` | + | string | User's browser. Acceptable values: `chrome`, `firefox`, `jivoMobile`, `microsoft edge`, `miui`, `opera`, `safari`, `samsung`, `webKit`, `weChat`, `yandex` | ## `professional_income_taxpayer` Fiscalization details for the self-employed. | Name | Mandatory | Type | Description | |------------------|----------------------------------------|--------|----------------------------------------------------------------------------------------------| | `services` | + | array | [List of services provided (maximum 6)](/reference/reference-objects.mdx#services) | | `tax_reference` | + | string | Self-employed person's INN | | `receipt` | - | object | [Fiscalization receipt](/reference/reference-objects.mdx#receipt). Returned in notifications | | `payer_type` | - | string | [Payer type](#payer_type) | | `payer_tax_number` | - (mandatory for `payer_type = legal`) | string | Payer's INN | | `payer_name` | - (mandatory for `payer_type = legal`) | string | Payer name | #### Payer type Payer type. Possible values: - `legal` – legal entity - `individual` – individual person - `foreign` – non-resident of Russia ## `public_token` Information about a public token. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `qr` QR code for payments via FPS. | Name | Mandatory | Type | Description | | ------- | --------- | ------ | --------------- | | `content` | + | string | Link to QR code | | `img` | + | string | QR code body | ## `rate` The exchange rate for money transfers. | Name | Mandatory | Type | Description | |----------|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fx_rate` | + | number | Ratio of the currency to ruble (of the target currency to the write-off currency), displayed to 4 decimals. Example: `75.0145` | | `quantity` | + | number | Quantity of currency units. Some currencies are calculated in tens, hundreds or thousands of units, [the current rates are available on the Bank of Russia website](https://cbr.ru/currency_base/daily) | ## `receipt` The data of the receipt created during fiscalization. | Name | Mandatory | Type | Description | |--------|-----------|--------|--------------------| | `id` | + | string | Receipt identifier | | `link` | - | string | Receipt link | ## `recipient` (recipient of a payout from an escrow account) Information about the recipient of a payout from an escrow account. Parent objects: [`transfer_details`](/reference/reference-objects.mdx#transfer_details). | Name | Mandatory | Type | Description | | ---------------------------- | --------- | ------ | ---------------------------------------------------------- | | `account_number` | - | string | Account number | | `name` | - | string | Name | | `bank_name` | - | string | Bank's name | | `bik` | - | string | Bank's BIC | | `correspondent_account_number` | - | string | Correspondent account number | | `inn` | - | string | Bank's INN (for cash and settlement only) | | `kpp` | - | string | Bank's KPP (for cash and settlement only) | ## `recipient` (payout recipient details) Payout recipient details. Which details are necessary depend upon the method of receiving the payout. Parent objects: [`participant_details`](/reference/reference-objects.mdx#participant_details). | Name | Mandatory | Type | Description | |----------------|---------------------------------------------------------------|--------|--------------------------------------------------------------------------------------------------------| | `full_name` | - (mandatory for payouts to any cards) | string | Full name | | `first_name` | - | string | First name | | `last_name` | - | string | Last name | | `middle_name` | - | string | Patronymic name | | `company_name` | - | string | Company name | | `reference` | - | string | Recipient identifier in your system | | `tax_reference` | - | string | Taxpayer identifier | | `beneficiary_id` | - (mandatory for the payments and payouts with a beneficiary) | string | INN of the beneficiary | | `country_iso3` | - | string | Country (ISO 3166-1 alpha-3) | | `account` | - | string | Sender's escrow account | | `date_of_birth` | - | string | Recipient's date of birth in the *YYYY-MM-DD* format. Make sure the recipient is 18 years old or older | ## `recurrent` (token for recurring payments or payouts) Token for recurring payments or payouts. Parent objects: [`payment_method`/`payout_details`](/reference/reference-objects.mdx#payment_method), [`payment_details`](/reference/reference-objects.mdx#payment_details). > A new token is generated for each new payment made using the same card. This token is linked to the payment, not to the card. If you need to identify the card, you can use the [Card identifier](/payments/payment-intro#cross-identifier-card). | Name | Mandatory | Type | Description | |-----------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | ## `recurrent` (information about a token for recurring payments or payouts) Information about a token for recurring payments or payouts. [More information about recurring payments and token settings](/payments/payment-recurring.mdx). Parent arrays: [`acquiring_payments`/`payment_list`](/reference/reference-objects.mdx#acquiring_payments). | Name | Mandatory | Type | Description | |-------------|-----------|--------|---------------------------------------------------------------------------------------------------------| | `token` | + | string | Token | | `created_at` | + | string | Creation date in ISO 8601 format | | `finished_at` | + | string | Completion date in ISO 8601 format. The setting isn't processed by the Bank | | `is_active` | + | bool | Possible to conduct the operation with this token: `true` – allowed, `false` – not allowed | | `initiator` | - | string | Recurring payment type. Possible values: `merchant`—an MIT payment (by default), `client`—a CIT payment | | `type` | + | string | Token type. Always: `recurrent_token` | ## `recurrent_token` Token for recurring payments or payouts. | Name | Mandatory | Type | Description | | ----- | --------- | ------ | ----------- | | `token` | + | string | Token | ## `redirect` User redirect data. | Name | Mandatory | Type | Description | |----------|-----------|--------------------------|-------------------------------------------------------| | `url` | + | string | Redirect address including GET parameters | | `base_url` | + | string | Redirect address | | `method` | + | string | Submission method, E.g. `GET`, `POST` | | `qs` | - | map<string,string> | Set of parameters depending on the transaction method | | `params` | - | map<string,*> | Set of parameters depending on the transaction method | >- Check if any parameters are specified in the `qs` and `params` objects. >- Redirect the user to the redirect address specified in `base_url` using the method from the `method` parameter and including all the required parameters in the URL or request body. ## `refunds` An array with details on a refund. | Name | Mandatory | Type | Description | |------------------|-----------|--------|--------------------------------------------------------------------------------| | `id` | + | string | Unique refund identifier | | `status` | + | string | Refund status. Possible values: `in_progress`, `accepted`, `declined`, `error` | | `amount_details` | + | object | [Amount of the refund](/reference/reference-objects.mdx#amount_details) | | `created_at` | + | string | Creation date | | `finished_at` | - | string | Completion date | | `is_chargeback` | - | bool | Whether the refund is made within a chargeback | | `transaction_info` | - | object | [Transaction details](/reference/reference-objects.mdx#transaction_info) | #### Refund statuses (`status`) - `in_progress` – the payment is being processed. - `accepted` – the refund has been completed successfully. - `declined` – Bank 131 has declined the refund. - `error` – the refund has not gone through because of an error. ## `resend_sms` Data for requesting a new code. | Name | Mandatory | Type | Description | |------------------|----------------|--------|-------------------------------------------------------------------------| | `rest_of_attempts` | + | string | Number of the code request attempts left | | `allowed_from` | + | string | Time starting from which a new code can be requested | | `callback_url` | + | string | Address to which to send a new code request | ## `ru` Russian bank account details (region: ru). | Name | Mandatory | Type | Description | | ----------- | ------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `bik` | - (mandatory for payouts without a token) | string | Recipient’s Bank Identification Code | | `account` | - (mandatory for payouts without a token) | string | Recipient's bank account | | `token` | - (mandatory for payouts with a token) | string | Bank account token | | `full_name` | + | string | Individual's full name. In case of a payout to an account of a sole proprietor should be passed in the following format: `ИП `. In case of a payout to a legal entity, enter the entity's name, if it is provided in the agreement. Important: if the name is passed incorrectly the recipient bank may cancel the payout and the payout will be refunded | | `description` | + | string | Payout purpose | | `inn` | - (mandatory for the payouts to the accounts of legal entities and sole proprietors) | string | Recipient's INN, 10 digits for legal entities, 12 digits for individuals, including sole proprietors | | `kpp` | - (mandatory for the payouts to the accounts of legal entities) | string | Recipient's Tax Registration Reason Code (KPP)| | `is_fast` | - | bool | Indicates whether [a speedy payout](/payouts/payout-account-sistema-besp) should be made (via BESP). A speedy payout takes place within an hour, a regular one—up to 3 banking days | ## `sber_pay` SberPay payment 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` 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) Information about the payer of a payout from an escrow account. Parent objects: [`account_details`](/reference/reference-objects.mdx#account_details). | Name | Mandatory | Type | Description | | ---------------------------- | --------- | ------ | ---------------------------------------------------------- | | `account_number` | - | string | Account number | | `name` | - | string | Name | | `bank_name` | - | string | Bank's name | | `bik` | - | string | Bank's BIC | | `correspondent_account_number` | - | string | Correspondent account number | | `inn` | - | string | Bank's INN (for cash and settlement only) | | `kpp` | - | string | Bank's KPP (for cash and settlement only) | ## `sender` (payout payer details) Payout payer details. Which details are necessary depend upon the method of receiving the payout. Parent objects: [`participant_details`](/reference/reference-objects.mdx#participant_details). | Name | Mandatory | Type | Description | |----------------|---------------------------------------------------------------|--------|-------------------------------------| | `full_name` | - | string | Full name | | `first_name` | - | string | First name | | `last_name` | - | string | Last name | | `middle_name` | - | string | Patronymic name | | `company_name` | - | string | Company name | | `reference` | - | string | Recipient identifier in your system | | `tax_reference` | - | string | Taxpayer identifier or Sender's INN (12 digits) | | `beneficiary_id` | - (mandatory for the payments and payouts with a beneficiary) | string | INN of the beneficiary | | `country_iso3` | - | string | Country (ISO 3166-1 alpha-3) | | `account` | - (mandatory for making payouts from an escrow account) | string | Sender's escrow account | | `citizenship_country_iso3`|+ | string | Sender's country of citizenship according to ISO 3166-1 alpha-3| | `state` | - |string | State or region of the sender's place of registration| | `city` | - |string | Locality of the sender's place of registration| | `postal_code` | - |string | Postal code of the sender's place of registration| | `street` | - |string | Street of the sender's place of registration| | `building` | - |string | Building number of the sender's place of registration| | `flat` | - |string | Apartment of the sender's place of registration|| | `date_of_birth` | - |string | Sender's date of birth in the *YYYY-MM-DD* format. Make sure the sender is 18 years old or older| | `description` | - |string | Additional information| | `ipv4` | - | string | IP address of the sender's device | ## `services` An array with a description of the service which the payout is covering for fiscalization purposes. The array may contain **up to 6 services**. >- The restriction on the number of services per receipt is regulated by the Federal Tax Service (not by the Bank). >- If the number of services is greater than six, you can: > - split them into multiple receipts, > - combine them. Example: if 10 consulting services, 10 000 rubles each, were provided, you can specify 10 services, 10 000 rubles each, as a single item instead of specifying each service separately. | Name | Mandatory | Type | Description | |----------------|-----------|---------|-----------------------------------------------------------------| | `name` | + | string | Service name (up to 256 characters) | | `amount_details` | + | object | [Service price](/reference/reference-objects.mdx#amount_details) | | `quantity` | - | integer | Number of services provided. Default value: 1 | > Note: The product of the service price and the number of services provided must equal the amount of the payout. ## `session` A container with data about all the operations performed within a single payment session. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund). | Name | Mandatory | Type | Description | |--------------------|--------------------------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------| | `id` | + | string | Session identifier | | `status` | + | string | Status. Possible values: `created`, `in_progress`, `accepted`, `cancelled`, `error` | | `created_at` | + | string | Creation date in ISO 8601 format | | `updated_at` | + | string | Update date in ISO 8601 format | | `payments`/`payout_details` | - | array | [A list of payouts performed within the session](/reference/reference-objects.mdx#payments) | | `acquiring_payments`/`payment_list` | - | array | [A list of payments performed within the session](/reference/reference-objects.mdx#acquiring_payments) | | `next_action` | - | string | Label indicating actions needed to perform the transaction successfully. Possible values: `confirm`, `capture` | | `error` | - (mandatory for `status = cancelled` and `status = error`) | object | [Error description](/reference/reference-objects.mdx#error) | #### Payment session statuses (`status`) - `created` – the session has been created and is waiting to be started or canceled. - `in_progress` – the payment is being processed. - `accepted` – the payment has been completed successfully. - `cancelled` – the payment has been canceled. - `error` – an unexpected error occurred while processing. >Attention! This status is not final. Please contact Bank 131's support team and wait for a final transaction status. #### Next steps (`next_action`) If this field is not empty, it means that Bank 131 is waiting for you to perform specific actions to continue with the operation: - `confirm` – you need to confirm the operation ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). - `capture` – you need to perform the debit ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) or cancel it ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)). ## `sms_fee` The sender's fee for SMS notification to the recipient. | Name | Mandatory | Type | Description | |----------|-----------|--------|-------------------------------------------------------------| | `amount` | + | number | Fee amount to be paid for SMS notification to the recipient | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `source` The amount and currency to write off of the sender for money transfers. | Name | Mandatory | Type | Description | |----------|-----------|--------|---------------------------------------------------------| | `amount` | + | number | Amount in decimal format to calculate the exchange rate | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `subscription_service_info` Subscription details when re-linking the same payer and bank. | Name | Mandatory | Type | Description | |----------|----------------|--------|-------------------------------------| | `id` | + | string | Subscription identifier (exactly 32 characters) | | `name` | + | string | Subscription name (1-70 characters) | ## `tax` Data for tax payment. | Name | Required | Type | Description | |-------------|----------|--------|------------------------------------------------------------------------------------------------------| | `type` | + | string | Tax type or payment method. Options: `tax_short`, `tax_full` | | `tax_details` | + | object | [Tax payment details](/reference/reference-objects.mdx#tax_details) | ## `tax_details` Data for tax payments. | Name | Required | Type | Description | |-----------------|----------------------------------------------------------|--------|-------------------------------------------------------------------------------| | ``period`` | - (required when `type = full`) | string | [Tax period](#tax-period) | | ``period`` | - (required when `type = tax_short`) | object | [Tax period](/reference/reference-objects.mdx#period) | | ``kbk`` | - (required when `type = full`) | string | Budget classification code, 20 digits | | ``oktmo`` | - (required when `type = full`) | string | All-Russian Classifier of Territories of Municipal Formations, 8 or 11 digits | | ``payment_reason`` | - (required when `type = full`) | string | [Payment reason](#tax-reason) | | ``document_number`` | - (required when `type = full`) | string | [Document number](#tax-doc) | | ``document_date`` | - (required when `type = full`) | string | [Document date](#tax-date) | ##### `Input format for the 'period' field` - If the `payment_reason` field is set to `ТП` or `ЗД`, then the payment frequency established by legislation should be specified in one of the following formats: - for monthly payments: `МС.MM.YYYY`, where MM is the month (from 01 to 12), and YYYY is the year for which the payment is made (e.g., for income tax withholding for February 2020, use `МС.02.2020`) - For taxes paid quarterly: `КВ.QQ.YYYY`, where QQ is the quarter (from 01 to 04), and YYYY is the year for which the tax is paid. - For semi-annual taxes (e.g., Simplified Tax System): `ПЛ.HH.YYYY`, where HH is the half-year (01 or 02), and YYYY is the year for which the tax is transferred. - For annual payments: `ГД.00.YYYY`, where YYYY is the year for which the tax is paid (e.g., for final profit tax calculation for 2019, use `ГД.00.2019`). - If the `payment_reason` field is set to `ТР`, then the demand date is indicated. - If the `payment_reason` field is set to `АП`, then `0` is used. ##### `Input format for the 'payment_reason' field` - `ТП` – when paying the tax/contribution for the current period. - `ЗД` – when voluntarily repaying tax/contribution arrears. - `ТР` – when repaying the debt based on a demand issued by the tax authority or the Social Insurance Fund (FSS). - `АП` – when repaying the debt based on an audit act (before the demand is issued). ##### `Input format for the 'document_number' field` - If the `payment_reason` field is set to `ТП` or `ЗД`, then use `0`. - If the `payment_reason` field is set to `ТР`, use the number of the tax payment demand. - If the `payment_reason` field is set to `АП`, use the number of the decision issued after the audit. ##### `Input format for the 'document_date' field` - If the `payment_reason` field is set to `ТП`, use the date of signing the declaration or `0` if the date is not specified. - If the `payment_reason` field is set to `ЗД`, use `0`. - If the `payment_reason` field is set to `ТР`, use the date of the payment demand. - If the `payment_reason` field is set to `АП`, use the date of the post-audit decision. ## `tokenize_widget` Settings for the tokenization widget. | Name | Mandatory | Type | Description | | ------ | --------- | ---- | ------------------------------------------------------------------- | | `access` | + | bool | Identifies whether this public key can use the tokenization widget. | ## `tokenized_card` A card token. | Name | Required | Type | Description | |-------|----------|--------|-------------| | `token` | + | string | Token | ## `total_balance` Balance information. | Name | Mandatory | Type | Description | |---------|-----------|------|---------------------------------------------| | `opening` | + | int | Opening balance on the statement start date | | `closing` | + | int | Closing balance on the statement end date | ## `total_turnover` Information on funds movement. | Name | Mandatory | Type | Description | |--------|-----------|------|--------------------------------------------------------| | `debet` | + | int | Total debits over the period covered by the statement | | `credit` | + | int | Total credits over the period covered by the statement | ## `transaction_info` Transaction information. | Name | Mandatory | Type | Description | | ---------- | -------------- | ------ | --------------------------------------------------------------------------------- | | `rrn` | - | string | Retrieval Reference Number (a unique identifier generated for a bank transaction) | | `arn` | - | string | Acquirer Reference Number (a unique number assigned to credit card transactions) | | `auth_code` | - | string | Authorization code | | `fp_message_id` | - | string | Unique transaction identifier in FPS | ## `transactions` An array with information on transactions. | Name | Mandatory | Type | Description | |----------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amount` | + | int | Top-up amount (non-negative values only) | | `base_amount` | - | int | Transaction amount in the currency. Should be filled out only for transactions in currencies other than Russian rubles. When using the base currency (RUB), the parameter is optional | | `currency` | + | string | Transaction currency | | `payment_date` | + | date | Transaction date | | `bank_system_id` | + | string | Payment identifier. It is specified for all kinds of payments:- for payments sent via the API - for transfers from another bank- for payments made through online banking | | `transaction_id` | - | string | Transaction identifier. It is specified for payments sent via the API | | `session_id` | - | string | Session identifier. It is specified for payments sent via the API | | `purpose` | + | string | Payment purpose | | `counter_party` | + | object | [Payer information](/reference/reference-objects.mdx#counterparty) | | `type` | + | string | Transaction type. Possible values: `credit` (for replenishment operations), `debet` (for write-off operations) values | ## `transfer_details` Information about a transfer. | Name | Mandatory | Type | Description | |-------------------------------|-----------|--------|--------------------------------------------------------------------------------------------| | `payment_method`/`payout_details` | + | object | [Method of receiving the payout](/reference/reference-objects.mdx#payment_method) | | `customer` | + | object | [Information about a payer](/reference/reference-objects.mdx#nominal_payment_customer) | | `recipient` | + | object | [Information about a recipient](/reference/reference-objects.mdx#nominal_payment_recipient) | | `purpose` | + | string | Payout purpose in the following format: `; card:` | | `amount` | + | object | [Amount](/reference/reference-objects.mdx#amount) | ## `transfer_fee` The sender's fee for money transfer. | Name | Mandatory | Type | Description | |----------|-----------|--------|------------------------------------------------------------| | `amount` | + | number | Fee amount to be paid by the sender for the money transfer | | `currency` | + | string | ISO 4217 currency code. Case insensitive | ## `transfer_from_bank_account` Information on a transfer from a settlement account. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------- | | `description` | + | string | Description | ## `transfer_from_nominal_account` Information on a transfer from an escrow account. | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------- | | `description` | + | string | Description | ## `wallet` Electronic wallet details. | Name | Mandatory | Type | Description | |----------|-----------|--------|-------------------------------------------------------------------------------------| | `type` | + | string | Wallet type. Possible values: `yoomoney` | | `yoomoney` | + | object | [YooMoney wallet details](/reference/reference-objects.mdx#yoomoney) | ## `wallets` Your guarantee payment balance details (this balance is used to perform payouts). | Name | Mandatory | Type | Description | |----------------|-----------|--------|-------------------------------------------------------------------| | `id` | + | string | Balance identifier | | `amount_details` | + | object | [Current balance](/reference/reference-objects.mdx#amount_details) | ## `yoomoney` YooMoney wallet details. :::info For payments, the object must be empty. ::: | Name | Mandatory | Type | Description | | ----------- | --------- | ------ | ----------------------------------------------------------------- | | `account` | + | string | YooMoney wallet number for payouts, 11 to 20 digits. Example: `4100175017397` | | `description` | - | string | Payout description (up to 128 characters) | 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 you decide to work without webhooks, you will need to use a [session/status](/reference/methods#sessionstatus) request each time to understand your next step and the operation result. ::: #### How to get webhooks 1. In your system, create an address to receive webhooks at. 2. Inform your Bank 131 manager of this address. 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 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, it will retry the webhook with increasing intervals. Here is how it works: * The interval between retries increases progressively, but never exceeds 15 minutes. * After 30 minutes, the Bank will stop sending the webhook. :::warning[IMPORTANT!] Additional fields may be added to the webhook payload over time, depending on the payment methods used. Make sure that your service can handle them without failure. ::: 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 you or your users to take the necessary action The Bank sends this webhook to you when you or your users need to carry out certain actions to proceed with the operation. For example, a user might need to go through 3D Secure authentication when paying via bank card. >The maximum waiting time for an action is 60 minutes. If the action does not occur within this time, the operation will automatically be completed with the `canceled` status. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `action_required` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ## `confirmation_payout` #### Bank 131 informs you when money is successfully deposited into the account at the recipient bank The Bank sends you this webhook, specifying the date and time of the funds' deposit, in the following cases: - **funds delivered to the recipient's account** — for payouts through BESP - **transfer accepted by the Central Bank** (i.e., the funds have been debited from Bank 131’s account and sent to the recipient’s bank account) — for regular payouts > The webhook is disabled by default. To start receiving `confirmation_payout` webhooks, contact you Bank 131 manager. The webhook can arrive within up to 7 business days from the transaction date. The webhook may not be received if the recipient bank fails to provide confirmation. Note that this does not affect the actual deposit of funds into the recipient’s account. The payout can be refunded after you receive the webhook. #### Webhook parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------| | `type` | + | string | Webhook type: `confirmation payout` | | `event` | + | string | Payout receipt type. Possible options:- `Payout accepted Central Bank`- `Funds credited recipient's account` | | `event_date` | + | date | Payout receipt date and time according to ISO 8601 | | `transaction_id` | + | string | Unique transaction identifier | | `session_id` | + | string | Unique session identifier | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type":"confirmation_payout", "event":"Funds credited recipient's account", "event_date":"2024-11-27T02:03:00.000000Z", "transaction_id":"po_2018", "session_id":"ps_3230" }' ``` ## `nominal_topup` #### Bank 131 informs you when your escrow account is replenished Bank 131 sends this webhook every time funds are added to your **escrow account** as a result of any internal or bank-to-bank transaction. The webhook body includes information on the amount of added funds and the new balance of your account. > Note that you can give the Bank manager any address to which you would like to receive these notifications. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------------------------|-----------|--------|---------------------------------------------------------------------------------------------| | `inn` | + | string | Recipient`s INN | | `kpp` | - | string | Recipient`s KPP | | `account_number` | + | string | Replenished account number | | `account_balance` | + | int | Current account balance (Amount in minor currency units. For 100 rubles, `10000` is passed) | | `doc_id` | + | string | Document identifier | | `doc_num` | + | string | Document number | | `amount` | + | int | Payment amount (Amount in minor currency units. For 100 rubles, `10000` is passed) | | `currency` | + | string | Payment currency code according to ISO 4217 | | `paymentDate` | + | date | Payment date and time according to ISO 8601 | | `purpose` | - | string | Payment purpose | | `contragent_name` | - | string | Sender's name | | `contragent_inn` | - | string | Sender's INN | | `contragent_kpp` | - | string | Sender's KPP | | `contragent_account_number` | + | string | Sender's account number | | `contragent_bank_bik` | + | string | Sender's bank BIK | | `contragent_bank_name` | - | string | Sender's bank name | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "inn": "3316004790", "kpp": "156605101", "account_number": "40702810600200000014", "account_balance": 518619720, "doc_id": "2080040124641368", "doc_num": "333", "amount": 66660, "currency": "810", "paymentDate": "2023-07-27T20:04:36.807000+03:00", "purpose": "Escrow account replenishment for 5896.60 rubles", "contragent_name": "Vector LLC", "contragent_inn": "1655415696", "contragent_kpp": "165501001", "contragent_account_number": "30110810800000000593", "contragent_bank_bik": "049205131", "contragent_bank_name": "Bank 131" }' ``` ## `payment_finished` #### The Bank informs you of the result of an operation The Bank sends this webhook to you when it has completed an operation (a payment or a payout). The webhook body contains all the details of the operation, including its status (in the `status` field). For example, if you are sending a payout and have received the `succeeded` status in this webhook, it means that the payout has been completed successfully. Also, the webhook body contains information on the Federal Tax Service receipt in the `receipt` parameter: its identifier and a link to download it. Click the link to download the receipt. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `payment_finished` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": 10000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": 10000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": 10000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": 10000, "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' ``` ## `payment_refunded` #### Bank 131 informs you of the result of a refund Bank 131 will send you this webhook after a refund is performed. The notification parameters contain information about the payment session, including all the information about the refunds. The webhook is sent in the following cases: - you made a refund using the [`session/refund`](/reference/reference-methods.mdx#sessionrefund) method - the recipient's bank [returned your payment sent to a Russian bank account](/payouts/payout-refunds.mdx) - within the **chargeback** procedure > If the return is made within the **chargeback** procedure, the `refunds` object contains the following additional line: `"is_chargeback": true`. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `payment_refunded` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_method": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "acquiring_payments": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payout_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payout_details": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", // highlight-next-line "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, // highlight-next-line "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "4242", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 1000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "transaction_info": { "rrn": "425307614919", "auth_code": "057441" }, "metadata": "good", "refunds": [{ "id": "rf_203", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "is_chargeback": true, "amount_details": { "amount": 1000, "currency": "rub" }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] }] } }' ``` ## `ready_to_capture` #### The Bank informs you that the money has been put on hold >If you work with [delayed capture payments](/payments/payment-hold), Bank 131 will **always** send you this webhook before debiting funds. This webhook means that the amount has been put on hold successfully, and the Bank is waiting for your next command. To debit the money, send a ([`session/capture`](/reference/reference-methods.mdx#sessioncapture)) request. To cancel the payment, send a ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) request. #### Webhook parameters | Name | Mandatory | Type | Description | |-----------|-----------|--------|--------------------------------------------------------------------| | `type` | \+ | string | Webhook type: `ready_to_capture` | | `session` | \+ | object | [Payment session](/reference/reference-objects.mdx#payment_session) | Example ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "capture", // highlight-next-line "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "capture", // highlight-next-line "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "metadata": "good" }] } }' ``` ## `ready_to_confirm` #### The Bank is waiting for your confirmation to perform the operation Bank 131 sends this webhook when it is ready to perform an operation (a payment or a payout). You need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a ([`session/confirm`](/reference/reference-methods.mdx#sessionconfirm)) to Bank 131. If something is not right, cancel the operation by sending a ([`session/cancel`](/reference/reference-methods.mdx#sessioncancel)) to Bank 131. >The maximum waiting time for a confirmation is 240 minutes. If no confirmation is received within this time, the operation will automatically be completed with the `canceled` status. For your convenience, you can use automatic payment session confirmation, when you are not required to obtain a `ready_to_confirm` webhook and then confirm it. To set up the automatic payment session confirmation, apply to your manager in Bank 131. #### Webhook parameters | Name | Mandatory | Type | Description | |---------------------|---------------------------------------------------------------------------|--------|---------------------------------------------------------------------------------------------| | `type` | + | string | Webhook type: `ready_to_confirm` | | `session` | + | object | [Payment session](/reference/reference-objects.mdx#payment_session) | | `confirm_information` | - (mandatory for transactions with an escrow account and money transfers) | object | [Transaction confirmation information](/reference/reference-objects.mdx#confirm_information) | Examples ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payments": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_method": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payout_list": [{ "id": "po_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payout_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` ```json showLineNumbers curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", // highlight-next-line "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, // highlight-next-line "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' ``` Time in webhooks is provided in UTC. --- ## Dashboard - [Dashboard](https://developer.131.ru/en/dashboard/dashboard-intro): Merchant's dashboard functionality and advantages Bank 131 provides a service for transaction tracking and analytics—the **Dashboard**. This centralized platform allows you to fully control your business financial flows, see details of each transaction, and resolve issues more quickly. Now, you do not need to request statements from your manager: all data is always at hand. The Dashboard is all about transparency. You see a complete map of fund movements: which transactions succeeded, which failed, and why. This is not just a 'transaction history' but a powerful tool for sales analytics. ## Key benefits for your business **Independent transaction control** You do not need to contact support to obtain information about transactions. Important transaction information is available directly in the Dashboard at any time. **Clear statuses and error details** You will see the current status of each transaction. If a transaction is unsuccessful, the service shows the specific reason. This allows you to respond quickly and minimize the number of unsuccessful transactions. **Transaction analytics for business development (coming soon)** Collect statistics on successful and unsuccessful transactions, analyze trends, identify peak loads and problem scenarios. The Dashboard helps you see not only what happened but also how to optimize everything. **Data security** All transaction data is protected by our corporate security standards and transmitted via secure communication channels. You can be confident in the safety of your business and customer financial information. ## Core features The following options are already available in the Dashboard. You can: * view the [transaction registry](#registry) and the [details of any transaction](#detalization) * search for transactions using the [date filter](#searching) * search for transactions using [AI](#AI) * download transaction reports in CSV format ### Transaction registry The transaction registry allows you to track the complete history of fund movements, including payments, payouts, and refunds. This tool enables you to monitor financial flows without having to contact your manager. The registry displays transaction statuses and key details, allowing you to quickly analyze both successful and unsuccessful transactions. ### Transaction details Click any row in the registry to open a panel with the details of a specific transaction. The details include the following data: * **Session ID** * **Transaction ID** * **Transaction type**: payment, payout, refund * **Method**: SBP, bank card, 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 At the top of the transaction registry panel, you will find a period filter. You can select: * All time: from the start of using the service (this option is selected by default) * Preset periods: 7 days, 30 days, 90 days * Custom period: any arbitrary start and end dates ### AI-powered search In addition to filters, you can use our AI search. Simply enter a query in the search bar—the neural network will instantly analyze the data array and return the most relevant result. AI search understands natural language queries. For example, you can enter "Show all payments via Mir card for November 25" or "Transactions over 5 thousand rubles"—the service will show an exact result, saving your time. ## How to get access To get access to the Dashboard, contact your personal manager at Bank 131. **How to log in:** 1. Wait for an email from Bank 131 to your corporate email address provided during registration. The email will contain your first login credentials: **login (your email) and temporary password (a generated character combination)**. 2. Follow the link in the email. 3. Upon first login, change the temporary password to a permanent one and complete two-factor authentication. ## Development roadmap An analytics dashboard will soon appear in the Dashboard. We plan to add approved transaction charts, conversion reports broken down by payment method, and widgets for monitoring refunds. 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 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 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 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 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 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 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. --- ## Widget - [FPS widget](https://developer.131.ru/en/widget/widget-fps): Widget for payments via FPS To acquire payments using FPS, you can use the Bank 131 widget. You add the widget to the page, display it to the user, and the user then interacts with the widget, going through all the payment steps from beginning to end, and then sees a message telling them that the payment has been successful (or an error message if anything goes wrong). You need to create a payment session, and the widget does the rest: it will send the payment request, redirect the user to the appropriate address, and display them the screen with the result of the operation. [How to acquire FPS payments](/payments/payment-fps-qr) ## How the widget looks like ![](/assets/fps_widget_ru.png) ## Code example of a page with FPS widget added ```html showLineNumbers FPS acquiring document.addEventListener('DOMContentLoaded', function () { if (!window.Bank131SBPPayment) { return; } const widget = new Bank131SBPPayment('public_token'); widget.onReady = function () { console.log('SBPPayment is ready.'); }; widget.onSBPStart = function () { console.log('SBPPayment was started.'); }; widget.onSBPFail = function (error) { console.log('SBPPayment was failed with an error', error); }; widget.onSBPSuccess = function () { console.log('SBPPayment was succeed.'); }; widget.render(); }); ``` ## How to embed the FPS widget #### 1. Set up scripts and CSS styles ```html showLineNumbers ``` ```html showLineNumbers ``` #### 2. Add widget container ```html showLineNumbers ``` #### 3. Create a widget instance After you set up the script, the `Bank131SBPPayment` constructor class becomes available. ```js const widget = new Bank131SBPPayment('public token'); ``` To display the FPS payment form, use the `render()` method: ```js widget.render(); ``` ## Widget API ### `Bank131SBPPayment` FPS payment form instance constructor ```js const widget = new Bank131SBPPayment(publicToken[, options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | publicToken | string | Mandatory public token. | | options | object | Additional settings. | | options.container | HTMLElement | Container with form. Default value: `` | ### `widget.render()` method The method displays the payment form in the page. The container is specified within the `options.container` setting. ```js widget.render([options]) ``` | Parameter | Type | Description | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | options | object | Additional settings. | | options.container | HTMLElement | Container with form. Default value: `` | ### `widget.onReady` event handler The widget is up and ready event handler. ```js widget.onReady = function () { /* handler */ } ``` ### `widget.onSBPStart` event handler Payment start event handler. ```js widget.onSBPStart = function () { /* handler */ } ``` ### `widget.onSBPSuccess` event handler Payment succeeded event handler. ```js widget.onSBPSuccess = function () { /* handler */ }; ``` ### `widget.onSBPFail` event handler Payment failed event handler. ```js widget.onSBPFail = function (error) { /* handler */ } ``` ## How to customize the SBP widget ### Widget appearance You can set up your own styles: ```css /* custom-styles.css */ .bank131-Field__label { color: green; } ``` --- ## Finance - [Daily payment report](https://developer.131.ru/en/finance/payment-daily-report): All successful operations for a day in CSV format The daily report is sent in CSV format to the email address specified in your agreement with Bank 131. If you wish to receive the reports in the XLSX or in a different way, for example, via SFTP, please contact your Bank 131 manager. ### How to use the report The report sent by Bank 131 contains a list of all successful operations for a day (24 hours). You need to check the operations on your side against those in the report. In case of any discrepancy, contact your Bank 131 manager. The timeframe for making corrections is specified in your agreement with the Bank. ### Report file name `_YYYY-MM-DD-YYYY-MM-DD` ### Report fields | Field name | Description |Example | |--------------------------------|-------------------------------------------------------------------------------|-----------------------| | ID | Bank 131 payment identifier | `pm_1237020` | | paymentSessionId | Payment session identifier | `ps_3232` | | Project name | The name of your project on Bank 131's side | `acquiring_card` | | Type of payment | Payment type. Possible options: `Adjustment`, `Advice`, `Refund`, `Recurrent`. [More details](/finance/payment-daily-report#payment-types) | `Advice` | | Amount | Total of the operation in rubles | `110` | | Fee | Bank 131's total fee (as per the agreement). Specified as a negative value | `-2` | | Settlement | Total of the settlement the Bank must transfer to you. The total of the settlement can be negative, for example for `Refund` or `Chargeback` | `-2` | | Transaction Date and Time | Date and time of the transaction on Bank 131's side | `2026-05-01 13:17:56` | | Card number | Masked number of the card/wallet number used to make the payment | `4...1878` | | paymentSessionMerchantMetadata | Your additional data that you passed within the request for the operation | `1Di732vw57` |   ### Payment types - `Adjustment` – partial cancellation of a transaction - `Advice` – successful transaction - `Refund` – rollback of a successful transaction - `Recurrent` – [recurring payment](/payments/payment-recurring) (automatic payment or repeated payment) ### How to receive large report files In case of large amount of data, Bank 131 is able to send report files with one of the methods below: - A CSV or XLSX file split into parts in CSV or XLSX format. - A single ZIP archive file (CSV or XLSX file archived). - A ZIP archive file split into parts (CSV or XLSX file archived and then split into parts). This can help to deal with the issues when your email server cannot process a single email file with a size larger than specified. To know more about this service, please contact your manager at Bank 131. In some cases, Bank 131 can split and/or archive reports based on their own business and/or operational needs. You can specify the number of transactions you want to receive in each part of a report to split the report file in accordance with that number. **An XLSX report example** **Example of split report** ``` acquiring_monthly_2023-02-01-2023-03-01_part_1_of_3.csv acquiring_monthly_2023-02-01-2023-03-01_part_2_of_3.csv acquiring_monthly_2023-02-01-2023-03-01_part_3_of_3.csv ``` 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** **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 '{ // highlight-start "account_number": "40702810400000000333" // highlight-end }' ``` ### Response parameters | Name | Mandatory | Type | Description | |--------------------|-----------|--------|------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `account_number` | - | string | Account number | | `account_currency` | - | string | Account currency according to ISO 4217. Example: `RUB` | | `balance` | - | object | [Balance details](/reference/reference-objects.mdx#balance) | | `error` | - | object | [Error](/reference/reference-objects.mdx#error) | Successful response example ```json showLineNumbers { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { // highlight-next-line "current_balance": 20900 } } ``` Unsuccessful response example ```json showLineNumbers { "status": "error", "error": { "code": "Error code", "description": "Error description" } } ``` --- - [Account statements](https://developer.131.ru/en/statements/statements-escrow): Sending a request to get bank statements for settlement or escrow account You can get bank statements for your settlement or escrow account for any given day in rubles—for example, to confirm a payout. To get a statement, use the [`report/account_statement`](/reference/reference-methods.mdx#reportaccount_statement) method. ### Request parameters | Name | Mandatory | Type | Description | |------------------|-----------|--------|-------------------------------------------------------------------------------| | `account_number` | + | string | Account number (20 digits) for which you request a statement | | `date_from` | + | date | Statement start date. Example: 2023-06-01 | | `date_to` | + | date | Statement end date. It should be the same as `date_from`. Example: 2023-06-01 | Account statement request example ```json showLineNumbers curl -X POST \ https://demo.bank131.ru/api/v1/report/account_statement \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ // highlight-start "date_from": "2023-06-01", "date_to": "2023-06-01", "account_number": "40702810600200000014" // highlight-end }' ``` ### Response parameters | Name | Mandatory | Type | Description | |------------------------------------------------------------------|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | + | string | Status. Options: `error`, `ok` | | `method` | + | object | [Method data](/reference/reference-objects.mdx#method) | |   `name` | + | string | Method name `account_statement` | |   `account_statement` | + | object | [Statement details](/reference/reference-objects.mdx#account_statement) | |     `date_from` | + | date | Statement start date | |     `date_to` | + | date | Statement end date | |     `account_number` | + | string | Account number (20 digits) for which the statement is generated | |     `total_turnover` | + | object | [Information on funds movement](/reference/reference-objects.mdx#total_turnover) | |       `debet` | + | int | Total debits over the period covered by the statement | |       `credit` | + | int | Total credits over the period covered by the statement | |     `total_balance` | + | object | [Balance information](/reference/reference-objects.mdx#total_balance) | |       `opening` | + | int | Opening balance on the statement start date | |       `closing` | + | int | Closing balance on the statement end date | |     `transactions` | + | array | [Information on transactions](/reference/reference-objects.mdx#transactions) | |       `amount` | + | int | Top-up amount (non-negative values only) | |       `base_amount` | - | int | Transaction amount in foreign currency. When using the base currency (RUB), the parameter is optional | |       `currency` | + | string | Transaction currency | |       `payment_date` | + | date | Transaction date | |       `bank_system_id` | + | string | Payment identifier. It is specified for all kinds of payments:- for payments sent via the API - for transfers from another bank- for payments made through online banking | |       `transaction_id` | - | string | Transaction identifier. It is specified for payments sent via the API | |       `session_id` | - | string | Session identifier. It is specified for payments sent via the API | |       `purpose` | + | string | Payment purpose | |       `counter_party` | + | object | [Counterparty details](/reference/reference-objects.mdx#counterparty) | |         `kpp` | - | string | Counterparty's KPP | |         `inn` | - | string | Counterparty's INN | |         `name` | + | string | Counterparty's name | |         `account_number` | + | string | Counterparty's account number | |         `bank_code` | + | string | Counterparty's bank BIK | |       `type` | + | string | Transaction type. Possible values: `credit` (for replenishment operations), `debet` (for write-off operations) values | Successful response example ```json showLineNumbers { "status": "ok", "method": { "name": "account_statement", "account_statement": { "date_from": "2022-11-12T18:19:32.487+0000", "date_to": "2022-11-13T18:19:32.487+0000", "account_number": "40703810500000000025", "total_turnover": { "debet": 0, "debet_base": null, "credit": 100, "credit_base": null }, "total_balance": { "opening": 0, "opening_base": null, "closing": 100, "closing_base": null }, "transactions": [{ "amount": 10000, "base_amount": null, "currency": "RUB", "payment_date": "2022-11-13", "bank_system_id": "2080040097819020", "transaction_id": "c7b923ec-844f-4d98-ad02-795d62fe1989", "session_id": "ps_3230", "purpose": "Account replenishment", "counter_party": { "kpp": "165501001", "inn": "1655415696", "name": "Fee for money transfer processing services", "account_number": "70606810600004710401", "bank_code": "049205131" }, "type": "credit" }] } } } ``` Unsuccessful response examples ##### `date_from` does not match `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (max interval is 1 day)", "code": "invalid_request" } } ``` ##### `date_from` is greater than `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid input request parameters: (date_to must be greater than date_from); (max interval is 1 day)", "code": "invalid_request" } } ``` ##### Invalid date in `date_from` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_from", "code": "invalid_request" } } ``` ##### Invalid date in `date_to` ```json showLineNumbers { "status": "error", "error": { "description": "Invalid value in date_to", "code": "invalid_request" } } ``` ##### Invalid JSON format ```json showLineNumbers { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } ``` ##### Internal error This response is returned in the following cases: - the account number is specified incorrectly - the account does not exist - the account does not belong to the user ```json showLineNumbers { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } ``` ---