---
name: bank131-authentication
description: Use when the user asks how to sign requests to the Bank 131 API: request signature, RSA/SHA-256, ECDSA, Base64, public and private keys, PEM, openssl, required headers (X-PARTNER-PROJECT, X-PARTNER-SIGN, X-PARTNER-SUBMERCHANT, X-PARTNER-IDEMPOTENCY-KEY), idempotency, and verifying Bank 131 webhook signatures.
---

### Required request headers

Each request must include the project identifier and the request signature. This allows the Bank to identify you and verify that the request originated from you.

| Header | Required | Description |
|--------|----------|-------------|
| `X-PARTNER-PROJECT` | + | Project identifier. Given to you by your Bank 131 manager |
| `X-PARTNER-SIGN` | + | Request signature |
| `X-PARTNER-SUBMERCHANT` | - (mandatory for financial institutions that are non-residents of the Russian Federation) | Payer's identifier (for legal entities) |
| `X-PARTNER-IDEMPOTENCY-KEY` | - | Idempotency key (from 4 to 64 characters) |

Request example with authentication:

```json
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
  }'
```

### Creating a request signature

- The signature verifies that a request originated from you and was not modified in transit.
- Two keys are needed: a public key (shared with the Bank) and a private key (stored securely on your side and never disclosed).
- Generate the keys using the RSA algorithm.
- The entire request body must be signed exactly as it is sent to the Bank (the full text in JSON format).
- The signature is generated using the SHA-256 encryption method, then encoded into Base64 and sent in the `X-PARTNER-SIGN` header.

openssl example:

```openssl
# 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

# 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
```

PHP example:

```php
$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);
```

### Verifying Bank 131 requests and webhooks

- All outgoing requests and webhooks from Bank 131 are signed using its secret key.
- To verify them, use the Bank's public key and the SHA-256 algorithm; the signature is transmitted in Base64.
- Save the Bank's public key in the PEM format (separately for live and for demo testing).
- Under normal circumstances, the Bank's public key does not change. If it does, the Bank notifies partners in advance and provides the new key.

### Idempotency key

- The idempotency key prevents the same operation from being executed multiple times (for example, when a request is resent after a network failure).
- You generate the key yourself and send it with the request. The Bank stores it and, if a request with the same key arrives within 24 hours, recognizes it as a duplicate and does not perform the operation again.
- The key is sent in the `X-PARTNER-IDEMPOTENCY-KEY` header (from 4 to 64 characters).

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`

Common errors 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

### Notes and limitations

- Requests can only be signed using the RSA/SHA-256 algorithm. ECDSA and other algorithms are not supported.
- The API has no rate limits on the number of requests per second or minute.