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 mass 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 using the HTTP POST method. 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 (see below) |
| X-PARTNER-SUBMERCHANT | - (mandatory for the 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: sign' \
-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
# 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);