---
name: bank131-connection
description: Use when the user asks how to connect to the Bank 131 API: test (demo/sandbox) environment, production, base URLs, project keys, request signing, and TLS certificates.
---

### Base URLs

- Demo testing: `https://demo.bank131.ru`
- Live transactions: `https://proxy.bank131.ru`

### Endpoint format

Endpoint: `/api/v{API version number}`

Examples:

- API v1: `https://demo.bank131.ru/api/v1/session/init/payout`
- API v2: `https://demo.bank131.ru/api/v2/session/init/payout`

Currently, two API versions are supported for certain methods. Object names may vary by version: for example, `payment_method` (v1) vs `payout_details` (v2). Backward compatibility is maintained—API updates do not break existing integrations.

### Required headers

| Header | Required | Description |
|--------|----------|-------------|
| `X-PARTNER-PROJECT` | + | Project identifier, provided 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
  }'
```

### Request signature

- Two keys are required: 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 and then encoded into Base64 before being sent in the `X-PARTNER-SIGN` header.
- All outgoing requests and webhooks from Bank 131 are signed using its secret key. Verify them with 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.
- Requests can only be signed using the RSA/SHA-256 algorithm. ECDSA and other algorithms are not supported.

### Trusted certificates (TLS)

- To connect to Bank 131 services over a secure TLS channel, your system must trust the Russian certificate authorities. Otherwise certificate chain validation fails (`certificate verify failed`, `SSL handshake failed`, etc.).
- Install two certificates from the Russian Ministry of Digital Development (Russian Trusted CA): **Russian Trusted Root CA** (root) and **Russian Trusted Sub CA** (intermediate).
- Download them from the Gosuslugi portal: `https://www.gosuslugi.ru/crt`, then install into the trusted root store of your OS or application.

### Do testing (without real data)

1. Submit an API integration request on Bank 131's website. A Bank 131 manager will contact you, help you gain access, and answer your questions.
2. Issue a secret key and a public key (intended for test requests only; real operations require different keys).
3. Share your public key with the Bank and get the Bank's public key.
4. If you want to get webhooks, provide your account manager with a URL at which you would like to receive them.

After these steps you will receive a test project identifier—a unique code assigned by the Bank to your business for API authentication. It is required for all requests. Your business can create as many projects as needed—there are no limits.

### Go live

Before starting to work with live data, ensure that all operations in the test mode are completed without errors.

1. Complete your legal entity KYC procedure with Bank 131 and sign an agreement.
2. Open and top up the required accounts:
   - a settlement account—for payouts and payments, including via the Faster Payments System (FPS);
   - an escrow account—for intermediary payments made on behalf of other parties, including via the Faster Payments System (FPS);
   - a collateral account—for payouts and payments, except for the Faster Payments System (FPS).
3. Issue a secret key and a public key for operations with real data.
4. Share your public key with the Bank and get the Bank's public key.
5. Join the Electronic Document Workflow and specify your public key in the Certificate of recognition of the electronic signature verification key.

After everything is set up, you will get a project identifier for performing live transactions.

### Libraries

- PHP SDK: `https://github.com/bank131/php-sdk`.
- Native SDKs for iOS and Android are not provided.

### Important notes

- All organizations that process, transmit, or store payment card data (as well as those that are able to impact card data security) are required to comply with the Payment Card Industry Data Security Standard (PCI DSS). Using the Bank 131 widget reduces the number of applicable requirements.
- Bank 131 notifies about planned technical works and maintenance windows via email to the address specified in the contract or when registering a project.