API request format

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.

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

Endpoint

How to set this out

<server address> + /api/v{API version number} + <address for sending the necessary method requests>

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:

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

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.

API version​

Endpoint​

How to set this out​

Server address​

API authentication​

Request signature​

Creating request body signature​

Verifying incoming requests from Bank 131​

Idempotency key​

Errors​

Libraries​