Documentation

Documentation

  • Bank 131 API
  • Languages iconEnglish
    • Русский

›Introduction to API

131 Documentation

  • API features
  • Where to begin

Introduction to API

  • Interaction
  • API libraries
  • Testing
  • Version history

How Payouts Work

  • Features
  • How it all works
  • Main payout scenario
  • Payout refunds
  • The Self-employed

    • Payouts to the self-employed
    • Linking the self-employed
    • Fiscalization

    Payout Methods

    • To a Russian bank card
    • To a Russian bank account
    • To a QIWI Wallet
    • To a YooMoney (Yandex.Money)
    • To the Russian Federal Tax Agency
    • Via FPS by a phone number

    Payout Scenarios

    • Payout to a card via widget
    • Payout from a nominal account to a bank card
    • Single-request payout
    • Payout to a card with PCI DSS
    • Payout to a self-employed person with fiscal receipt

How Payments Work

  • Features
  • Payment process
  • Payments via bank card
  • Payments with later capture
  • Refunds
  • Recurring payments
  • Payments via FPS by QR code
  • Payments via Telegram

    • How to create your Telegram bot
    • How to connect your Telegram bot
    • How to setup your Telegram bot

    Split Payments

    • Features and options
    • Split payments out of the box
    • Split payments using API

    Payment Scenarios

    • Paying via payment form
    • Paying with PCI DSS
    • Single-request payment

Widgets

  • Widget to get card details
  • Payment form widget
  • Widget for linking a self-employed person to the Bank

Passport Verification

  • Features
  • Interaction
  • Methods

    • Verification request
    • Verification status
  • Response and errors

Reports

  • Payouts report
  • Payments report
  • Monthly report

API Reference

  • Objects
  • Methods
  • Webhooks
  • Error codes

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

NameMandatoryTypeDescription
X-PARTNER-PROJECT+stringProject identifier. Given to you by your Bank 131 manager
X-PARTNER-SIGN+stringRequest signature (see below)
X-PARTNER-SUBMERCHANT- (mandatory for the financial institutions that are non-residents of the Russian Federation)stringPayer'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:

  • for live testing
  • for demo testing

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);

Bank 131's public key for live testing

Download the public key

← Where to beginAPI libraries →
  • Endpoint
  • Request format
  • Authentication
    • Request signature
    • Signature generation and validation examples
  • Bank 131's public key for live testing
Documentation
Documentation
PayoutsPaymentsAPI ReferenceService documents
Step by step
Payout to a card via widgetPayout to a card with PCI DSSPayout to the self-employed Paying via payment form
Get in touch
Ideas and partnerships — partners@131.ruMedia — press@131.ru
© 2023 Bank 131