API interaction

Endpoint

How to set this out

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

For the version number, only the major part (before the point) is used. You can check the current version in the Version history or on the pages of the relevant API components.

For example, if the payouts version is 1.8, the address for sending a request for a test payment will look like this:

https://demo.bank131.ru/api/v1/session/init/payout

Server address

For demo testing: https://demo.bank131.ru
For live testing: https://proxy.bank131.ru

Request format

All the data in requests to Bank 131 and notifications from Bank 131 are transmitted with the use of the GET/POST method over HTTP. Message parameters are packed into a JSON object.

Authentication

In the headers of your requests to the Bank, you need to pass the data for authentication: your project's identifier and the requests' signature.

Headers

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

The signature is needed to verify the authenticity and integrity of requests. Bank 131 verifies that the requests received are in fact from you (and are complete); you verify the Bank's notifications the same way.

To create and verify the signature, you will need the secret and public key. Your public key is specified in the Application for recognition and verification of electronic signature key. Using the key, Bank 131 will verify signatures of your incoming payments.

Key pair generation

You need to generate a pair of keys on your side using the RSA signature algorithm.

Creating request body signature

The signature must be transmitted together with the request to Bank 131. You need to sign the request body as a whole, in the form in which it is sent to the Bank's server (after serializing the request body into JSON to send it over HTTP).

Use your secret key for signing the request. Create the signature using the SHA-256 algorithm. The resulting signature must then be transmitted in Base64 format.

Verifying incoming requests from Bank 131

All outgoing requests from Bank 131 are signed using the Bank's own secret key.

Using Bank 131's public key, you need to verify the signatures of the requests coming from the bank on your side. The algorithm used is SHA-256. The signature is transmitted in Base64 format.

Bank 131's public key

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 request identifier. You can generate it and use it to ensure that no request with the same unique identifier is attempted more than once. For example, this way you can avoid duplicate payments and payouts.

The idempotency key lifetime is 24 hours.

Format

Specify the idempotency key 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

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

See more about the Errors

API libraries

Libraries that you may use to integrate with the Bank 131 API.

PHP SDK

Endpoint​

How to set this out​

Server address​

Request format​

Authentication​

Headers​

Request signature​

Key pair generation​

Creating request body signature​

Verifying incoming requests from Bank 131​

Bank 131's public key​

Idempotency key​

Format​

API libraries​