# 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 - [API Features](https://developer.131.ru/en/intro): Overview of Bank 131 platform capabilities -- payouts, payments, VAT payment, supported entity types, residency, and payout method matrix 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). 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 > 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 > VAT payment Foreign companies providing electronic services to users in Russia can pay the VAT (the Google tax). Learn more about VAT payments > Was this helpful? Payouts Payment processing VAT payment --- - [Where to Begin](https://developer.131.ru/en/before): Step-by-step onboarding guide -- test setup, key generation, PCI DSS compliance, webhook URL configuration, and go-live checklist Do testing (without real data) Submit an API integration request on Bank 131's website. A Bank 131 manager will contact you, help you gain access, and answer your questions. Issue a secret key and a public key. These keys are intended for test requests only. Performing operations with real data will require different keys. Share your public key with the Bank and get the Bank's public key. If you want to get webhooks from the Bank, provide your account manager with a URL at which you would like to receive them. Upon completing these steps, you will receive a test project identifier--a unique code assigned by the Bank to your business for API authentication. This identifier is required for all requests. For example, it allows the Bank to determine the origin of a payment. Go live :::warning Important! All organizations that process, transmit, or store payment card data, as well as those that do not process, transmit, or store such data directly but are able to impact card data security, are required to comply with the Payment Card Industry Data Security Standard (PCI DSS). The scope of requirements depends on the payout or payment method. Using the widget of Bank 131 reduces the number of applicable requirements. For more information, please visit the official NSPK website. ::: Before starting to work with live data, ensure that all operations in the test mode are completed without errors. Complete your legal entity KYC procedure with Bank 131 and sign an agreement. Open and top up the required accounts: a settlement account-for payouts and payments, including via the Faster Payments System (FPS) an escrow account-for intermediary payments made on behalf of other parties, including via the Faster Payments System (FPS) a collateral account-for payouts and payments, except for the Faster Payments System (FPS) Issue a secret key and a public key for operations with real data. Share your public key with the Bank and get the Bank's public key. Join the Electronic Document Workflow (see the rules). Specify your public key in the Certificate of recognition of the electronic signature verification key. 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. Was this helpful? Do testing (without real data) Go live --- - [API Request Format](https://developer.131.ru/en/reference/format): Request/response structure, authentication with RSA-SHA256 signature generation, idempotency key usage, header reference 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 session/init/payout session/init/payout/fiscalization session/start/payout session/start/payout/fiscalization session/init/payment session/init/payment/sync session/start/payment session/confirm session/capture session/cancel session/refund fps/customer_verification session/status session/init/payout/nominal session/multi/create/nominal session/multi/init/payment/nominal session/multi/start/payment/nominal session/init/payout/rko session/multi/create/rko session/multi/start/payment/rko 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 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 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) and a private key (stored securely on your side). The Bank uses the public key to validate requests. The private key is used to sign your requests and must never be disclosed to anyone. You need to generate these two keys using the RSA algorithm. Creating request body signature The entire request body must be signed exactly as it is sent to the Bank (i.e., the full text in JSON format). Your private key is required to create the signature. The signature is generated using the SHA-256 encryption method. After creation, the signature must be encoded into Base64 format so it can be transmitted with the request. Verifying incoming requests from Bank 131 All outgoing requests from Bank 131 are signed using its secret key. To ensure a request is genuinely from the Bank, you must verify this signature. You use the Bank's public key and the SHA-256 algorithm to perform this verification. The signature is transmitted in Base64 format. Save Bank 131's public key in the PEM format: For live testing Download For demo testing Download Signature generation and validation examples OpenSSL PHP # 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 $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 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 session/init/payout session/init/payout/fiscalization session/start/payout session/start/payout/fiscalization session/init/payment session/init/payment/sync session/start/payment session/confirm session/capture session/cancel session/refund 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 Learn more about the errors > Libraries You can use the PHP SDK library to integrate with Bank 131 API. Was this helpful? API version Endpoint API authenticationRequest signature Idempotency key Libraries --- - [API Testing](https://developer.131.ru/en/reference/testing): Test card numbers (3DS and non-3DS), YooMoney wallets, bank accounts, and failure simulation via `customer.reference` values 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 and download Bank 131's public key for testing in the PEM format Download 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 object--requests with these values will not be processed. Bank cards for test operations Use both cards with 3D Secure support and without it. info You can create any tokens for test cards. Cards with 3D Secure support: Card number | Payment system | Country --- | --- | --- 2200774546102058 | Mir | Russia 4000000000000002 | Visa | USA 5500000000000004 | MasterCard | North Korea To go successfully through 3D Secure, specify: 12345. Cards without 3D Secure support: Card number | Payment system | Country --- | --- | --- 4242424242424242 | Visa | United Kingdom 5101180000000007 | MasterCard | Turkey YooMoney wallet for test operations Use any wallet number containing 11-12 digits. Bank account for test operations Use any account number containing 20 digits. Testing unsuccessful operations To test errors at various stages of payment and payout processing, pass one of the following values in the customer.reference field of the customer object. Value | Result --- | --- thief | For payments only. The payment will be canceled when money is put on hold loser | For payments and payouts. The payment will be canceled when the funds on hold are debited; the payment will result in an error Was this helpful? Bank cards for test operations YooMoney wallet for test operations Bank account for test operations Testing unsuccessful operations --- - [Standard Payout and Payment Scenarios](https://developer.131.ru/en/reference/typical): Typical session-based workflows for payouts and payments with state machine overview 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 and Payments 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. If they are disabled, you will have to send a session/status request each time to understand the next step and transaction results. Payouts Payments The steps depend on whether or not you use our widget. With our widget Without our widget Send a token request to get a public token. The token is used to initialize the widget. Initialize the widget using the received token. Save the hash for future payouts. Start the payout in one of the following ways: send a session/create request and then a session/start/payout request with the session identifier and payout details--the recommended option start a session and the payout simultaneously (session/init/payout) Wait for a ready_to_confirm webhook from the Bank, indicating that it is ready to perform the payout and is waiting for your confirmation. Confirm (session/confirm) or cancel (session/cancel) the payout. To enable automatic confirmation, contact you manager at Bank 131. Wait for a payment_finished webhook with the payout results. If the status is succeeded, the payout was successful. Start the payout in one of the following ways: send a session/create request and then a session/start/payout request with the session identifier and payout details--the recommended option start a session and the payout simultaneously (session/init/payout) Wait for a ready_to_confirm webhook from the Bank, indicating that it is ready to perform the payout and is waiting for your confirmation. Confirm (session/confirm) or cancel (session/cancel) the payout. To enable automatic confirmation, contact you manager at Bank 131. Wait for a payment_finished webhook with the payout results. If the status is succeeded, the payout was successful. The steps depend on whether or not you use our widget. With our widget Without our widget Create a payment session with a session/create request. In the response you will get the session identifier. Send a token request to get a public token. The token is used to initialize the widget. Initialize the widget using the received token. Wait for a ready_to_confirm webhook from the Bank, indicating that it is ready to perform the payment and is waiting for your confirmation. Confirm (session/confirm) or cancel (session/cancel) the payment. To enable automatic confirmation, contact you manager at Bank 131. Wait for a 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), or cancel the payment (session/cancel). Skip this step if delayed capture payments are not enabled for you. In this case, the funds will be put on hold and captured automatically. Wait for a payment_finished webhook with the payment results. If the status is succeeded, the payment was successful. Start the payment in one of the following ways: send a session/create request and then a session/start/payment request with the session identifier and payment details--the recommended option start a session and the payment simultaneously (session/init/payment) Wait for a ready_to_confirm webhook from the Bank, indicating that it is ready to perform the payment and is waiting for your confirmation. Confirm (session/confirm) or cancel (session/cancel) the payment. To enable automatic confirmation, contact you manager at Bank 131. If you get an 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. Wait for a 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), or cancel the payment (session/cancel). Skip this step if delayed capture payments are not enabled for you. In this case, the funds will be put on hold and captured automatically. Wait for a payment_finished webhook with the payment results. If the status is succeeded, the payment was successful. Was this helpful? --- ## Payouts - [About Payouts](https://developer.131.ru/en/payouts/payouts-intro): Payout methods overview -- bank cards (Visa/MasterCard/Mir), bank accounts, YooMoney wallets, FPS by phone; settlement, escrow, and collateral account types You can securely and with ease execute payouts to individuals, legal entities, sole proprietors, and self-employed persons as well as pay VAT to the Federal Tax Service. You can make payouts in both Russian rubles and foreign currency. You can send money to: bank cards (Visa, MasterCard, and Mir) Russian bank accounts YooMoney wallets Also, you can send money by the recipient's phone number via the FPS. info Bank 131 provides a daily payout report and a monthly payout report. 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 > 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 > 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 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 > 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 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 > info A card identifier is not a replacement for a token and cannot be used to make payouts or to retrieve all cards linked to a recipient. To set up the identifier, contact your manager at Bank 131. Refunds Funds transfers to accounts in Russian banks may be declined. This can occur, for instance, if the account is blocked. In this case, the money is returned to the sender's account. The refund is carried out within 7 business days. Learn more about payout refunds > 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. Was this helpful? Bank accounts Processing, transferring, and storing card details Card identifier Refunds Tariffs and limits --- - [Payout to a Card (PCI DSS)](https://developer.131.ru/en/payouts/payout-pcidss): Send payouts directly to Russian bank cards with full PCI DSS compliance requirements 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 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 method to create a session and a payout at the same time. In this case, specify all the parameters for a payout right away and skip the next step. This option is not recommended. Creating a session cURL PHP 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" }' 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 method. Pass the session identifier along with all the parameters for a payout. Request example cURL PHP curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "2200********4940" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' 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 webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example 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 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) or cancel it (session/cancel). Confirming the session cURL PHP 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" }' use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); Canceling the session cURL PHP 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" }' 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 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 > View error codes > Handling the webhook using SDK use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem'), file_get_contents('/path/to/bank131/public_key.pem') ); $client = new Client($config); $hook = $client->handleWebHook('sign from headers', 'request body'); if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) { $session = $hook->getSession(); //do your logic here } Was this helpful? Step 1. Create a payment session Step 2. Start the payout Step 3. Wait for a webhook saying the payout is ready Step 4. Confirm or cancel the payout Step 5. Wait for a webhook with the payout results --- - [Payout to a Card via Widget](https://developer.131.ru/en/payouts/payout-tokenized-card): Send payouts using the tokenized card widget with reduced PCI DSS scope 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 token: using the tokenize/elements method token: by processing a recurring payment A token does not depend on the project (X-PARTNER-PROJECT) within which it was created. The scope of PCI DSS requirements that you must comply with depends on which option you choose. With our widget By token/hash Step 1. Get a public token The public token is needed to initialize the widget. Send a token request to create a token, specifying the tokenize_widget widget type. You will receive a public token in response. Request example cURL PHP curl -X POST \ http://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tokenize_widget": { "access": true } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setTokenizeWidget() ->build(); $response = $client->widget()->issuePublicToken($request); $publicToken = $response->getPublicToken(); Step 2. Initialize the widget Initialize the widget on your site 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 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 method to create a session and a payout at the same time. In this case, specify all the parameters for a payout right away and skip the next step. This option is not recommended. Creating a session cURL PHP 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" }' 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 method. Pass the session identifier along with all the parameters for a payout. info You can find information on the hash or card using the token/info method. For example, you can get the first 5 and last 4 digits of the account number to show the recipient which account the payout will be credited to. Request example cURL PHP curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\EncryptedCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $participant = new Participant(); $participant->setFullName('Ivanov Ivan Ivanovich'); $request = RequestBuilderFactory::create() ->startPayoutSession('session_id') ->setCard(new EncryptedCard('number_hash')) ->setRecipient($participant) ->setAmount(10000, 'rub') ->setMetadata('good') ->build(); $response = $client->session()->startPayout($request); Step 5. Wait for a webhook saying the payout is ready Bank 131 will send you a ready_to_confirm webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel). Webhook example 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 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) or cancel it (session/cancel). Confirming the session cURL PHP 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" }' use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); Canceling the session cURL PHP 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" }' 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 webhook. The result of the payout can be found in the status field of the payments/payout_list array. If the status is succeeded, then the payout was successful. If the status is failed, then an error occurred during the payout. In the request specify either token or hash depending on which one you use. Step 1. Create a payment session Create a session using the session/create 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 method to create a session and a payout at the same time. In this case, specify all the parameters for a payout right away and skip the next step. This option is not recommended. Creating a sessioncurl -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 method. Pass the session identifier along with all the parameters for a payout. info You can find information on the token, hash, or card through the 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 exampleWith a token received via the method With a hash from the widget With a token from recurring payments curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "tokenized_card", "tokenized_card": { "token": "759c9852dde2211d7531b3d905c1d513fbfb914bee87fb567d99c7b2f2c2ad44" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "metadata": "good" }' curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "card", "card": { "type": "encrypted_card", "encrypted_card": { "number_hash": "064e7045a239e2d5d0448c2f72be84beb8d6dc47020f5b1174bccb6f3b9b2f1b" } } }, "participant_details": { "recipient": { "full_name": "Ivanov Ivan Ivanovich" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_3230", "payment_method": { "type": "recurrent", "recurrent": { "token": "9a8a650c49de69eb98549027c5bc366f5bda51efe59bb8c0e02eb8a8a4e359da" } }, "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 webhook. This means that the payout can be performed and the Bank is waiting for you to confirm (or cancel) it. Webhook examplecURL PHP 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" }] } }' 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) or cancel it (session/cancel). Confirming the sessioncURL PHP 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" }' 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 sessioncURL PHP 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" }' 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 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 > View error codes > Example of how to handle a webhook using SDKuse 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 } Was this helpful? --- - [Payout to a Russian Bank Account](https://developer.131.ru/en/payouts/russian-account): Send payouts to Russian bank accounts via BESP or regular interbank transfer You can send money from your collateral account to bank accounts as follows: as a standard payout--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--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 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 method to create a session and a payout at the same time. In this case, specify all the payout parameters with open card data and skip the next step. This option is not recommended. Request examplecurl -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 request, specifying the session identifier alongside the payout parameters. Example of a payout by account numberFor residents For non-residents curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ "session_id": "ps_3230", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }' curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d'{ "session_id": "ps_3230", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "{VO99090} Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good", "participant_details": { "sender": { "full_name": "Vector LLC", "address_line": "123 Main Street", "country_iso3": "USA", "city": "New York" }, "recipient": { "full_name": "Ivanov Ivan Ivanovich" } } }' Step 3. Wait for a webhook showing that the Bank is ready to perform the payout Bank 131 will send you a ready_to_confirm webhook. This means that the payout can be performed and the Bank is waiting for you to confirm. Webhook example 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) or cancel (session/cancel) the payout. Confirming a payout cURL PHP 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" }' use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); Пример с отменой выплатыcURL PHP 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" }' 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 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 webhook. To do this, contact your account manager at Bank 131. Webhook delivery is not guaranteed by Bank 131, as it depends on the recipient bank. More about the payout statuses > View error codes > How to learn that a payout was returned > Was this helpful? Making a standard payout --- - [Payout via FPS by Phone](https://developer.131.ru/en/payouts/payout-fps-phone): Send payouts through the Faster Payment System using recipient phone number 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 method. Before making a payout using the new details, check whether the recipient is registered in FPS using the fps/customer_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 type | + | string | Value: bank_account bank_account | + | object | Bank account system_type | + | string | Bank transfer system. Always: faster_payment_system faster_payment_system | + | object | FPS data phone | + | string | Recipient's phone number bank_id | + | string | Identifier of the recipient's bank in FPS description | + | string | Payout purpose amount_details | + | object | Amount 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 sender | + | object | Sender details account | + | string | Escrow account number from which to make the payout recipient | + | object | Recipient details beneficiary_id | + | string | INN of the beneficiary How to specify the payout purpose In the description parameter, specify the following: the transaction type (e.g. service fee) the reason for the transaction (e.g. under Agreement No. 123) the name of the products and/or services provided whether or not VAT is applicable for non-residents of the Russian Federation: a currency transaction code agreed with Bank 131 Restrictions: disallowed characters: ?, ! maximum length:140 characters Payout purpose example For residents For non-residents 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 sending the parameters from the table above. Example of an FPS payout from the settlement account curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system", "faster_payment_system": { "phone": "79680000000", "bank_id": "100000000069", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "metadata": "good" }' How to perform a payout from the escrow account :::warning Important! Before making a payout, submit a list of beneficiaries to Bank 131 to identify them. ::: Use the payout scenario without our widget sending the parameters from the table above. Example of an FPS payout from the escrow accountcurl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "faster_payment_system", "faster_payment_system": { "phone": "79680000000", "bank_id": "100000000069", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } }, "metadata": "good" }' Was this helpful? Payout parameters How to specify the payout purpose How to perform a payout from the settlement accountHow to perform a payout from the escrow account --- - [Payouts to the Self-Employed](https://developer.131.ru/en/selfemployed/intro): Fiscalization flow for payouts to self-employed individuals with Federal Tax Service receipt generation 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. How to make a payout with fiscalization > 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 > Was this helpful? Notifications from the Federal Tax Service --- - [Speedy Payouts](https://developer.131.ru/en/payouts/payout-account-sistema-besp): Express payout processing through the Bank of Russia payment system (BESP) You can send money from your collateral, settlement, or escrow account to bank accounts as speedy payouts through the BESP system--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 accountsYou can only send payouts to the accounts that begin with these digits: 40817810 42301810 42302810 42303810 42304810 42305810 42306810 42307810 40802810 40701810 40502810 40702810 (for legal entities) Accounts allowed for payouts from collateral accountsYou can only send payouts to the accounts that begin with these digits: 40817810 42301810 42302810 42303810 42304810 42305810 42306810 42307810 40802810 40820810 40702810 (for legal entities) Making a speedy payout 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 specifying the parameters required for a payout from a collateral, settlement, or escrow account. Make sure you pass true in the is_fast parameter of the ru object, otherwise a standard payout will be made. Object example { "bank_account": { "system_type": "ru", "ru": { "bik": "044525971", "account": "40817810100000270411", "full_name": "Ivanov Ivan Ivanovich", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt", "is_fast": "true" } } } More about the payout statuses > View error codes > How to learn that a payout was returned > Was this helpful? Accounts for payouts Making a speedy payout --- - [Payout Refunds](https://developer.131.ru/en/payouts/payout-refunds): Handling payouts declined by the recipient bank and refund processing within 7 business days 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 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. In return you will get the payout details and, if the payout was returned, the refund details. Check the payout report. 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. Was this helpful? --- - [Settlement Account API](https://developer.131.ru/en/settlement-account/settlement-intro): Managing settlement accounts for direct payouts to counterparties, salaries, and taxes You can manage your settlement account with Bank 131 API. Features Payouts. To bank cards (by card number, with our widget or by token), to Russian bank accounts (by account number, with our widget or by token), and also by phone number via FPS. Balance info. Check your settlement account balance using the account_balance method. Account statements. Request a statement on all transactions for any particular day using the report/account_statement method. Accounts for payouts Accounts allowed for payouts from settlement accountsYou can only send payouts to the accounts that begin with these digits: 40817810 42301810 42302810 42303810 42304810 42305810 42306810 42307810 40802810 40701810 40502810 40702810 (for legal entities) Was this helpful? Features Accounts for payouts --- - [Escrow Account API](https://developer.131.ru/en/escrow-account/escrow-intro): Managing escrow accounts for intermediary payouts on behalf of beneficiaries with beneficiary list submission 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 before payouts. Payouts. To bank cards (by card number, with our widget or by token), to Russian bank accounts (by account number, with our widget or by token), and also by phone number via FPS. Balance info. Check your escrow account balance using the account_balance method. Account statements. Request a statement on all transactions for any particular day using the report/account_statement method. Top-up notifications. Enable the nominal_topup webhook to receive instant notifications on your escrow account top-ups. Accounts for payouts Accounts allowed for payouts from escrow accountsYou can only send payouts to the accounts that begin with these digits: 40817810 42301810 42302810 42303810 42304810 42305810 42306810 42307810 40802810 40701810 40502810 40702810 (for legal entities) General scenario on how to work with an escrow account Working with an escrow account via the API generally involves the following steps: Verify beneficiaries. Replenish your escrow account. Make a payout. Note that the scenario may vary in some steps depending on the escrow account agreement. Was this helpful? Features Accounts for payouts General scenario on how to work with an escrow account --- ## Payments - [About Payments](https://developer.131.ru/en/payments/payment-intro): Payment methods overview -- bank cards, SberPay, T-Pay, FPS QR, YooMoney, recurring payments, AFT, delayed capture, refunds 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, you cannot enable payments. API features With the Bank 131 API, you can: accept payments via bank cards (Visa, Mastercard, and Mir), via SberPay, T-Pay, and FPS accept payments from YooMoney wallets make recurring payments send AFT payments process two-stage payments--hold funds on a card for up to 5 days, then debit them fully or partially issue full or partial refunds Sending card data You can submit card data to Bank 131 either via the payment widget or directly. 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 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 > info A card identifier is not a replacement for a token and cannot be used to make payments or to retrieve all cards linked to a recipient. To set up the identifier, contact your manager at Bank 131. Tariffs and limits The tariffs are given in your agreement with the Bank. You can discuss them with your manager. Was this helpful? API features Sending card data Card identifier Tariffs and limits --- - [Payments by Bank Cards](https://developer.131.ru/en/payments/payment-pcidss): Direct card payment integration with 3DS authentication and full PCI DSS compliance This scenario describes how bank card payments are accepted and processed by services having the technical capacity to collect and store card details on their side. If you decide not to collect bank card details and not to store them on your side, accept payments using our payment form. This scenario does not include the payment capture step. How to make a delayed capture payment Create a payment session (session/create). You will receive a payment session identifier in response. Alternatively, you can use the session/init/payment method. In this case, specify all the payment parameters right away and skip the next step. Creating a session cURL PHP 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" }' 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); Send a session/start/payment request. In the session_id parameter, pass the identifier of the session created in Step 1. In the type field of the payment_details object, specify card. In the bank_card object, transmit user's bank card details. Starting a payment cURL PHP 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" } } }, "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "metadata": "good" }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->startPaymentSession('session_id') ->setCard( new BankCard( '4242424242424242', '02', '22', '123', 'cardholder name' ) ) ->setCustomer(new Customer('lucky')) ->setMetadata('good') ->build(); $response = $client->session()->startPayment($request); Wait for a 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 cURL PHP 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" }] } }' 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 } Confirm (session/confirm) or cancel (session/cancel) the payment. Confirming the session cURL PHP 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" }' use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); Canceling the session cURL PHP 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" }' 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'); If the user's card requires 3D Secure, Bank 131 will send you an action_required webhook with redirection details in the customer_interaction.redirect.url field. Redirect the user. Webhook example cURL curl -X POST \ https://partner.ru \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "customer_interaction": { "type": "redirect", "redirect": { "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 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 } Wait for a payment_finished webhook or request the payment status using the session/status method. The result of the payment can be found in the status field of the acquiring_payments/payment_list array. If the status is succeeded, then the payment has been successful. If the status is failed, then the payment has not been completed because of an error. More about the payment statuses Payment without a payment form Was this helpful? Payment without a payment form --- - [Single-Request Payments](https://developer.131.ru/en/payments/payment-pcidss-simple): Synchronous one-request payment flow using `session/init/payment/sync` 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 Here, a payment with immediate capture is described. More about delayed capture payments How to enable For such payments, there is a special method, session/init/payment/sync. 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 request. How to perform a payment Send a session/init/payment/sync request. Please be aware that we do not recommend implementing this method unless you have already used it before. In the type field of the payment_method/payout_details object, specify card. In the bank_card 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 pending - the user needs to go through 3D Secure verification More about the payment statuses Request example cURL 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" } }' 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 will be included in the response. To learn the final payment status, send a session/status request. 3D Secure card If a user card requires 3D Secure, redirection details will be returned in response to the request. Redirect the user to customer_interaction.redirect.url. After that, send a session/status request to learn the final payment status. Was this helpful? How to enable How to perform a payment If no result is returnedToo long payment 3D Secure card --- - [Payments via Payment Form](https://developer.131.ru/en/payments/payment-with-form): Hosted payment form widget for PCI DSS scope reduction 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 and then perform the payment securely. This scenario does not include the payment capture step. How to make a delayed capture payment Create a payment session (session/create). You will receive a payment session identifier in response. More about request format Creating a session cURL PHP 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" }' 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); Generate a public token to work with the widget. Send a 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. Request example cURL PHP curl -X POST \ http://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_123456" } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setAcquiringWidget( 'test_ps_id', 'http://success.url', 'http://failed.url', false ) ->build(); $publicTokenResponse = $client->widget()->issuePublicToken($request); $publicToken = $publicTokenResponse->getPublicToken(); 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 Wait for a 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 cURL 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 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 } Confirm (session/confirm) or cancel (session/cancel) 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 cURL PHP 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" }' use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $response = $client->session()->confirm('session_id'); Canceling the session cURL PHP 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" }' 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'); Wait for a 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. More about the payment statuses Diagram for payment via payment form Was this helpful? Diagram for payment via payment form --- - [Delayed Capture Payments](https://developer.131.ru/en/payments/payment-hold): Two-stage payments -- hold funds on card for up to 5 days, then capture fully or partially 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 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 You are passing card details with open parameters You are using our payment widget To create a delayed capture payment, complete the following steps: Create a payment session that is separate from the actual payment (session/create) or a single combined session (session/init/payment). If you have created the session separately from the start of the payment, send a session/start/payment request. Bank 131 will then send you a ready_to_confirm webhook, which means that the Bank is ready to perform the payout and is waiting for your confirmation. Confirm (session/confirm) or cancel (session/cancel). If you get an 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. Wait for a 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. Webhook example cURL PHP 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" }] } }' 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 } Capture the full amount that is on hold, a portion of the amount (session/capture), or decline the payment (session/cancel). Wait for a payment_finished webhook containing the result of the payment. If the status is succeeded, this tells you that the payment was successful. Payment diagram with holding Complete Steps 1-5. 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. Wait for a 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. Webhook example cURL PHP 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" }] } }' 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 } Capture the full amount that is on hold, a portion of the amount (session/capture), or decline the payment (session/cancel). Wait for a payment_finished webhook containing the result of the payment. If the status is succeeded, this tells you that the payment was successful. Diagram of a delayed capture payments Was this helpful? How it works How to enable delayed capture Hold period Later capture payment scenario Payment diagram with holding --- - [Recurring Payments](https://developer.131.ru/en/payments/payment-recurring): MIT/CIT recurring payment flows with token lifecycle management and disabling 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 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 How to make recurring payments via SberPay How to make recurring payments via T-Pay How to make recurring payments via YooMoney 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. How to create a recurring payment Obtain the user's consent to recurring payments. Perform a successful payment that will recur, and get a token. Perform payments using this token. 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: Describe the payment terms to make sure the user will read them. 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. 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. 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). You can do this when creating a payment session or in any payment request. If such a payment is successfully performed, you will receive a token for recurring payments with which you will be able to repeat the payment. In this case, you need to get the user's consent on your side beforehand. In our payment widget If you perform a payment with the widget, you can show the I agree to recurring payments checkbox to the user. If the user ticks this checkbox and the payment is performed successfully, you will receive a token for recurring payments. Token statuses When you create a token, it becomes active (is_active: true) and you can perform payments with the token. If a token is inactive (is_active: false) or expired, the payment will not be processed and you will see an error. How to learn the token status Send a token/info request. In the type parameter, pass recurrent_token, in the recurrent_token.token parameter, pass the token. In return, you will get info 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 request. In response, you will receive recurrent. 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 Without our widget With our widget How to make a payment without our widget When creating a payment session or sending a payment request, pass true in the recurrent parameter of the payment_options object. Example of a payment request with an instruction to create a token cURL PHP curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "card", "card": { "type": "bank_card", "bank_card": { "number": "4242424242424242", "expiration_month": "01", "expiration_year": "22", "security_code": "087" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" }, "payment_options": { "recurrent": true } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; use Bank131\SDK\DTO\Customer; use Bank131\SDK\DTO\PaymentOptions; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setRecurrent(true); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '01', '22', '087')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayment($request); How to make a payment with our widget 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, 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 curl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_34851", "show_recurrent_checkbox": true } }' Then, create a payment form 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 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 webhook. Webhook example 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 cURL PHP 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": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "customer": { "reference": "lucky" } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Customer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39') ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->build(); $response = $client->session()->initPayment($request); Was this helpful? User consentWhy you need it How to obtain user's consent Token for recurring paymentsHow to get a token Token statuses How to learn the token status How to disable a token How to accept recurring paymentsStep 1. Successfully perform a payment with an instruction to create a token Step 2. Save the token Step 3. Accept payments using the token --- - [Payments via SberPay](https://developer.131.ru/en/payments/payment-sber-pay): SberPay payments via phone number lookup or dynamic QR code This scenario describes how to receive payments via SberPay. These payments, one-time and recurring, do not require card details from customers. To select a recurring payment method, inform your manager in Bank 131 upon boarding. You should confirm a payment within 20 minutes by sending session/confirm. 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). Mobile application (app) Mobile browser (mobile_web) Desktop browser (web) Create a separate session using the session/create method, or create a session with the payment using the session/init/payment 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 method is required to be sent after you created a separate session. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request. You can also use the sberpay/push 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. Bank 131 will send you an 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: Open the onlineios-app://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the startonline://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the onlineappmobile://sbolpay.... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the budgetonline-ios://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the btripsexpenses://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the ios-app-smartonline://sbolpay/... deeplink. Wait 50ms. Reload the page. Follow the deeplink to the Sber landing page. 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. Wait for a 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. Pass the transaction status to the customer. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "return_url": "https://t.me/bank131" } }' Response example { "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 } }] } } Create a separate session using the session/create method, or create a session with the payment using the session/init/payment 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 method is required to be sent after you created a separate session. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request. _You can also use the sberpay/push method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber). Bank 131 will send you an 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: Open the onlineios-app://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the startonline://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the onlineappmobile://sbolpay.... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the budgetonline-ios://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the btripsexpenses://sbolpay/... deeplink. Wait 50ms. Reload the page to hide a possible alert if the deeplink could not open properly. Redirect back to your page with the new request settings. Open the ios-app-smartonline://sbolpay/... deeplink. Wait 50ms. Reload the page. Follow the deeplink to the Sber landing page. 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. Wait for a 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. Pass the transaction status to the customer. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "mobile_web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "mobile_web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "return_url": "https://t.me/bank131" } }' Response example { "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 } }] } } Create a separate session using the session/create method, or create a session with the payment using the session/init/payment and pass all the required parameters, including the following ones: sber_pay in the type parameter web in the channel parameter the URL to forward the customer to in the return_url parameter. The session/start/payment method is required to be sent after you created a separate session. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request. You can also use the sberpay/push method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber). 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. Wait for a 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. Pass the transaction status to the customer. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "web" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "web", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "return_url": "https://131.ru" } }' Response example { "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 } }] } } Selecting a proper deeplink for Sber iOS mobile applications Code example Code example for selection logic implementationconst 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 via SberPay: Get a token by sending recurrent=true (in the payment_options object) in the request. If the payment is successful, you will get the token in the payment_finished webhook in the recurrent.token parameter. Example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "sber_pay", "sber_pay": { "phone": "71234567890", "channel": "app" } } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" }, "payment_options": { "return_url": "https://t.me/bank131", "recurrent": "true" } }' Use the token to make recurring payments. Example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": "app", "customer": { "reference": "user-ebf7-4815-af0a-b1f77e6de7e7" } }' Was this helpful? Payment scenario Selecting a proper deeplink for Sber iOS mobile applications Recurring payments --- - [Payments via T-Pay](https://developer.131.ru/en/payments/payment-tpay): T-Pay payments via deeplink or QR code from T-Bank During payments via T-Pay the payer authentication is performed through logging into the T-Bank app. Customers do not have to enter card details to make payments. You can accept T-Pay payments in two ways: with a QR code, which works for payments made from a desktop browser (generate and display the QR code on your own) with a URL to the T-Bank application, which works for payments made from a mobile device After being redirected by the URL, the payer will have 20 minutes to complete the payment. Otherwise, the session terminates within 20 minutes with the canceled status. You can make payments with automatic payment session confirmation. Payment scenario The payment scenario depends on the customer's payment channel: mobile device (mobile) or desktop browser (desktop). The client device properties in the request define the format of the payment link in the action_required webhook. Mobile device (mobile) Desktop browser (desktop) Create a session separately using the session/create method and then start the payment (session/start/payment), or create a session along with the payment using the session/init/payment method. Pass all the required parameters: Pass the tpay value in the type parameter of the internet_banking object. Pass the mobile value in the type parameter of the platform_details object. Specify one of the acceptable values in the os and browser parameters. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } } }' Response example { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:14:28.236854Z", "updated_at": "2025-09-05T07:14:28.298522Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-05T07:14:28.310910Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request. Bank 131 will send you an action_required webhook containing a URL within redirect.url to forward the customer to the T-Bank mobile application. Webhook examplecurl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:49:12.513214Z", "updated_at": "2025-09-05T07:49:24.628403Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "pending", "created_at": "2025-09-05T07:49:12.605322Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { "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" } } }' Forward the customer by the link passed within the redirect.url parameter to the T-Bank mobile application. Wait until the customer approves or cancels the payment. Wait for a ready_to_capture webhook and capture the amount that is on hold in full or partially (session/capture), or decline the payment (session/cancel). Skip this step if you do not have delayed capture payments enabled. In this case, the hold and capture will be made automatically. Wait for a payment_finished webhook containing the payment result from Bank 131. The succeeded status indicates a successful payment. Create a separate session using the session/create method and then start the payment (session/start/payment), or create a session along with the payment using the session/init/payment method. Pass all the required parameters: Pass the tpay value in the type parameter of the internet_banking object. Pass the desktop value in the type parameter of the platform_details object. Specify one of the acceptable values in the os and browser parameters. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 67000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "desktop", "os": "windows", "browser": "chrome" } } }' Response example { "status": "ok", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:14:28.236854Z", "updated_at": "2025-09-05T07:14:28.298522Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "in_progress", "created_at": "2025-09-05T07:14:28.310910Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {} }] } } Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request. Bank 131 will send you an action_required webhook containing a URL for QR code within redirect.url. Generate and display the QR code to the payer on your own. Webhook examplecurl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3813062", "status": "in_progress", "created_at": "2025-09-05T07:49:12.513214Z", "updated_at": "2025-09-05T07:49:24.628403Z", "acquiring_payments": [{ "id": "pm_2769418", "status": "pending", "created_at": "2025-09-05T07:49:12.605322Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { "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" } } }' Display the link passed within the redirect.url parameter as a QR code. Wait until the customer approves or cancels the payment. Wait for a ready_to_capture webhook and capture the amount that is on hold in full or partially (session/capture), or decline the payment (session/cancel). Skip this step if you do not have delayed capture payments enabled. In this case, the hold and capture will be made automatically. Wait for a payment_finished webhook containing the payment result from Bank 131. The succeeded status indicates a successful payment. Recurring payments To perform MIT recurring payments or CIT recurring payments via T-Pay: Get a token by sending recurrent=true (in the payment_options object) in the request. If the payment is successful, you will get the token in the payment_finished webhook in the recurrent.token parameter. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "internet_banking", "internet_banking": { "type": "tpay" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "recurrent": true, "type": "mobile", "os": "ios", "browser": "chrome" } } }' Response example { "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 } }] } } Use the token to make recurring payments. ExamplesMIT recurring payment CIT recurring payment Request example Response example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", "initiator":"merchant" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "android", "browser": "chrome" } } }' { "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": {} }] } } Request example Response example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39", "initiator":"client" } }, "amount_details": { "amount": 670000, "currency": "RUB" }, "customer": { "reference": "lucky" }, "payment_options": { "platform_details": { "type": "mobile", "os": "ios", "browser": "chrome" } } }' { "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. Was this helpful? Payment scenario Recurring payments How to make a refund --- - [Payments via FPS QR](https://developer.131.ru/en/payments/payment-fps-qr): SBP QR code payments through the Faster Payment System with dynamic or static QR You can receive payments using the Faster Payment System (FPS). To do this: Open an account in Bank 131. Register your legal entity account with the FPS. Add an FPS payment link onto your payment webpage. You can accept FPS payments in two ways: With a QR code, which works for payments made from a desktop browser (customer_interaction.type.inform.qr.img from the action_required webhook). With a deeplink, which works for payments made from a mobile device (customer_interaction.type.inform.qr.content from the action_required webhook). To accept the FPS payments with a QR code, you should create QR code in accordance with the NSPK guidelines. After an FPS payment is complete, you will receive the customer's masked phone number in the phone parameter of the contacts array. Should you require the customer's full phone number, apply to your manager in Bank 131. You can make payments with automatic payment session confirmation. How to make recurring payments via FPS How to get a token for recurring payments via FPS without charging How to receive a payment via FPS Create a payment session session/create 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 object. Request examplecurl -X POST \ https://demo.bank131.ru/api/v1/session/create \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 5000, "currency": "rub" }, "customer": { "reference": "lucky" } }' Response example{ "status": "ok", "session": { "id": "ps_123456789", "status": "created", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z" } } Send a payment request using the session/start/payment method. The payment_options.return_url parameter contains an URL to take customer back from the issuer's mobile application. Request examplecurl -X POST \ https://demo.bank131.ru/api/v1/session/start/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_123456789", "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "payment_options": { "return_url": "https://131.ru" }, "customer": { "reference": "lucky" } }' Response example{ "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 } }] } } Wait for a ready_to_confirm webhook to confirm the payment with session/confirm or cancel the payment with session/cancel. Wait for an 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. Examplecurl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_120285623", "status": "in_progress", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_94939668", "status": "pending", "created_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "95.24.204.116" }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "customer_interaction": { "type": "inform", "inform": { "qr": { "content": "https://qr.nspk.ru/AD1000269CKIK8M09C1RB40LB7QAM8IH?type=02&bank=100000000143&sum=1000&cur=RUB&crc=C900", "img": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAATw0lEQVR42u3deXBURR7Acba2at3aqt2tPRRh5dBFWBQUWFYBCVqIS4mCuF5EQiGHohwCyuGFHCpGRUAsISACGw5RWK6AAV3FFbkhCgQLiCEc4QhHCCEkmVy/zYxmYEIyCWHy+tdvvr+q/gOmJzPzXvfnHb/X3TWEIAjCkqjBJiAIArAIgiAAiyAIwCIIggAsgiAIwCIIArAuerFGDTWlst+v0j/8Cj7X2M4ytK2u5PuFup4T7cqJtmaqHdjYzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlqmOqakRaYdXExKmOo1bDgza+4ITvw2wAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACvswDLVgW38ftqLEx3JVDtwc7ZT076szv0GWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWEqzZpoygqb+nqbspKlsopsPjoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWOqyPpqGLWhvlJqG0tjYqbXP1wVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYzIdlFCInsn+aMqDat4upbKJbwDfVzwELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlo0rP1OPetSzY942wKIe9agHWIBFPeoBFmABFvWoB1iART3qUc/VYGkPTcMgtM+HpSmLZOO8aNrbn6bsX7X2ecACLMACLMACLMACLMACLMACLMACLMACLMACrHAAS/uE/6Y6g5vnBHPLfFja8dS+CIrTnwFYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgAVYgGU1WG4eXqM9q2LjECgbs8qa9pum7KRWFAELsAALsAALsAALsAALsAALsAALsAALsAALsABLQZZQO6jaF1YIdYPWnsXUhKL29uf4QQewAAuwAAuwAAuwAAuwAAuwAAuwAAuwAAuwACscwLIxI2PjAhvhMvyiukBwy8FME3ZOZ/QBC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7BcB5aphqWpQZv6ztqHc2iCSDsc2hdB0RqABViABViABViABViABViABViABViABViABVhhC5amDa19OIxbMLERVLcsWuKWkwbAAizAAizAAizAAizAAizAAizAAizAAizAAixXg+VE5zcFpanGa6qzakJHUyZNe9u1MUtYnZ8BWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIDlOrA0IWHjnFumtrOmrFS4rRSuvQ1p6jOABViABViABViABViABViABViABViABViABViuBsstQ1pM7STtnZoMlJ3bwNTvCHVbC3mWELAAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AASztYNnYkTSsSu2UeJDevthxukGvfLoAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWGEHlo2Nw1RH15RN1D7nlo0LgJjab9rbs/r5sAALsAALsAALsAALsAALsAALsAALsAALsAALsJjTXVe2RNNnaMrWhdvqzcyH5fxQJMACLMACLMACLMACLMACLMACLMACLMACLMACLKvBcstKyDZ2JO3zZmnKIGvvwJoO/LbvD8ACLMACLMACLMACLMACLMACLMACLMACLMACLKvBMpW90p7lqs5GTugMtwwX03SQUj+BH2ABFmABFmABFgFYgAVYgEUAFmABFmABFmCFGiwbV/I1NeeRG4ddEPaAoH0OL0fmwwIswCIAC7AAC7AAC7AAC7AIwAIswAIsArBsBMvNG9VUIwIsO1HS1Pltz/4BFmARgAVYgAVYgAVYgAVYgAVYgAVYgEUAVtiC5ZZVnp0AuirvdS6K0MihDux0p64uFE0ZAViAJYWntkr2irFSlHUGeQALsABLN1hFp9fL+TmNJf2l2yV346Li/+CMC7AAC7AUg5UXX1syxjSV04MbytnJj0nBkT0oBFiABVhawbpWchY29IHlK0Mby/kl46Uo5xwaAZZ9YJnaCE58rimMtYHlLWffanoBreJy5tUI8SSsQqQQtT8nOrqNC6gAFmBVCazcJTf4zq4uRstbMqf1loLjyWgFWIAFWHrA8pZzU5pcApa3pD/fRLI/myxFebmABViABVg6wPLE1ZX04TeViZbvMnFse8nb/TVgARZgAZZ5sLwla0bjcsEqKec+GiCF6UcBC7D0gRVuwGho5Jcbc789JFmegpCAlfffppK9arLvMjAYWukjmknOFzEiBXlhA5UTnVrrHG2agAYsy8HqM/IzaTH1e4nfl37FYOV/dYvvtcITByRzaq8Kz7Yy3uwk+UmbAQuwAAuwKhcD+i2S20etlT+/uVkeX7RXDmXkXjFYJeH5Ll7OjG4XHK4hjSRrwQtSdO60Y9s1Py9fzp/PBizAAiwbwerW6xOp/dZmH1p1JmyVyRuOiKegqAqXhI0DYUg9JUe7jZf9DR4LWlI7DRVPYmifkt+1c488N/g1afX3rnJjvTvlr3UipE7NVnLdNbf7yrP9RwMWYAGWjWB1fyxW2o383AdWSbnjw52y4VDmZYLV6KfXPPmSPmmZJP0pUvZe9WC5JekP3eR09CIpyg3tvax3354hda9t7cepdPHilXr4GGABlvNgOZ2F0zhHUSjA6t5jgdR7c1MAWldHb5YBcclyIiuv0mBlf5MoKc2eDQqVt6R2eU3yUo6HHIgpk2aXC1VJeW3MFLUHJE0ZRk1zvoXKF8ByC1jFpePznwWAVVJumLhNPtqeJoVFFYC1uoHs/fW/gkKV3OBJObd0Y5X21949+2X+3GUyacJMeX/yHPlizTrxeC5gmrQvRerXvsMP023Nu8jKFV/K2YxMyc31+EthYaH/PVlZ2bJh/fZKlW1bdgIWYAGWFrCiIudKo/EbykTLWzrMSZSEo1nBwSoHqn2/fUROvhwrhedyLvs7JmxPlAc69S3zbKl5k06++1XeGP7ceP//33RjBzmSelwyirHaunmHbN2yQ06dvDQTunvXvgrPyC7+LMACLMBSApa3PDBweblgeUvN6C0ycs0BST/yTaXBOtThZfH8cKhK+yh+1Vq5/i9ty0Wk5a2dfRm/oqIiueVvHf3/P6DfKHm670tSr1Yb//9572tFPjJIkn88CFiABVhuAMtbes3ZIdcUwxQMrsYT/yfzF/YVT3ytcsFKrttLzs7/usqzKR89kiYNr7/LD4YXn75PjJDXx74vfXqO8N08/8+ieF/dQwePBOBycUawdLm1cUdJTT1eJlg3XBfhOzsrKfVqtQYswLKrXqhB1ZTZLAusH3Yf9136tZ+dGBQtb+n8wQJJXB4RCNZvHpK0QdOlIP3K5sV6J3p6AFbrv90W8Prp0xlS+PONte8Tdl96RnTzvT7c3nx9qrRoel/Aa889O65MsEa/MingMzq27xESsLQOVamu9qz1BAawXAqWNwqKL7NmbDvuu+keDK1ab22SMXNelYz4W+Rg2xGSsy0pJJ0o8uGBfix6dBsStO6unXsD4Klfu40cSDnsf/3ggdTiS8sLN+SbNvonYAEWYLkJLG/k5+TLyqnr5IERa+TqCs62mk/+UuL3hO6J9Ye69PNj8cyTLwete/JkegA87SMiL6lzd7vIgDreDCNgARZguQSslI37ZV7PWIm59wNfGRM1V5qPXVfhZWLU4n1y+KznijvRiIuyfk0a3lN8CRh8hZ42LR/017/5xg6Sl3fhkQfvcJybi/9GyesN69/JGRZgAZYbwNqyNklWj13lhyqgdI6R3gOXS51SD5mWLnUnbJUpG49KXkHVV9PZtCEhAJN2rR+RTz6Oky2bd/hutvd/6pUAxN6JjgmoP3jgWDl27ITv7GvYkNcDXuvVYxhgAVb1bnxNi0aY2nGhjtJg9Xl8rkzrElM2Vj+XmV2ny8J5cdIyZmGFZ1veIT7fHsys8vcbPnR80EcNRr30rr+u95mr25p1rvDxhAZ12xWfRSY5CpaprLImKAELsEIO1huRc4JiFT9mlWQez5Q9p7ZKnxW3StePB0n9iV8FRct776t/XLKkZV3+mMH8/AJ5Y9z7ATfMS+Nz8VnWvr0pEtHq4XKxatG0k6xfdyHbCFiABViWgtU/ap5Mv39amVDN7xnru6dVEiVgeUuv5W0k4qMJUjM6+NmWN9s4KyHNl3283PA+tR7zwTzfA6FR3QbLgKdHybTif3ufvyodnlyPfLIgzvfg6H3/fEI63fOE9Ov9osyPXSpZWecD6p45c1Y+XbjSX75L2B3w+uerv/G/tmLZF4AFWIClBawJj866BKoPiy8PN83aKPm5+QHvuxisktJzaaTcN/eHCi8T756dKN8fy5JwD8ACLMCqIlhDi8+uSmO1YuQyST9Y9mMKZYE1KL6tb8X6+TtOSKP3tgdFy/sk/bDVKZKRUwBYgGUXWG6Zi0dDNqcqYEV1i5UpD830QxXbfbYkrd0XdEhNeWCVRHp2vgyN318MU/CzrcZTEmRR4qmwRMnUwcwtfbBKvx2w7Afrxcd/etZq+v1TZX3MOvFkVfwMVUVgeaOgsECejpsjNd8eGrTUn/iCfJ3yI2ABFmABVvAY0n+xTO06QxYP/FTS9qZV+n0VgbXh0E5pNq27/GL0bUHLvXMHS9Lpw5xhARZgAVbFMXX4Mtm1fIcUFV5e5q48sE6cPyO9lo6TX45pFRSquhM7y+LdX4b1fSrAAizAuszIyaraEJqywIpaEiF/jL47KFS/GttGhq15T855siUcArAsB8tUxs3UBnR6IQ6noiywGrwXERSrdrOeksS0ZCHMtl1TfdUJUAELsCoFVteFd5QL1TVvd5R/f7dSiqQIpQALsADLLFh941pI7QntLoHKex/rmZXRkp6diU6ABViApQOse2LbXoJVi5gesjl1NyoBFmABlh6wei9vKb8ff+Fy8Hfj75JJGxdIfmEBIgGWO8EytfGd+H5Ow+Y0WK1mXji7evTTFyX1bBoSVbLtmALBFGIahqQBVhiDFbXkH3LVuNbScMrDsubHjegEWIAFWHrBajm9g4xZ+6Hk5HuQCbAAC7D0gnXifJokp6ciEmABFmDpB4sArLAFy4mdpAmd6mwIhD1wae/8Ng4nAizAIgALsAALsAALsAALsAjAAizAAiwCsABLGQimGq+mObcIZ/a19gN1qPughvYMWIBFABZgARZgARZgARZgEYAFWIAFWARghQVYTvxgTfNXVefnEnZjpulAbaq/VSdigAVYBGABFmABFmABFmABFgFYgAVYgEUAltVgacLJ1Iq1mhqgE43SiU7jxD534mBmCkVNJxJObyvAAizAAizAAizAAizAAizAAizAAizAAizAAizXgaUpC6dpjiJTHc7GzJJ2PLXDq+nA6vTvBSzAAizAAizAAizAAizAAizAAizAAizAAizAshosTUMKtGdaNHUQUx3Oxm1vKmum6QBnU/YUsAALsAALsAALsAALsAALsAALsAALsAALsADLarBMNWjtGUZTmRu3DHMx1da0Z/U0gOBkOwUswAIswAIswAIswAIswAIswAIswAIswAIswAIsF3UGJ7J62ocxadqX2r9LuAEIWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWNUAllsam/ahEZo6jakskpuzpzZms00dqAELsAALsAALsAALsAALsAALsAALsAALsAALsFwNlhMZPO2LD5iCSHvmVRN22r+zJpxszMADFmABFmABFmABFmABFmABFmABFmABFmABFmC5BixT2TVT2GnPfGlfpCDc5q9yc+Za6xAjwAIswAIswAIswAIswAIswAIswAIswAIswAIsq8FyItOifSVaG4dp2FhPe9vQPreZjVnWqvw9wAIswAIswAIswAIswAIswAIswAIswAIswAIs14GlKYOnfaiFqU5jY4ZMawdxEg7tC2yYOmkALMACLMACLMACLMACLMACLMACLMACLMACLMByDVjaG5abV5d28+INNs4FpWneMRtXsDY2HxZgARZgARZgARZgARZgARZgARZgARZgARZgAZZ2sLQ3Sicah1t+r6kO55bQPk+Ypow5YAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYLmoITjxXk1waJ+/StOq1po+w4n3ajooq5oPC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAC7AAy81gaYdNU8My9fdCvd9YhEIXlFqzooAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWIAFWFaDpT07pH0nac8waloIwdSiEdpXv7bxt1VnuwcswAIswAIswAIswAIswAIswAIswAIswAIswHIdWJqyf6FuCNqzk6bm4bJx+7k5k6u9HajKEgIWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYNkIlo0ZmVDvOFPzPtk4p5WNbUPDAgxuy+gbyxICFmABFmABFmABFmABFmABFmABFmABFmABFmABlq5GZOPQIaezOaaznW4BWlObBCzAAizAAizAAizAAizAAizAAizAAizAAizAAqwwBEvThP9uWViBYSnuWfnZ9gAswAIswAIswAIswAIswAIswAIswAIswAIswAoLsEL+pSycD8vUkBsntoumoUM2dkyGQAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAEWYAGWug1tKvPlBDDaF6vQhI5b5h1zoj1rOsAZW/kZsAALsAALsAALsAALsAALsAALsAALsAALsABLE1gEQRCqMq5sAoIgAIsgCAKwCIIALIIgCMAiCIIALIIgAIsgCEJn/B/u92LX9SrJTQAAAABJRU5ErkJggg==" } } }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "actions": { "confirm": "2024-02-07T23:59:53.310721Z" } } }' Wait for a 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. Examplecurl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_123456789", "status": "accepted", "created_at": "2024-02-07T23:59:52.977041Z", "updated_at": "2024-02-07T23:59:52.977041Z", "acquiring_payments": [{ "id": "pm_12345678", "status": "succeeded", "created_at": "2024-02-07T23:59:52.977041Z", "finished_at": "2024-02-07T23:59:52.977041Z", "customer": { "reference": "lucky", "contacts": [{ "phone": "7965*****85" }] }, "payment_details": { "type": "faster_payment_system", "faster_payment_system": { "description": "Payment of services" } }, "amount_details": { "amount": 10000, "currency": "RUB" }, "payment_options": { "return_url": "https://131.ru", "recurrent": false } }], "actions": { "confirm": "2024-02-07T23:59:52.977041Z", "capture": "2024-02-07T23:59:52.977041Z" }, "transaction_info": { "fp_message_id": "A50581324524670W0000040011450701" } } }' How to make a refund via FPS To make refunds using the FPS, follow the standard procedure. Payment diagram Was this helpful? How to receive a payment via FPS How to make a refund via FPS Payment diagram --- - [Payments with YooMoney](https://developer.131.ru/en/payments/p-yoomoney): Accept payments from YooMoney e-wallets You can accept payments with YooMoney wallets, including: one-time payments recurring payments delayed capture payments Payments made with YooMoney wallets are refunded in a standard way. How to make a payment All parameters are passed in plain text. Do not use our widgets. Send a /session/init/payment 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. Request example curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "rub" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_options": { "return_url": "https://www.131.ru", "description": "description" } }' Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation. Webhook example 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" } }' Confirm (session/confirm) or cancel (session/cancel) the payment. Wait for an 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 curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3821809", "status": "in_progress", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:34:31.887997Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "pending", "created_at": "2025-11-05T08:33:46.190121Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "RUB" }, "amounts": {}, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=309d1fd7-000f-5001-8000-1e9f64506f41", "base_url": "https://yoomoney.ru/checkout/payments/v2/contract", "method": "GET", "qs": { "orderId": "309d1fd7-000f-5001-8000-1e9f64506f41" }, "params": {} } }, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z" } } }' If you make delayed capture payments, wait for a ready_to_capture webhook and then either confirm (session/capture) or cancel (session/cancel) the capture. Webhook example 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" } } }' Wait for a 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 occurred during the payment. Webhook example curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3821809", "status": "accepted", "created_at": "2025-11-05T08:33:46.121130Z", "updated_at": "2025-11-05T08:45:19.857746Z", "acquiring_payments": [{ "id": "pm_2775568", "status": "succeeded", "created_at": "2025-11-05T08:33:46.190121Z", "finished_at": "2025-11-05T08:45:19.781451Z", "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 5000, "currency": "RUB" }, "amounts": {}, "metadata": { "key": "value" }, "payment_options": { "recurrent": false, "description": "description" } }], "actions": { "confirm": "2025-11-05T08:34:31.626530Z", "capture": "2025-11-05T08:45:18.934056Z" } } }' Recurring payments CIT recurring payments with YooMoney wallets are not supported. To make MIT recurring payments with YooMoney wallets: Get a token by sending recurrent=true in the payment_options object. If the payment is successful, you will get the token in the payment_finished webhook in the recurrent.token parameter. Request example curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "wallet", "wallet": { "type": "yoomoney", "yoomoney": {} } }, "amount_details": { "amount": 25420, "currency": "rub" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] }, "payment_options": { "return_url": "https://www.131.ru", "description": "description", "recurrent": "true" } }' Use the token to make recurring payments. Request example curl -X POST \ https://proxy.bank131.ru/api/v1/session/init/payment \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_details": { "type": "recurrent", "recurrent": { "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39" } }, "amount_details": { "amount": 1000, "currency": "RUB" }, "metadata": { "key": "value" }, "customer": { "reference": "lucky", "contacts": [{ "email": "test@mail.net" }] } }' Payment diagram Was this helpful? How to make a payment Recurring paymentsPayment diagram --- - [Refunds](https://developer.131.ru/en/payments/payment-refund): Full and partial refund flows, chargeback handling via `session/refund` 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. 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 request. In the session_id field, pass the identifier of the 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 cURL PHP 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" }' 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 webhook with the results. Webhook example 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 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 } Was this helpful? How to perform a refundStep 1. Send a refund request Step 2. Wait to be notified of the results of the refund --- - [AFT Payments](https://developer.131.ru/en/payments/payment-aft): Account Funding Transactions -- topping up e-wallets or accounts via 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. Was this helpful? --- - [Payment Form Widget](https://developer.131.ru/en/payments/payment-widget): Payment widget technical integration guide with customization options 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 What the widget looks like Regular widget With a checkbox for enabling recurring payments With no Cardholder field Code example: a page with a widget Payment form widget
How to add a widget to a page 1. Link the scripts and styles 2. Add a container with the widget
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 method). const paymentForm = new Bank131PaymentForm('public token'); To display the payment form, call the render() method: paymentForm.render(); Widget API Bank131PaymentForm Payment form class constructor. 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. 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. paymentForm.onReady = function () { /* handler */ } Event handler: paymentForm.onPaymentStart Handles the event occurring at the start of the payment process. paymentForm.onPaymentStart = function () { /* handler */ } Event handler: paymentForm.onPaymentSuccess Handles the event occurring when the payment process finishes successfully. paymentForm.onPaymentSuccess = function () { /* handler */ }; Event handler: paymentForm.onPaymentFail Handles the event occurring when the payment process finishes unsuccessfully. paymentForm.onPaymentFail = function (error) { /* handler */ } Event handler: paymentForm.onDestroy Handles the event of the widget getting closed. 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: const paymentForm = new Bank131PaymentForm('publicToken', { isCvcMasked: true, }); Open the 3D Secure window as required You can choose how to open the 3D Secure window for the user. Use the target parameter of the customerInteractionRedirect object with the following options: _blank -- in a new tab _self -- in the same frame _parent -- in the next-level frame if the frames are nested in one another _top -- outside of all the frames as the top window Default: _top. Note that: We do not recommend using the _self option for security reasons. If you use the _blank option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget. Hide the cardholder name To hide the Cardholder filed, pass hideCardHolderField: true. By default, the field is shown. Appearance You can link your own styles after the library ones and override them, like this: Or this: /* 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 widget constructor. Widget UI element | Parameter name | Type | Default value --- | --- | --- | --- Widget text settings | texts | object | Failed payment message | failedPaymentScreen | string | Ошибка Payment form | paymentForm | object | Payment button name | buttonPayLabel | string | Оплатить Cardholder name text | cardholderLabel | string | Владелец карты Cardholder name prompt text | cardholderNote | string | None Cardholder name placeholder | cardholderPlaceholder | string | ИМЯ ФАМИЛИЯ Card number | cardNumberLabel | string | Номер карты Card number prompt text | cardNumberNote | string | None Card number placeholder | cardNumberPlaceholder | string | 0000 0000 0000 0000 CVV/CVC number | cvvLabel | string | CVC CVV/CVC number prompt text | cvvNote | string | None CVV/CVC number placeholder | cvvPlaceholder | string | CVC Card expiration date | expireDateLabel | string | Срок действия Card expiration date prompt text | expireDateNote | string | Как на карте Card expiration date placeholder | expireDatePlaceholder | string | ММ/ГГ Recurring payment checkbox | recurrentLabel | string | Соглашаюсь на автоплатежи Terms of agreement | | | Terms of agreement. The text within the mandatory {{#link}}{{/link}} tags is used as a link to the terms of agreement source. | termsAgreement | string | Нажимая кнопку «Оплатить» вы соглашаетесь с условиями {{#link}}пользовательского соглашения{{/link}} Field validation error messages | validationErrors | object | Invalid card number | INVALID_CARD_NUMBER | string | Неверный номер карты Invalid CVV/CVC | INVALID_CVV | string | Код должен содержать 3 цифры Invalid card expiration date | INVALID_EXPIRY_DATE | string | Неверная дата Required field value is missing | IS_REQUIRED | string | Обязательное поле Payment process page | paymentProcessScreen | object | Payment processing page text | description | string | Это займет совсем немного времени Payment process screen heading | title | string | Происходит оплата... Redirecting page (3D Secure) | redirectionScreen | object | Invitation message to proceed with redirection in case of automatic redirection failure. The text within the mandatory {{#link}}{{/link}} tags is used as a link. | followTheLink | string | Если этого не произошло, перейдите {{#link}}по ссылке{{/link}}. Payment processing page header | title | string | Происходит оплата... Automatic redirection warning, includes 3 seconds countdown timer. The {{countdown}} value is mandatory and will be replaced with the timer.Use the {{#strong}}{{/strong}} tags to emphasize the timer in bold. | waitForRedirectToBanksPage | string | Через {{#strong}}{{countdown}} сек.{{/strong}} Вы будете перенаправлены на страницу банка-эмитента. Successful payment page | successPaymentScreen | object | Successful payment page header | title | string | Успешно Transaction data | transactionData | object | Transaction amount label | amountLabel | string | Сумма Payment type data (card type and masked card number) label | creditCardLabel | string | Карта Transaction ID label | transactionIdLabel | string | ID транзакции Unknown error message | unknownError | string | Что-то пошло не так... An example of code to modify texts: 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 Was this helpful? What the widget looks like Code example: a page with a widget How to add a widget to a page Widget APIBank131PaymentForm Method: paymentForm.render() Event handler: paymentForm.onReady Event handler: paymentForm.onPaymentStart Event handler: paymentForm.onPaymentSuccess Event handler: paymentForm.onPaymentFail Event handler: paymentForm.onDestroy Widget customizationHide CVV/CVC details Open the 3D Secure window as required Hide the cardholder name Appearance End user errors --- ## Money Transfers - [Money Transfers Overview](https://developer.131.ru/en/transfers/transfer-start): Cross-border money transfers from Russia without opening an account -- supported countries (Kazakhstan, Kyrgyzstan, Tajikistan, Uzbekistan), currencies, and multisession flow With this feature, individuals can transfer money from Russia abroad without opening an account. Countries to which you can make a transfer Country | Country code | Transfer method | Transfer currency | Limitations --- | --- | --- | --- | --- Kazakhstan | KAZ | Bank card | Tenge (KZT) | No limitations Kyrgyzstan | KGZ | Bank card | Som (KGS) | Transfers to Elcart only Tajikistan | TJK | Bank card | Somoni (TJS) | No limitations Uzbekistan | UZB | Bank card | Uzbekistan sum (UZS) | No limitations Money transfer features info Money transfer operations are only available for individuals 18 years old or older. When filling in information on the recipient, make sure the data you specify matches the passport the recipient will use to receive the money. Money transfers are processed within multisessions. One multisession combines multiple transactions: write-off (debiting the sender) and payout (crediting to the recipient). The exchange rate is reserved for a limited time (up to 5 minutes). The following terms are used in the documentation: Payment partner - an entity that accepts, transfers, and pays out funds. Sender - an individual who transfers funds. Recipient - an individual who receives the funds transferred from the sender. Note that the sender can be the recipient too in case of a refund or transfer to self. Payment - a transaction within which funds are accepted from the sender. Payout - a transaction within which funds are paid out to the recipient. Was this helpful? Countries to which you can make a transfer Money transfer features --- - [Transfers Without Widget](https://developer.131.ru/en/transfers/transfer-without-widget): Direct API integration for money transfers without using the widget This scenario describes initiating a money transfer if you decided to obtain and store bank card details on your side (you must comply with the additional PCI DSS requirements). Sequence diagram of a money transfer Step 1. Preliminary rate calculation (optional) Before initiating the transfer, you can request the currency exchange rate using the 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 examplesDirect rate, from RUB to TRY Inverse rate, from UZS to RUB 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" } } }' 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 examplesDirect rate, from RUB to TRY Inverse rate, from UZS to RUB Unsuccessful response example { "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 } } } { "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 } } } { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } Step 2. Starting the transfer Start the transfer using the 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. Request examplesTransfer from a bank card to a bank card in Tajikistan Transfer from a bank card to IBAN in Turkey 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" } } } }] }' 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 examplesTransfer from a bank card to a bank card in Tajikistan Transfer from a bank card to IBAN in Turkey Unsuccessful response example { "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 } }] } } { "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 } }] } } { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } Wait for a 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.exchanges object will contain the current exchange rate and the debit and payout amounts. Webhook example curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "status": "ok", "session": { "id": "ps_3808364", "status": "in_progress", "created_at": "2025-08-08T12:30:02.616632Z", "updated_at": "2025-08-08T12:30:04.489651Z", "payout_list": [{ "id": "po_955258", "status": "pending", "created_at": "2025-08-08T12:30:03.401467Z", "payout_details": { "type": "card", "card": { "brand": "mir", "last4": "5389", "country_iso3": "RUS" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "recipient": { "full_name": "Sidor Sidorov Sidorovich", "first_name": "Sidor", "last_name": "Sidorov", "middle_name": "Sidorovich", "country_iso3": "TJK", "date_of_birth": "2000-11-08", "citizenship_country_iso3": "TJK", "contacts": { "phone": { "full_number": "+43523452345", "country_iso3": "TJK", "operator_code": "352", "short_number": "3452345" }, "email": "recipient@test.tr" } } } }], "payment_list": [{ "id": "pm_2765897", "status": "pending", "created_at": "2025-08-08T12:30:03.401320Z", "customer": { "reference": "lucky" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "1111", "country_iso3": "POL" } }, "amount_details": { "amount": 37700, "currency": "TJS" }, "participant_details": { "sender": { "full_name": "Ольга Зайцева Александровна", "first_name": "Ольга", "last_name": "Зайцева", "middle_name": "Александровна", "country_iso3": "RUS", "city": "Уренгой", "postal_code": "119900", "building": "99", "date_of_birth": "1998-03-15", "street": "Конаковская", "flat": "1", "state": "Московская область", "identity_document": { "id_type": "Паспорт иностранного гражданина", "id_number": "8008 579120", "issue_date": "2020-03-01" }, "citizenship_country_iso3": "TRY", "contacts": { "phone": { "full_number": "+992910011020", "country_iso3": "TJK", "operator_code": "937", "short_number": "6151530" }, "email": "sender@test.com" } } }, "payment_options": { "return_url": "https://www.131.ru/", "recurrent": false } }], "next_action": "confirm" }, "confirm_information": { "exchanges": [{ "id": "pm_2765897", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 306237, "currency": "RUB" } }, { "id": "po_955258", "source": { "amount": 37700, "currency": "TJS" }, "destination": { "amount": 306237, "currency": "RUB" }, "fx_rate": "8.123", "commission": { "amount": 0, "currency": "RUB" } }] } }' Step 3. Confirming the transfer Check the transfer details and confirm the transfer using the session/confirm method. You need to confirm the session within 5 minutes. You can cancel the transfer using the session/cancel method. Request examplecurl -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{ "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 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 examplecurl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' Step 4. Canceling the transfer (optional) If required, you can cancel the transfer using the session/cancel method. Request examplecurl -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{ "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 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. List of possible errors Webhook examplecurl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [ { "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 } ], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' Was this helpful? Sequence diagram of a money transferStep 1. Preliminary rate calculation (optional) Step 2. Starting the transfer Step 3. Confirming the transfer Step 4. Canceling the transfer (optional) Step 5. Payout to the recipient --- ## API Reference - [Objects](https://developer.131.ru/en/reference/objects): Complete reference of all API objects -- card, customer, session, payment/payout details, amounts, fees, fiscalization, tokenization, webhook payloads (v1 and v2 naming differences documented) 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 recipient | + | object | Information about the recipient account 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 total_balance | - | object | Balance information transactions | - | array | Information on transactions acquiring_payments = payment_list Use acquiring_payments for API v1, and payment_list for API v2. An array with all the payment details. Name | Mandatory | Type | Description --- | --- | --- | --- id | + | string | Unique payment identifier status | + | string | Payment status Possible values: succeeded, in_progress, pending, failed created_at | + | string | Creation date in ISO 8601 format payment_details | + | object | Payment data amount_details | + | object | Amount amounts | - | object | Transaction fee finished_at | - | string | Completion date in ISO 8601 format customer | + | object | User (payer) details recurrent | - | object | Details needed to perform recurring payments participant_details | - | object | Participants' details refunds | - | array | Refund list customer_interaction | - | object | Data needed for user interaction transaction_info | - | object | Transaction details metadata | - | object | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks error | - | object | Error description Payment statuses (status) in_progress - the payment is being processed. pending - awaiting your confirmation (session/confirm) or cancellation (session/cancel). succeeded - the payment has been completed successfully. failed - the payment has not gone through due to an error. acquiring_widget Settings for the payout form widget (for performing bank card payments). Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Identifies the payment session for which the payment will be performed show_recurrent_checkbox | - | bool | Whether to display the Enable automatic payments checkbox in the widget interface success_return_url | - | string | URL to which the user is redirected after the payment has been successfully completed failure_return_url | - | string | URL to which the user is redirected when an error occurs during the payment success_on_hold | - | bool | Whether to show a message about a successful payment to a payer when holding. By default, false and the widget shows a loading screen until the end of the hold redirect_target | - | string | Redirect link open options: - top -- outside of all the frames as the top window - self -- in the same frame - parent -- in the next-level frame if the frames are nested in one another. Default: top actions Information about actions taken. Name | Mandatory | Type | Description --- | --- | --- | --- confirm | - | string | Confirmation date in ISO 8601 format capture | - | string | Capture date in ISO 8601 format amount Amount object. Name | Mandatory | Type | Description --- | --- | --- | --- amount | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter 10000 currency | + | string | ISO 4217 currency code. Case insensitive. Options: rub, eur amount_details Amount object. Name | Mandatory | Type | Description --- | --- | --- | --- amount | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter 10000 currency | + | string | ISO 4217 currency code. Case insensitive. Options: rub, eur amounts Information on the transaction fee. Name | Mandatory | Type | Description --- | --- | --- | --- fee | - | object | Information on the applicable fee 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 destination | + | object | Amount and currency to be paid to the recipient transfer_fee | - | object | Sender's fee for money transfer sms_fee | - | object | Sender's fee for SMS notification to the recipient payment | - | object | Total amount to write off of the sender 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) faster_payment_system | - (mandatory for system_type = faster_payment_system) | object | Recipient's data in the 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 iban | - | object | Money transfer recipient's 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 encrypted_card | - (mandatory for type = encrypted_card) | object | Card with encrypted fields (tokenized) tokenized_card | - (mandatory for type = tokenized_card) | object | Tokenized card number 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 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 account_details | + (for payouts to bank accounts) | object | Information about the sender and recipient accounts exchanges | + (for money transfers) | object | Information about exchange rates contacts An array with the contacts of a user (payout recipient or payment sender). Parent 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, recipient. Name | Mandatory | Type | Description --- | --- | --- | --- email | - | string | User's email phone | - | object | User's phone number 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, payments/payout_list. 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 customer (payer) Information about the payer of a payout from an escrow account. Parent objects: 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 resend_sms | + | object | Data for requesting a new code 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 inform | - (mandatory for type = inform) | object | Payment option data 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 request. Name | Required | Type | Description --- | --- | --- | --- number | + | object | Token information 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 Error codes 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 destination | + | object | Amount and currency to be paid to the recipient fx_rate | + | number | Exchange rate, displayed to 4 decimals commission | + | object | Amount and currency of the commission for transfer 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 method description | - (mandatory for payouts) | string | Payout or payment purpose subscription_service_info | - | object | Subscription details 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 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 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 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 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. 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 request. Parent objects: 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 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 transfer_from_bank_account | - (mandatory for type = transfer_from_bank_account) | object | Information about a transfer from a settlement 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 method Method details. Name | Mandatory | Type | Description --- | --- | --- | --- name | + | string | Method name (account_statement) account_statement | + | object | Statement details 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 notificationACKNOWLEDGED - read notificationARCHIVED - archived notification created_at | + | dateTime | Notification date number Token and tokenized card details. Name | Required | Type | Description --- | --- | --- | --- token | + | string | Token info | + | object | Card information participant_details Payout participant details. Name | Mandatory | Type | Description --- | --- | --- | --- sender | - | object | Sender's details recipient | - | object | Recipient's details 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 + transfer_fee + 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 recurrent | - (mandatory for type = recurrent) | object | Details for repeating the payment using the token internet_banking | - (mandatory for type = internet_banking) | object | Details on payments via payment systems internal_transfer | - (mandatory for type = internal_transfer) | object | Internal transfer details faster_payment_system | - (mandatory for type = faster_payment_system) | object | Payment via FPS wallet | - (mandatory for type = wallet) | object | Payment via 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 bank_account | - (mandatory for type = bank_account) | object | Recipient's bank account wallet | - (mandatory for type = wallet) | object | Recipient's electronic wallet tax | - (mandatory for type = tax) | object | Payouts to the Russian Federal Tax Agency recurrent | - (mandatory for type = recurrent) | object | Payout with token tokenized_card | - (mandatory for type = tokenized_card) | object | Payout with tokenized card number 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 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, e.g. the login that lets you verify the recipient on your side payment_method/payout_details | + | object | Method of receiving the payout amount_details | + | object | Amount amounts | - | object | Transaction fee fiscalization_details | - | object | Fiscalization details participant_details | - | object | The details of payout participants required to perform the payout, e.g. the names and addresses of the payer and the recipient refunds | - | array | Refund list transaction_info | - | object | Transaction details metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks error | - | object | Error description Payout statuses (status) in_progress - the payment is being processed. pending - awaiting your confirmation (session/confirm) or cancellation (session/cancel). 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) tax_reference | + | string | Self-employed person's INN receipt | - | object | Fiscalization receipt. Returned in notifications payer_type | - | string | 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 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. 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. 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, 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. 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. Parent arrays: acquiring_payments/payment_list. 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 | Set of parameters depending on the transaction method params | - | map | 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 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 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 should be made (via BESP). A speedy payout takes place within an hour, a regular one--up to 3 banking days sber_pay SberPay payment details. Name | Mandatory | Type | Description --- | --- | --- | --- phone | - | string | Phone number to send PUSH or SMS to. Format: 7********** channel | + | ENUM | SberPay payment channel. Options: app, mobile_web, web self_employed_widget Settings for the widget used for linking self-employed people to Bank 131. Name | Mandatory | Type | Description --- | --- | --- | --- tax_reference | - (if phone is passed) | string | Self-employed person's INN phone | - (if tax_reference is passed) | string | Self-employed person's phone number sender (escrow payer details) Information about the payer of a payout from an escrow account. Parent objects: account_details. 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. 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 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 acquiring_payments/payment_list | - | array | A list of payments performed within the session 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 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) or cancel it (session/cancel). capture - you need to perform the debit (session/capture) or cancel it (session/cancel). 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 tax_details Data for tax payments. Name | Required | Type | Description --- | --- | --- | --- period | - (required when type = full) | string | Tax period period | - (required when type = tax_short) | object | Tax 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 document_number | - (required when type = full) | string | Document number document_date | - (required when type = full) | string | Document 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 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 customer | + | object | Information about a payer recipient | + | object | Information about a recipient purpose | + | string | Payout purpose in the following format: ; card: amount | + | object | 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 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 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) Was this helpful? accept_code account_details account_statement acquiring_payments = payment_list acquiring_widget actions amount amount_details amounts amounts (for money transfers) balance bank_account bank_account_ru bank_card card card_elements commission confirm_information contacts contacts (for money transfers) counter_party customer (user in your system) customer (payer) customer_authorization customer_interaction data (user account) data (token and card number) destination encrypted_card error exchanges faster_payment_system faster_payment_system_verification fee fiscalization_details iban identity_document info (bank account token) info (tokenized bank card) info (notifications number) info (notifications information) info (public token) info (token for recurring payments or payouts) info (tokenized card details) inform internal_transfer internet_banking method notification_list notifications number participant_details payee payer payment payment_details payment_method = payout_details payment_options payments = payout_list period phone platform_details professional_income_taxpayer public_token qr rate receipt recipient (recipient of a payout from an escrow account) recipient (payout recipient details) recurrent (token for recurring payments or payouts) recurrent (information about a token for recurring payments or payouts) recurrent_token redirect refunds resend_sms ru sber_pay self_employed_widget sender (escrow payer details) sender (payout payer details) services session sms_fee source subscription_service_info tax tax_details tokenize_widget tokenized_card total_balance total_turnover transaction_info transactions transfer_details transfer_fee transfer_from_bank_account transfer_from_nominal_account wallet wallets yoomoney --- - [Methods](https://developer.131.ru/en/reference/methods): Complete API method reference -- session lifecycle (create, start, confirm, cancel, capture, refund), tokenize, fps/banks, recurrent/disable, wallet/balance, account/statement (v1 and v2 endpoints) When processing requests, the system checks for valid input parameters, the presence of the necessary headers, and rights to perform operations. info In the documentation, the mandatory status of parameters is specified for each transaction, but you are not required to pass them in the body of this particular request. You can pass them in advance--when creating a session. Example of sending a payout request: If the session/create request was sent empty, the payout request (session/start/payout) must contain all the mandatory parameters. If the session/create request contained all the mandatory parameters specified for the transaction, the payout request (session/start/payout) can be empty or contain only those parameters the values of which you want to override. If the session/create request contained some of the mandatory parameters, the payout request (session/start/payout) must contain the remaining ones. If you create a session and a payout in a single request (session/init/payout), pass all required parameters right away. Performing operations recurrent/disable Disable token for recurring payments You can disable a token with this request. Send the token in the request, in the response you will get is_active: false. This means you cannot perform recurring payments with this token. After the token has disabled, the token expiration setting finished_at may contain a weird date of the year 2000. This value won't affect anything, so please disregard it. Endpoint /api/v1/recurrent/disable Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- recurrent | + | object | Token information Request examplecURL PHP 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" } }' 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 Response example{ "recurrent": { "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427", "created_at": "2020-07-14T13:17:11+03:00", "finished_at": "2020-07-31T16:05:42+03:00", "is_active": false, "type": "recurrent_token" }, "status": "ok" } session/cancel Operation cancellation This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a ready_to_confirm or a ready_to_capture webhook. If you do not want to perform the operation, you can cancel it by sending a session/cancel. If everything looks good, send a request to confirm the operation (session/confirm) or a request to debit the amount being put on hold (session/capture). API v1 API v2 Endpoint /api/v1/session/cancel Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Session identifierRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } Endpoint /api/v2/session/cancel Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Session identifierRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/capture Debiting amounts put on hold This request can be used if you are sending delayed capture payments. These payments are performed in two stages: first, the money is put on hold (for example, on the user's bank card), and then it is debited in response to your request. The request can be sent when Bank 131 is ready to debit the money and has sent you a ready_to_capture webhook. If you want to debit the amount put on hold, send a session/capture. You can debit the full amount on hold, or a portion of it. To cancel the debit, send a (session/cancel). API v1 API v2 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 debitedRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] }] } } { "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 debitedRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] }] } } { "error": { "code": "error code", "description": "error description" }, "status": "error" } session/confirm Operation confirmation This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a ready_to_confirm webhook. You'll need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a session/confirm request. The confirmation window is 4 hours from the moment of transaction creation. Failure to submit the request on time will result in a confirm_timeout error. If something is not right, cancel the operation by sending a session/cancel request. API v1 API v2 Endpoint /api/v1/session/confirm Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Session identifier confirm_information | - (mandatory for the transactions with an escrow account or when requier_confirm_information = true) | object | Transaction confirmation informationRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 informationRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/create Payment session creation Creates a payment session on Bank 131's side. Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund). Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. If you are ready to provide all the data needed to perform the operation in the request, you can use the method whereby the payout (session/start/payout) or the payment (session/start/payment) starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. API v1 API v2 Endpoint /api/v1/session/create Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | - | object | Payment details (card, customer account, etc.) payment_details | - | object | Transfer details amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | - (mandatory for payouts) | object | Information about the participants (the sender and the recipient) customer | - (mandatory for payments) | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z" } } { "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 (card, customer account, etc.) payment_details | - | object | Transfer details amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | - (mandatory for payouts) | object | Information about the participants (the sender and the recipient) customer | - (mandatory for payments) | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "status": "ok", "session": { "id": "ps_3230", "status": "created", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z" } } { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } session/init/payment Session creation with simultaneous payout initiation Can be used if you are ready to pass all the parameters needed for the payment at once. The response contains the parameters of the session created and an array with information about the payment (acquiring_payments/payment_list). API v1 API v2 Endpoint /api/v1/session/init/payment Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_details | + | object | Payment data amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | - | object | Participants information customer | + | object | Client data in your system payment_options | - | object | Additional payment parameters metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('http://bank131.ru'); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '05', '22', '123')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayout($request); Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok session | - | object | Payment session error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] } } { "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 amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | - | object | Participants information customer | + | object | Client data in your system payment_options | - | object | Additional payment parameters metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Card\BankCard; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $paymentOptions = new PaymentOptions(); $paymentOptions->setReturnUrl('http://bank131.ru'); $request = RequestBuilderFactory::create() ->initPaymentSession() ->setCard(new BankCard('4242424242424242', '05', '22', '123')) ->setAmount(10000, 'rub') ->setCustomer(new Customer('lucky')) ->setPaymentOptions($paymentOptions) ->build(); $response = $client->session()->initPayout($request); Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok session | - | object | Payment session error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] } } { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } session/init/payment/sync Please be aware that we do not recommend implementing this method unless you have already used it before. One-request payment This method allows sending a payment request and getting a response right away. Use it if you are ready to submit all payment parameters in this request. The response contains the parameters of the session created and the acquiring_payments/payment_list array with the payment result and information. API v1 API v2 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 type | + | string | Payment method type. Possible values: card card | + | object | Bank card details type | + | string | Method of card information transmission. Value: bank_card bank_card | + | object | Card information 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 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 customer | + | object | Information about payment sender on your side reference | + | string | Payment sender ID in your system payment_options | + | object | Additional payment parameters 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 webhooksRequest examplecURL 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] } } { "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 type | + | string | Payment method type. Possible values: card card | + | object | Bank card details type | + | string | Method of card information transmission. Value: bank_card bank_card | + | object | Card information 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 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 customer | + | object | Information about payment sender on your side reference | + | string | Payment sender ID in your system payment_options | + | object | Additional payment parameters 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 webhooksRequest examplecURL 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] } } { "error": { "code": "invalid_request", "description": "customer.reference.not_blank" }, "status": "error" } session/init/payout Session creation with simultaneous payout initiation This request can be used if you are ready to pass all the parameters needed for the payout at once, for example when transferring a payout to a Russian bank account. The response contains the parameters of the session created and an array with the information about the payout (payments/payout_list). API v1 API v2 Endpoint /api/v1/session/init/payout Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | + | object | Payment details (card, customer account, etc.) amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details participant_details | - | object | Information about the participants (the sender and the recipient) customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 (card, customer account, etc.) amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details participant_details | - | object | Information about the participants (the sender and the recipient) customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/init/payout/fiscalization Session creation and payout start, with additional check that all the fiscalization data has been provided Can be used for payouts to self-employed people if you are ready to provide all the information about the self-employed person and the details necessary to create the payout at once, for example when transferring a payout to a Russian bank account. The response contains the parameters of the session created and an array with the information about the payout (payments/payout_list) with the data necessary to send the receipt. API v1 API v2 Endpoint /api/v1/session/init/payout/fiscalization Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | - | object | Payment details (card, customer account, etc.) amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details participant_details | - | object | Information about the participants (the sender and the recipient) customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 (card, customer account, etc.) amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details participant_details | - | object | Information about the participants (the sender and the recipient) customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "code": "invalid_request", "description": "participant_details.recipient.full_name.not_blank" }, "status": "error" } session/refund Refund You can use this request to return money to the user after a successful payment. After completing the refund, Bank 131 will send you a payment_refunded webhook. API v1 API v2 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. If not specified, the refund will be made for the full amount of the payment metadata | - | * | Additional informationRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] }] } } { "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. If not specified, the refund will be made for the full amount of the payment metadata | - | * | Additional informationRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } }] }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/start/payment Payment start This request can be used to start a payment within an existing session. In the parameters, you can pass the data necessary to perform the payment or change pieces of data that have already been passed. API v1 API v2 Endpoint /api/v1/session/start/payment Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Payment session identifier payment_details | - | object | Payment data amount_details | - | object | Amount participant_details | - | object | Information about the participants (the payer and the recipient) customer | - | object | Payment sender information in your system payment_options | - | object | Additional payment settings metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 amount_details | - | object | Amount participant_details | - | object | Information about the participants (the payer and the recipient) customer | - | object | Payment sender information in your system payment_options | - | object | Additional payment settings metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "internal error", "code": "repository_record_not_found" } } session/start/payout Payout start This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. API v1 API v2 Endpoint /api/v1/session/start/payout Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Payment session identifier payment_method | - | object | Payout details (card, customer account, etc.) amount_details | - | object | Amount participant_details | - | object | Information on payout participants customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 (card, customer account, etc.) amount_details | - | object | Amount participant_details | - | object | Information on payout participants customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/start/payout/fiscalization Payout start, with check that all fiscalization data has been provided This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. API v1 API v2 Endpoint /api/v1/session/start/payout/fiscalization Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Payment session identifier payment_method | - | object | Payment details (card, customer account, etc.) amount_details | - | object | Amount fiscalization_details | - | object | Fiscalization details participant_details | - | object | Information on payout participants customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } }] } } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230', $incomeInformation) ->build(); $response = $client->session()->create($request); Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok session | - | object | Payment session error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 (card, customer account, etc.) amount_details | - | object | Amount fiscalization_details | - | object | Fiscalization details participant_details | - | object | Information on payout participants customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecURL PHP 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" } }] } } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection; use Bank131\SDK\DTO\FiscalizationService; use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $services = new FiscalizationServiceCollection(); $services[] = new FiscalizationService( 'Delivery', new Amount(5000, 'rub'), 1 ); $incomeInformation = new ProfessionalIncomeTaxpayer( $services, '590000000000' ); $incomeInformation->setPayerName('Vector LLC'); $incomeInformation->setPayerType('legal'); $incomeInformation->setPayerTaxNumber('330000000000'); $request = RequestBuilderFactory::create() ->startPayoutSessionWithFiscalization('3230', $incomeInformation) ->build(); $response = $client->session()->create($request); Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok session | - | object | Payment session error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } token Getting a token to work with widgets The token is needed to access Bank 131's JavaScript library. You can get it using this request. The token is valid for 24 hours and can be used for a single operation only. When sending a request, specify the widget you are going to work with. Endpoint /api/v1/token Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- tokenize_widget | - | object | Data required by the tokenization widget self_employed_widget | - | object | Data required by the self-employed registration widget acquiring_widget | - | object | Data required by the payment form widget An example of how to get a token to perform a payout that involves obtaining card details via the widget and connecting a self-employed personcURL PHP curl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "tokenize_widget": { "access": true }, "self_employed_widget": { "tax_reference": "111111111111" } }' use Bank131\SDK\API\Request\Builder\RequestBuilderFactory; use Bank131\SDK\Client; use Bank131\SDK\Config; $config = new Config( 'https://demo.bank131.ru', 'your_project_name', file_get_contents('/path/to/your/private_key.pem') ); $client = new Client($config); $request = RequestBuilderFactory::create() ->issuePublicTokenBuilder() ->setTokenizeWidget() ->setSelfEmployedWidget('111111111111') ->setAcquiringWidget( 'test_ps_id', 'http://success.url', 'http://failed.url', false ) ->build(); $response = $client->widget()->issuePublicToken($request); $publicToken = $response->getPublicToken(); An example of how to get a token to perform a payment through a payment formcurl -X POST \ https://demo.bank131.ru/api/v1/token \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "acquiring_widget": { "session_id": "ps_123456" } }' Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok public_token | - | string | Public token error | - | object | Error Response examplesSuccessful response example Unsuccessful response example { "status": "ok", "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539" } { "status": "error", "error": { "description": "acquiring_widget.session_id.not_unique", "code": "invalid_request" } } tokenize Tokenizing a bank account number This method is used for tokenizing a bank account (payout). Use it to get a token and a masked account number. The token received in the response does not expire. You can tokenize any account that passes verification against a specified range of accounts. Otherwise, the "Enter a different account number" error will be returned. Endpoint /api/v1/tokenize Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- type | + | string | Bank account type bank_account_ru | + | object | Russian bank account details bik | + | string | Bank BIK account | + | string | Account number Request examplecurl -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 error | - | object | Error Response examplesSuccessful response example Unsuccessful response example { "status": "ok", "token": "2c6ebe1368407b922057efee0fed58360dae1d28af50fa6734bb54c61a763c24", "data": { "masked_account": "40817***9535" } } { "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 Request examplecurl -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 error | - | object | Error Response examplesSuccessful response example Unsuccessful response example { "status": "ok", "data": { "number": { "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919", "info": { "masked_card_number": "424242******4242", "card_network": "visa", "card_type": "visa" } } } } { "status": "error", "error": { "description": "error description", "code": "error code" } } Information fps/banks You can use this request to get a list of names and identifiers of banks-recipients of the Faster Payment System. The method can be used for payouts only. Endpoint /api/v1/fps/banks Request examplecURL PHP 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 '{}' use Bank131\SDK\Client; $response = $client->fps()->getBanks(); foreach ($response->getBanks() as $bank) { echo $bank->getId(), ' ', $bank->getRuName(), ' ', $bank->getEngName(), PHP_EOL; } Response example{ "banks": [{ "id": "100000000243", "eng_name": "National Standard Bank", "ru_name": "Национальный стандарт" }, { "id": "100000000056", "eng_name": "Khlynov", "ru_name": "Хлынов" },...] } fps/customer_verification You can use this request to check whether a recipient is registered in the Faster Payment System (FPS). If the user is found in the FPS, the session will have a successful status, otherwise the session will be canceled. This operation is free of charge and is confirmed automatically (ready_to_confirm is not sent). API v1 API v2 Endpoint /api/v1/fps/customer_verification Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | + | object | Payment details (card, customer account, etc.) participant_details | + | object | Information about the participants (the sender and the recipient)Request examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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": "Иванович" } } }] } } { "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 (card, customer account, etc.) participant_details | + | object | Information about the participants (the sender and the recipient)Request examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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": "Иванович" } } }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } report/account_balance Use this method to get your settlement or escrow account balance. More on account balance. 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 examplecurl -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 error | - | object | Error Response examplesSuccessful response example Unsuccessful response example { "status": "ok", "account_number": "40702810400000000333", "account_currency": "RUB", "balance": { "current_balance": 20900 } } { "status": "error", "error": { "code": "Error code", "description": "Error description" } } report/account_statement Use this method to get bank statements for your settlement or escrow account opened in rubles. Statements can only be generated for a day. To learn more, click here. 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 examplecurl -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 name | + | string | Method name (account_statement) account_statement | + | object | Statement details 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 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 opening | + | int | Opening balance on the statement start date closing | + | int | Closing balance on the statement end date transactions | + | array | Information on 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 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{ "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 examplesInvalid dates Invalid JSON format Internal error date_from does not match date_to { "status": "error", "error": { "description": "Invalid input request parameters: (max interval is 1 day)", "code": "invalid_request" } } date_from is greater than date_to { "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 { "status": "error", "error": { "description": "Invalid value in date_from", "code": "invalid_request" } } Invalid date in date_to { "status": "error", "error": { "description": "Invalid value in date_to", "code": "invalid_request" } } { "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 { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } session/status Obtaining session information You can send this request if you want to obtain full information about the payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment. The response contains the payment session with details about all the operations performed during it. API v1 API v2 Endpoint /api/v1/session/status Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Payment session identifierRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 identifierRequest examplecURL PHP 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" }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } token/info Receiving information via token Operations with bank cards are often carried out with tokenized values. For payouts and payments through widgets, a public token is created. A token ca also be created for recurring payments. For any payment token you can get information: About the bank card for which that token was created - this will be the hidden card number and payment system. About the token itself - type of token, time of creation, expiration date, active or inactive at the moment of inquiry. This method can be used, for example, to learn the hidden card number and show the user which card the funds will be debited from. Or if you need to check the token expiration date. Endpoint /api/v1/token/info Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- type | + | string | Type of request. Options: card, public_token, recurrent_token, bank_account_ru card | - (mandatory for type = card) | object | Bank card details public_token | - (mandatory for type = public_token) | object | Token details recurrent_token | - (mandatory for type = recurrent_token) | object | Token details bank_account_ru | - (mandatory for type = bank_account_ru) | object | Bank account details Information request examplesCard number hash Public token Token for recurring payments or payouts Bank account token You send a card number hash and receive information about it. 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. 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. 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. 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, public token, token for recurring payments or payouts, or bank account token error | - | object | Error Response examplesCard information via hash Information about a public token Information about a token for recurring payments or payouts Information about a bank account token { "status": "ok", "info": { "number_hash": "card_number_hash", "brand": "visa", "last4": "4242", "type": "card" } } { "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" } } { "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" } } { "status": "ok", "info": { "masked_account": "40817***9535", "created_at": "2024-02-08T17:17:44+03:00", "finished_at": "2124-02-08T17:17:44+03:00", "type": "bank_account_ru" } } wallet/balance You can use this request to check your current Bank 131 deposit balance. note This method can be used for payouts only. You can find your acquiring balance information in your remote banking service account in the Statements section, provided that compensations are paid to your Bank 131 account. This is necessary in order to make sure there is enough money on the balance: for payouts for returns If the amount is insufficient, you can top up your deposit. The request does not return the information about your escrow account balance. You may find this information in your remote banking service account in the Accounts section or use the report/account_balance method. Endpoint /api/v1/wallet/balance Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- request_datetime | + | string | Timestamp of the request in ISO 8601 Request examplecURL PHP 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" }' 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 error | - | object | Error Response examplesSuccessful response example Unsuccessful response example { "status": "ok", "wallets": [{ "id": "131", "amount_details": { "amount": 13100, "currency": "rub" } }] } { "status": "error", "error": { "description": "error description", "code": "error code" } } Self-employed people npd/accruals and npd/request/status The method allows to obtain detailed information about tax accruals and bonus amount for the self-employed. The request consists of two parts: Send an npd/accruals request, passing a self-employed person's details, and receive the request_id identifier in response. Send an npd/request/status request with this identifier. In response, you will receive detailed information about tax accruals and bonus amount for the self-employed. The endpoint to send the npd/accruals request /api/v1/npd/accruals Request parameters for npd/accruals Name | Mandatory | Type | Description --- | --- | --- | --- tax_reference_list | + | array | List of tax reference numbers (INN). Limited to 100 INNs per single request Request example for npd/accrualscurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/accruals Request example for npd/request/statuscurl -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{ "status": "ok", "accruals": [{ "tax_charge_list": [{ "amount": "", "due_date": "", "tax_period_id": "", "oktmo": "", "kbk": "", "paid_amount": "", "create_time": "", "id": "" }], "krsb_list": [{ "debt": "", "penalty": "", "overpayment": "", "oktmo": "", "kbk": "", "tax_organ_code": "", "update_time": "", "id": "" }], "inn": "111111111111" }] } npd/notifications/count and npd/request/status The method allows to obtain the number of unread notifications the Federal Tax Service sent to the self-employed. The request consists of two parts: Send an npd/notifications/count request, passing a self-employed person's details, and receive the request_id identifier in response. Periodically send an npd/request/status request with this identifier. In response, you will receive the number of unread notifications. The pending status indicates that you must repeat the request. The endpoint to send the npd/notifications/count request /api/v1/npd/notifications/count Request parameters for npd/notifications/count Name | Mandatory | Type | Description --- | --- | --- | --- tax_reference_list | + | array | List of tax reference numbers (INN) (limited to 1000 per single request) Request example for npd/notifications/countcurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/notifications/count Request example for npd/request/statuscurl -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 Response example for npd/request/status{ "status": "ok", "info": [{ "tax_reference": "123456789012", "count": 0 }] } npd/notifications/mark_as_delivered and npd/request/status The method allows to inform the Federal Tax Service that notifications were delivered to a self-employed person. This method must be used after the notifications/read method. The request consists of two parts: Send an npd/notifications/mark_as_delivered request, passing a self-employed person's details, and receive the request_id identifier in response. Send an npd/request/status request with this identifier. In response, you will receive the status of the delivery. The endpoint to send the npd/notifications/mark_as_delivered request /api/v1/npd/notifications/mark_as_delivered Request parameters for npd/notifications/mark_as_delivered Name | Mandatory | Type | Description --- | --- | --- | --- notification_list | + | array | Information about notifications Request example for npd/notifications/mark_as_deliveredcurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/notifications/read Request example for npd/request/statuscurl -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{ "status": "ok" } npd/notifications/read and npd/request/status The method allows to obtain the detailed information about unread notifications the Federal Tax Service sent to the self-employed. The request consists of two parts: Send an npd/notifications/read request, passing a self-employed person's details, and receive the request_id identifier in response. Periodically send an npd/request/status request with this identifier. In response, you will receive detailed information about unread notifications. The pending status indicates that you must repeat the request. The endpoint to send the npd/notifications/read request /api/v1/npd/notifications/read Request parameters for npd/notifications/read Name | Mandatory | Type | Description --- | --- | --- | --- tax_reference_list | + | array | List of tax reference numbers (INN) get_read | + | boolean | Send the already read notifications in response. Possible values: true - send; false - do not send get_archived | + | boolean | Send the archived notifications in response. Possible values: true - send; false - do not send Request example for npd/notifications/readcurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/notifications/read Request example for npd/request/statuscurl -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) Response example for npd/request/status{ "status": "ok", "info": [{ "tax_reference": "123456789012", "notifications": [{ "id": "132313", "title": "131.ru is asking for permission to act on your behalf", "message": "131.ru has asked you for permission to perform certain operations on your behalf. You can view the list of the operations and grant the permission by clicking Allow, or deny by clicking Deny", "status": "NEW", "created_at": "2023-03-22T13:29:55+00:00" }] }] } npd/notifications/update and npd/request/status The method allows to inform the Federal Tax Service that notifications were read by the self-employed. The method must be used after the notifications/mark_as_delivered method. The request consists of two parts: Send an npd/notifications/update request, passing a self-employed person's details, and receive the request_id identifier in response. Send an npd/request/status request with this identifier. In response, you will receive the status of the request. The endpoint to send the npd/notifications/update request /api/v1/npd/notifications/update Request parameters for npd/notifications/update Name | Mandatory | Type | Description --- | --- | --- | --- notification_list | + | array | Information about notifications Request example for npd/notifications/updatecurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/notifications/update Request example for npd/request/statuscurl -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{ "status": "ok" } npd/taxpayer/account_status and npd/request/status The method allows to obtain general information about tax accruals and bonus amount for the self-employed. The request consists of two parts: Send an npd/taxpayer/account_status request, passing a self-employed person's details, and receive the request_id identifier in response. Send an npd/request/status request with this identifier. In response, you will receive general information about tax accruals and bonus amount for the self-employed. The endpoint to send the npd/taxpayer/account_status request /api/v1/npd/taxpayer/account_status Request parameters for npd/taxpayer/account_status Name | Mandatory | Type | Description --- | --- | --- | --- tax_reference | + | string | Tax reference number (INN). Limited to 1 INN per single request Request example for npd/taxpayer/account_statuscurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/taxpayer/account_status Request example for npd/request/statuscurl -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{ "status": "ok", "bonus_amount": "9972.3624", "unpaid_amount": "0", "debt_amount": "0" } npd/taxpayer/check_personal_info and npd/request/status Verification of the self-employed data This request allows to verify with the Federal Tax Service if there is any inconsistency in data (INN, full name, phone number) provided by a self-employed person. The request consists of two parts: Send an npd/taxpayer/check_personal_info request, passing a self-employed person's INN, full name, and phone number, and receive the request_id identifier in response. Periodically send an npd/request/status request with this identifier. In response, you will receive a list of inconsistent parameters, if there is any. The pending status indicates that you must repeat the request. The endpoint to send the npd/taxpayer/check_personal_info request /api/v1/npd/taxpayer/check_personal_info Request parameters for npd/taxpayer/check_personal_info Name | Mandatory | Type | Description --- | --- | --- | --- first_name | + | string | First name second_name | + | string | Family name patronymic | + | string | Patronymic name tax_reference | + | string | Tax reference number (INN) phone | + | string | Phone number in the "7ХХХХХХХХХХ" format Request example for npd/taxpayer/check_personal_infocurl -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{ "status": "ok", "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6" } The endpoint to send the npd/request/status request /api/v1/npd/request/status Request parameters for npd/request/status Name | Mandatory | Type | Description --- | --- | --- | --- request_id | + | string | Identifier passed in response at npd/taxpayer/check_personal_info Request example for npd/request/statuscurl -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 Response example for npd/request/status{ "status": "ok", "success": false, "violations": [ "first_name", "second_name", "phone" ] } Escrow account session/create/nominal Creating a payment session This request creates a payment session on Bank 131's side. Payment operations can only be performed within a session. Use this request if you need to request the data necessary to perform a payout from the user. For example, call the tokenization widget, show it to the user and get tokenized account details, and then send the payout request with those details. If you are ready to provide all the data needed to perform the operation in the request, you can use the session/init/payout/nominal method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. API v1 API v2 Endpoint /api/v1/session/create/nominal Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | - | object | Payment details amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | - | object | Information about the participants (the sender and the recipient) fiscalization_details | - | object | 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 webhooksRequest examplescurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | - | object | Information about the participants (the sender and the recipient) fiscalization_details | - | object | 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 webhooksRequest examplescurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/init/payout/nominal Creating a session with a simultaneous payout to a bank account You can use this request to send payouts from an escrow account to a bank account, including via FPS. API v1 API v2 Endpoint /api/v1/session/init/payout/nominal Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | + | object | Payment details amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | + | object | Information about the participants (the sender and the recipient) fiscalization_details | - | object | 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 webhooksRequest examplesPayout to an individual's account Payout to a legal entity's account curl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", // for FPS payouts, use the faster_payment_system object "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | + | object | Information about the participants (the sender and the recipient) fiscalization_details | - | object | 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 webhooksRequest examplesPayout to an individual's account Payout to a legal entity's account curl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", // for FPS payouts, use the faster_payment_system object "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 300, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/multi/create/nominal Creating a payment session Creates a payment session on Bank 131's side. Payment operations can only be performed within a session. One or more operations can be performed within the session. Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. If you are ready to provide all the data needed to perform the operation in the request, you can use the session/multi/init/payment/nominal method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. API v1 API v2 Endpoint /api/v1/session/multi/create/nominal Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_details | - | object | Transfer details payment_method | - | object | Payment details (card, customer account, etc.) fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | - | object | Information about the participants (the sender and the recipient) amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 payout_details | - | object | Payment details (card, customer account, etc.) fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | - | object | Information about the participants (the sender and the recipient) amount_details | - | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 customer | - | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "description": "error description", "code": "error code" }, "status": "error" } session/multi/init/payment/nominal Creating a session with a simultaneous payout to a bank card This request can be used if you are ready to pass all the parameters needed for the payout at once. The response contains the parameters of the session created and an array with information about the payout (acquiring_payment/payment_list). API v1 API v2 Endpoint /api/v1/session/multi/init/payment/nominal Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_details | + | object | Transfer details payment_method | + | object | Payment details (card, customer account, etc.) fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | + | object | Information about the participants (the sender and the recipient) amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 customer | + | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 payout_details | + | object | Payment details (card, customer account, etc.) fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | + | object | Information about the participants (the sender and the recipient) amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 customer | + | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "description": "error description", "code": "error code" }, "status": "error" } session/multi/start/payment/nominal Starting a payout to bank card This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed. If you are using the widget for getting the user's tokenized bank card details, you can pass them using this request. API v1 API v2 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 payment_method | + | object | Payment details (card, customer account, etc.) fiscalization_details | - | object | Fiscalization details; only for payouts to the self-employed participant_details | + | object | Information about the participants (the sender and the recipient) amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 customer | + | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 payout_details | + | object | Payment details (card, customer account, etc.) fiscalization_details | + | object | Fiscalization details; only for payouts to the self-employed participant_details | + | object | Information about the participants (the sender and the recipient) amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 customer | + | object | Recipient's data in your system metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "description": "error description", "code": "error code" }, "status": "error" } session/start/payout/nominal Starting a payout to a bank account You can use this request to send payouts from an escrow account to a bank account, including via FPS. This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed. If you are using the widget for getting the user's tokenized bank account details, you can pass them using this request. API v1 API v2 Endpoint /api/v1/session/start/payout/nominal Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Payment session identifier payment_method | + | object | Payment details amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | + | object | Information about the participants (the sender and the recipient) fiscalization_details | - | object | 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 webhooksRequest examplesPayout to an individual's account Payout to a legal entity's account curl -X POST \ https://demo.bank131.ru/api/v1/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", // for FPS payouts, use the faster_payment_system object "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 amount_details | + | object | Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000 participant_details | + | object | Information about the participants (the sender and the recipient) fiscalization_details | - | object | 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 webhooksRequest examplesPayout to an individual's account Payout to a legal entity's account curl -X POST \ https://demo.bank131.ru/api/v2/session/start/payout/nominal \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -d '{ "session_id": "ps_12345", "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", // for FPS payouts, use the faster_payment_system object "ru": { "bik": "044525974", "account": "40817810400003869535", "full_name": "Ivanov Ivan Ivanovich", "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 30000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810300200000013" }, "recipient": { "beneficiary_id": "1234567890" } } }' 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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } Settlement account session/create/rko Creating a payment session This request creates a payment session on Bank 131's side. Payment operations can only be performed within a session. Use this request if you need to request the data necessary to perform a payout from the user. For example, call the tokenization widget, show it to the user and get tokenized account details, and then send the payout request with those details. If you are ready to provide all the data needed to perform the operation in the request, you can use the session/init/payout/rko method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. API v1 API v2 Endpoint /api/v1/session/create/rko Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | - | object | Payment details (bank account) amount_details | - | object | Amount in kopecks. To send 100 rubles, specify 10000 participant_details | - | object | Sender's details fiscalization_details | - | object | 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 examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 (bank account) amount_details | - | object | Amount in kopecks. To send 100 rubles, specify 10000 participant_details | - | object | Sender's details fiscalization_details | - | object | 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 examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/init/payout/rko Creating a session with a simultaneous payout to a bank account You can use this request to send payouts from a settlement account to a bank account. API v1 API v2 Endpoint /api/v1/session/init/payout/rko Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_method | + | object | Payment details (bank account) amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 participant_details | + | object | Sender's details fiscalization_details | - | object | 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 examplecurl -X POST \ https://demo.bank131.ru/api/v1/session/init/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok session | - | object | Session details error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 (bank account) amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 participant_details | + | object | Sender's details fiscalization_details | - | object | 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 examplecurl -X POST \ https://demo.bank131.ru/api/v2/session/init/payout/rko \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bik": "049205131", "account": "40702810300000000006", "full_name": "Acme", "inn": "1234567890", "kpp": "165801002", "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt" } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "participant_details": { "sender": { "account": "40702810900000000011" } } }' Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok session | - | object | Session details error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } session/multi/create/rko Creates a payment session on Bank 131's side. Payment operations can only be performed within a session. One or more operations can be performed within the session. Use this request if you need to request the data necessary to perform a payout from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details. If you are ready to provide all the data needed to perform the operation in the request, you can use the (session/multi/init/payment/rko) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request. The response contains the parameters of the created session. API v1 API v2 Endpoint /api/v1/session/multi/create/rko Name | Mandatory | Type | Description --- | --- | --- | --- payment_details | - | object | Transaction details payment_method | - | object | Payment details (bank card, bank account, etc.) fiscalization_details | - | object | Fiscalization details. Mandatory for payouts to the self-employed. participant_details | - (mandatory for payouts to bank cards) | object | Transaction participants details (sender and recipient) amount_details | - | object | Amount in kopecks. To send 100 rubles, specify 10000 customer | - | object | Recipient's details in your system metadata | - | * | Any additional details required for the transaction. The details return within responds and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 payout_details | - | object | Payment details (bank card, bank account, etc.) fiscalization_details | - | object | Fiscalization details. Mandatory for payouts to the self-employed. participant_details | - (mandatory for payouts to bank cards) | object | Transaction participants details (sender and recipient) amount_details | - | object | Amount in kopecks. To send 100 rubles, specify 10000 customer | - | object | Recipient's details in your system metadata | - | * | Any additional details required for the transaction. The details return within responds and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "description": "error description", "code": "error code" }, "status": "error" } session/multi/init/payment/rko Creating a session with a simultaneous payout to a bank card This request can be used if you are ready to pass all the parameters needed for the payout right away. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. API v1 API v2 Endpoint /api/v1/session/multi/init/payment/rko Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_details | + | object | Transaction details payment_method | + | object | Payment details (bank card, bank account, etc.) customer | + | object | Recipient's details in your system amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details. Mandatory for payouts to the self-employed. participant_details | - (mandatory when making a payout to a bank card) | object | Transaction participants details (sender and recipient) metadata | - | * | Any additional details required for the transaction. The details return within responds and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 payout_details | + | object | Payment details (bank card, bank account, etc.) customer | + | object | Recipient's details in your system amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details. Mandatory for payouts to the self-employed. participant_details | - (mandatory when making a payout to a bank card) | object | Transaction participants details (sender and recipient) metadata | - | * | Any additional details required for the transaction. The details return within responds and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "description": "error description", "code": "error code" }, "status": "error" } session/multi/start/payment/rko Starting a payout to a bank card This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Either, you can change pieces of data that have already been passed. If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request. API v1 API v2 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 payment_method | + | object | Payment details (bank card, bank account, etc.) customer | + | object | Recipient's details in your system amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details. Mandatory for payouts to the self-employed. participant_details | - (mandatory when making a payout to a bank card) | object | Transaction participants details (sender and recipient) metadata | - | * | Any additional details required for the transaction. The details return within responds and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "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 payout_details | + | object | Payment details (bank card, bank account, etc.) customer | + | object | Recipient's details in your system amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 fiscalization_details | - | object | Fiscalization details. Mandatory for payouts to the self-employed. participant_details | - (mandatory when making a payout to a bank card) | object | Transaction participants details (sender and recipient) metadata | - | * | Any additional details required for the transaction. The details return within responds and webhooksRequest examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" } } }] } } { "error": { "description": "error description", "code": "error code" }, "status": "error" } session/start/payout/rko Starting a payout to a bank account This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed. If you are using the widget for getting the user's tokenized bank account details, you can pass them using this request. API v1 API v2 Endpoint /api/v1/session/start/payout/rko Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Payment session identifier payment_method | + | object | Payment details (bank account) amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 participant_details | + | object | Sender's details fiscalization_details | - | object | 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 examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "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 (bank account) amount_details | + | object | Amount in kopecks. To send 100 rubles, specify 10000 participant_details | + | object | Sender's details fiscalization_details | - | object | 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 examplecurl -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 error | - | object | ErrorResponse examplesSuccessful response example Unsuccessful response example { "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" }] } } { "status": "error", "error": { "description": "error description", "code": "error code" } } Money transfers calculate This method is used to calculate currency exchange rates for money transfers. There are two ways to calculate the currency exchange rate for a money transfer: Direct rate: specify the amount to be sent in rubles and calculate the amount to be received in the target currency. Inverse rate: specify the amount to be received in the target currency and calculate the amount to be sent in rubles. Endpoint /api/v1/calculate Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- amounts | + | object | Exchange amount and currency source | + | object | Amount and currency to write off of the sender 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 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 examplesDirect rate, from RUB to TRY Inverse rate, from UZS to RUB 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" } } }' 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 source | + | object | Amount and currency to write off of the sender 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 amount | + | number | Calculated amount to be received currency | + | string | ISO 4217 currency code. Case insensitive transfer_fee | + | object | Sender's fee for money transfer 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 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 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 source | + | object | Amount and currency to write off of the sender (passed in the request) 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) 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 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 error | - | object | Error Response examplesDirect rate, from RUB to TRY Inverse rate, from UZS to RUB Unsuccessful response example { "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 } } } { "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 } } } { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } session/multi/init This method is designed to initiate a cross-border transfer. Endpoint /api/v2/session/multi/init Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- payment_list | + | array | List of outgoing transactions from the sender amount_details | + | object | Payout amount details. 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 | + | 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 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 email | - | string | Sender's email phone | + | object | Sender's phone number details 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 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 type | + | string | Type of payment method. Possible values:- card -- bank card- recurrent -- transaction with previously saved card details card | - | object | Bank card details для type = card recurrent | - | object | Bank card token data для type = recurrent payout_list | + | array | List of incoming transactions to the recipient amount_details | + | object | Payout 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 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 email | - | string | Recipient's email phone | + | object | Recipient's phone number details 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 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 for type = card bank_account | - | object | IBAN for type = bank_account tokenized_card | - | object | Bank card token data for type = tokenized_card moneysend | - | object | Pass the object for cash transfers, always empty: {} Request examplesTransfer from a bank card to a bank card in Tajikistan Transfer from a bank card to IBAN in Turkey 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" } } } }] }' 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 error | - | object | Error Response examplesTransfer from a bank card to a bank card in Tajikistan Transfer from a bank card to IBAN in Turkey Unsuccessful response example { "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 } }] } } { "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 } }] } } { "status": "error", "error": { "description": "Invalid request", "code": "invalid_request" } } Other methods sberpay/push Method to send PUSH/SMS notifications to customers for SberPay transactions. Endpoint /api/v1/sberpay/push Request parameters Name | Mandatory | Type | Description --- | --- | --- | --- session_id | + | string | Session ID phone | + | string | Phone number to send PUSH or SMS Request examplecurl -X GET \ https://proxy.bank131.ru/api/v1/sberpay/push \ -H 'Content-Type: application/json' \ -H 'X-PARTNER-PROJECT: your_project_name' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "session_id": "ps_75459435", "phone": "+79638594ххх" }' Response parameters Name | Mandatory | Type | Description --- | --- | --- | --- status | + | string | Status. Possible values: error, ok error | - | object | Error description Response examplesSuccessful response example Unsuccessful response example { "status": "ok" } { "status": "error", "error": { "description": "Internal error", "code": "internal_error" } } Was this helpful? Performing operationsrecurrent/disable session/cancel session/capture session/confirm session/create session/init/payment session/init/payment/sync session/init/payout session/init/payout/fiscalization session/refund session/start/payment session/start/payout session/start/payout/fiscalization token tokenize tokenize/elements Informationfps/banks fps/customer_verification report/account_balance report/account_statement session/status token/info wallet/balance Self-employed peoplenpd/accruals and npd/request/status npd/notifications/count and npd/request/status npd/notifications/mark_as_delivered and npd/request/status npd/notifications/read and npd/request/status npd/notifications/update and npd/request/status npd/taxpayer/account_status and npd/request/status npd/taxpayer/check_personal_info and npd/request/status Escrow accountsession/create/nominal session/init/payout/nominal session/multi/create/nominal session/multi/init/payment/nominal session/multi/start/payment/nominal session/start/payout/nominal Settlement accountsession/create/rko session/init/payout/rko session/multi/create/rko session/multi/init/payment/rko session/multi/start/payment/rko session/start/payout/rko Money transferscalculate session/multi/init Other methodssberpay/push --- - [Webhooks](https://developer.131.ru/en/reference/webhooks): Webhook event reference -- action_required, ready_to_confirm, ready_to_capture, payment_finished, payment_refunded, confirmation_payout, nominal_topup 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 request each time to understand your next step and the operation result. How to get webhooks In your system, create an address to receive webhooks at. Inform your Bank 131 manager of this address. IP addresses our webhooks arrive from: 84.201.171.246 and 84.252.136.174. What to send in response Bank 131 waits for you to send the 200 HTTP code in response to any webhook. If the Bank receives a 4** or 5** code, it will retry the request with increasing intervals. Here is how it works: The interval between retries increases progressively, but never exceeds 15 minutes. After 30 minutes, the Bank will stop sending the webhook. :::warning IMPORTANT! Additional fields may be added to the webhook payload over time, depending on the payment methods used. Make sure that your service can handle them without failure. ::: action_required The Bank is waiting for you or your users to take the necessary action The Bank sends this webhook to you when you or your users need to carry out certain actions to proceed with the operation. For example, a user might need to go through 3D Secure authentication when paying via bank card. The maximum waiting time for an action is 60 minutes. If the action does not occur within this time, the operation will automatically be completed with the canceled status. Webhook parameters Name | Mandatory | Type | Description --- | --- | --- | --- type | + | string | Webhook type: action_required session | + | object | Payment session ExampleAPI v1 API v2 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": "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" } }] } }' curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "action_required", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_131", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user@131.ru" }, "payment_details": { "type": "card", "card": { "brand": "visa", "last4": "8801", "bin": "220220", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 15000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "customer_interaction": { "type": "redirect", "redirect": { "url": "https://bank131.ru?foo=bar", "base_url": "https://bank131.ru", "method": "POST", "qs": { "foo": "bar" }, "params": { "PaReq": "sdfew^//asdhbv", "MD": "abc75daefnn" } } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' 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 Examplecurl -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 Examplecurl -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 ExamplesAPI v1 API v2 Payout Payment curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_method": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "acquiring_payments": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' Payout Payment curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payout_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payout_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_finished", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "po_2018", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "bank_account", "bank_account": { "system_type": "ru", "ru": { "bic": "*******02", "account": "****************5734", "full_name": "***", "description": "*****", "is_fast": false } } }, "amount_details": { "amount": 10000, "currency": "rub" }, "amounts": { "fee": { "merchant_fee": { "amount": 10, "currency": "RUB" } } }, "fiscalization_details": { "professional_income_taxpayer": { "services": [{ "name": "****", "amount_details": { "amount": "10000", "currency": "rub" }, "quantity": 1 }], "tax_reference": "*********628", "receipt": { "id": "**********", "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print" }, "payer_type": "foreign", "payer_name": "******" } }, "transaction_info": { "rrn": "425307614918", "auth_code": "057441" } }] } }' payment_refunded Bank 131 informs you of the result of a refund Bank 131 will send you this webhook after a refund is performed. The notification parameters contain information about the payment session, including all the information about the refunds. The webhook is sent in the following cases: you made a refund using the session/refund method the recipient's bank returned your payment sent to a Russian bank account 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 ExampleAPI v1 API v2 Payout Payment 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", "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_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" } }] }] } }' 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", "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" } }] }] } }' Payout Payment 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", "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" }, "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" } }] }] } }' curl - X POST\ https: //partner.ru \ -H 'Content-Type: application/json'\ - -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "payment_refunded", "session": { "id": "ps_3230", "status": "accepted", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "payment_list": [{ "id": "pm_2705", "status": "succeeded", "created_at": "2018-05-27T02:03:00.000000Z", "finished_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "lucky" }, "payment_details": { "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, 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) request. To cancel the payment, send a (session/cancel) request. Webhook parameters Name | Mandatory | Type | Description --- | --- | --- | --- type | + | string | Webhook type: ready_to_capture session | + | object | Payment session ExampleAPI v1 API v2 curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_capture", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "capture", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "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" }] } }' 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", "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "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) to Bank 131. If something is not right, cancel the operation by sending a (session/cancel) 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 confirm_information | - (mandatory for transactions with an escrow account and money transfers) | object | Transaction confirmation information ExamplesAPI v1 API v2 Payout Payment 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", "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", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", "acquiring_payments": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' Payout Payment 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", "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", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' curl -X POST \ https://partner.ru \ -H 'content-type: application/json' \ -H 'X-PARTNER-SIGN: signature' \ -d '{ "type": "ready_to_confirm", "session": { "id": "ps_3230", "status": "in_progress", "created_at": "2018-05-27T02:03:00.000000Z", "updated_at": "2018-05-27T02:03:00.000000Z", "next_action": "confirm", "payment_list": [{ "id": "pm_2018", "status": "pending", "created_at": "2018-05-27T02:03:00.000000Z", "customer": { "reference": "user123", "contacts": [{ "email": "user@gmail.com" }] }, "payment_details": { "type": "card", "card": { "last4": "4242", "brand": "visa", "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc" } }, "amount_details": { "amount": 10000, "currency": "rub" }, "metadata": "good" }] } }' Was this helpful? action_required confirmation_payout nominal_topup payment_finished payment_refunded ready_to_capture ready_to_confirm --- - [Error Codes](https://developer.131.ru/en/reference/errors): Complete error code reference with descriptions, causes, and recovery actions for all API methods 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 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 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 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, escrow, or collateral account 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) 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 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. 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 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 Was this helpful? --- ## Dashboard - [Dashboard Intro](https://developer.131.ru/en/dashboard/dashboard-intro): Transaction monitoring, analytics, and reporting in a single-window view 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 and the details of any transaction search for transactions using the date filter search for transactions using AI download transaction reports in CSV format Transaction registry The transaction registry allows you to track the complete history of fund movements, including payments, payouts, and refunds. This tool enables you to monitor financial flows without having to contact your manager. The registry displays transaction statuses and key details, allowing you to quickly analyze both successful and unsuccessful transactions. Transaction details Click any row in the registry to open a panel with the details of a specific transaction. The details include the following data: Session ID Transaction ID Transaction type: payment, payout, refund Method: SBP, bank card--other methods will be supported soon Amount: transaction amount Status: transaction status (succeeded, failed, pending, in_progress) Date and time of the transaction creation Partner: your company name Fee: amount withheld by the Bank for transaction processing Antifraud: service comment (Passed, Failed) Date filter At the top of the transaction registry panel, you will find a period filter. You can select: All time: from the start of using the service (this option is selected by default) Preset periods: 7 days, 30 days, 90 days Custom period: any arbitrary start and end dates AI-powered search In addition to filters, you can use our AI search. Simply enter a query in the search bar--the neural network will instantly analyze the data array and return the most relevant result. AI search understands natural language queries. For example, you can enter "Show all payments via Mir card for November 25" or "Transactions over 5 thousand rubles"--the service will show an exact result, saving your time. How to get access To get access to the Dashboard, contact your personal manager at Bank 131. How to log in: 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). Follow the link in the email. Upon first login, change the temporary password to a permanent one and complete two-factor authentication. Development roadmap An analytics dashboard will soon appear in the Dashboard. We plan to add approved transaction charts, conversion reports broken down by payment method, and widgets for monitoring refunds. Additionally, it will become possible to assign roles to service users. Each role contains a specific set of capabilities for convenient collaboration. Stay tuned for updates. Was this helpful? Key benefits for your business Core featuresTransaction registry Transaction details Date filter AI-powered search How to get access Development roadmap --- ## Service Documents - [Legal Documents](https://developer.131.ru/en/documents/landing-legal): Service agreements, restricted business list, and legal documentation Here you will find all the documents required for opening accounts, connecting to remote banking services, and using other services provided by Bank 131. Legal entities and individual entrepreneurs: Online banking and EDM -- documents for using online banking, instructions, and other documents Cash and settlement services -- applications for opening accounts, tariffs, and other documents for maintaining settlement accounts Acquiring -- documents required for accepting payments from individuals Payouts -- documents required for making payouts to individuals' bank cards Special accounts -- documents related to special bank accounts Credit institutions: Correspondent accounts -- documents and tariffs for correspondent accounts dengi.ru payment system -- documents required for participating in the dengi.ru payment system Electronic money transfers -- documents required for carrying out electronic money transfers Was this helpful? ---