Methods

When processing requests, the system checks for valid input parameters, the presence of the necessary headers, and rights to perform operations.

Performing operations

`fiscalization`

Fiscalization without payment

This request can be used to register the payment to the self-employed with the Federal Tax Agency and get a link to the receipt. The payment itself does not need to be paid (this can be done before or after, by any method).

To send a request for fiscalization, you first need to create a payment session and obtain a session ID (session_id).

Endpoint

/api/v1/fiscalization

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
fiscalization_details	+	object	Fiscalization details
payment_method	-	object	Payout details (card, customer account, etc.)
amount_details	-	object	The amount
participant_details	-	object	Information on payout participants
customer	-	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL

curl -X POST \
https://demo.bank131.ru/api/v1/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_2704",
  "fiscalization_details": {
    "professional_income_taxpayer": {
      "tax_reference": "123456789012",
      "payer_type": "legal",
      "payer_tax_number": "3316004777",
      "payer_name": "OOO Vector",
      "services": [
        {
          "name": "Goods delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        },
        {
          "name": "Component delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        }
      ]
    }
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Successful response example

{
  "status": "ok",
  "session": {
    "id": "ps_2704",
    "status": "in_progress",
    "created_at": "2021-05-27T08:13:33.736384Z",
    "updated_at": "2021-05-27T08:13:33.871729Z",
    "payments": [
      {
        "id": "po_2705",
        "status": "in_progress",
        "created_at": "2021-05-27T08:13:33.860754Z",
        "amount_details": {
          "amount": 15000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "services": [
              {
                "name": "Goods delivery",
                "amount_details": {
                  "amount": 5000,
                  "currency": "rub"
                },
                "quantity": 2
              },
              {
                "name": "Component delivery",
                "amount_details": {
                  "amount": 5000,
                  "currency": "rub"
                },
                "quantity": 1
              }
            ],
            "tax_reference": "123456789012",
            "payer_type": "legal",
            "payer_tax_number": "3316004777",
            "payer_name": "ООО Vector"
          }
        }
      }
    ]
  }
}

`recurrent/disable`

Disable token for recurring payments

You can disable a token with this request. Send the token in the request, in the response you will get is_active: false. This means you cannot perform recurring payments with this token.

After the token has disabled, the token expiration setting finished_at may contain a weird date of the year 2000. This value won't affect anything, so please disregard it.

Endpoint

/api/v1/recurrent/disable

Request parameters

Name	Mandatory	Type	Description
recurrent	+	object	Object with a token

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/recurrent/disable \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "recurrent": {
    "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427"
  }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->disableRecurrentRequestBuilder()
    ->setRecurrentToken('e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39')
    ->build();

$response =  $client->recurrent()->disable($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
recurrent	+	object	Object with a token

Response example

{
  "recurrent": {
    "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427",
    "created_at": "2020-07-14T13:17:11+03:00",
    "finished_at": "2020-07-31T16:05:42+03:00",
    "is_active": false
  },
  "status": "ok"
}

`session/cancel`

Operation cancellation

This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a ready_to_confirm or a ready_to_capture webhook.

If you do not want to perform the operation, you can cancel it by sending a session/cancel.

If everything looks good, send a request to confirm the operation (session/confirm) or a request to debit the amount being put on hold (session/capture).

Endpoint

/api/v1/session/cancel

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session identifier

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/cancel \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$response = $client->session()->cancel('session_id');

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

`session/capture`

Debiting amounts put on hold

This request can be used if you are sending delayed capture payments. These payments are performed in two stages: first, the money is put on hold (for example, on the user's bank card), and then it is debited in response to your request.

The request can be sent when Bank 131 is ready to debit the money and has sent you a ready_to_capture webhook.

If you want to debit the amount put on hold, send a session/capture. You can debit the full amount on hold, or a portion of it.

To cancel the debit, send a (session/cancel).

Endpoint

/api/v1/session/capture

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Bank 131 session identifier
amount_details	-	object	The amount to be debited. Can be less than the amount on hold, but greater than 0. If not specified, the full amount of the payment will be debited

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/capture \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$response = $client->session()->capture('session_id');

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

`session/confirm`

Operation confirmation

This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a ready_to_confirm webhook.

You'll need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a session/confirm to Bank 131. If something is not right, cancel the operation by sending a (session/cancel) to Bank 131.

Endpoint

/api/v1/session/confirm

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session identifier
confirm_information	- (mandatory for the transactions with an escrow account or when `requier_confirm_information = true`)	object	Transaction confirmation information

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/confirm \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$response = $client->session()->confirm('session_id');

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

`session/create`

Payment session creation

Creates a payment session on Bank 131's side.

Payment operations can only be performed within a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund, or a payment which is subsequently split).

Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details.

If you are ready to provide all the data needed to perform the operation in the request, you can use the method whereby the payout (session/start/payout) or the payment (session/start/payment) starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint

/api/v1/session/create

Request parameters

Name	Mandatory	Type	Description
payment_method	-	object	Payment details (card, customer account, etc.)
payment_details	-	object	Transfer details
amount_details	-	object	The amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
fiscalization_details	-	object	Fiscalization details; only for payouts to the self-employed
participant_details	-	object	Information about the participants (the sender and the recipient)
customer	Mandatory for payments	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

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 '{
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "order123"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->createPaymentSession()  //OR ->createPayoutSession()
    ->setAmount(10000, 'rub')
    ->setMetadata('order123')
    ->build();

$response = $client->session()->create($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

`session/init/payment`

Session creation with simultaneous payout initiation

Can be used if you are ready to pass all the parameters needed for the payment at once, e.g. when paying with a bank card if you have PCI DSS.

The response contains the parameters of the session created and an object with information about the payment (acquiring_payments).

Request parameters

Name	Mandatory	Type	Description
payment_details	+	object	Payment data
amount_details	+	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
participant_details	-	object	Participants information
customer	+	object	Client data in your system
payment_options	-	object	Additional payment parameters
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "05",
        "expiration_year": "22",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  },
  "payment_options": {
    "return_url": "https://131.ru"
  }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$paymentOptions = new PaymentOptions();
$paymentOptions->setReturnUrl('http://bank131.ru');

$request = RequestBuilderFactory::create()
    ->initPaymentSession()
    ->setCard(new BankCard('4242424242424242', '05', '22', '123'))
    ->setAmount(10000, 'rub')
    ->setCustomer(new Customer('lucky'))
    ->setPaymentOptions($paymentOptions)
    ->build();

$response = $client->session()->initPayout($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_203",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "payment_options": {
          "return_url": "https://131.ru"
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

`session/init/payment/sync`

Please be aware that we do not recommend implementing this method unless you have already used it before.

One-request payment

This method allows sending a payment request and getting a response right away. Use it if you are ready to submit all payment parameters in this request. e.g. when paying with a bank card if you have PCI DSS.

The response contains the parameters of the session created and the acquiring_payments object with the payment result and information.

Request parameters

Only required request parameters are listed here. You can find additional parameters by following the links in object descriptions.

Name	Mandatory	Type	Description
payment_details	+	object	Payment data
type	+	string	Payment method type. Possible values: `card`
card	+	object	Object containing bank card details
type	+	string	Method of card information transmission. Value: `bank_card`
bank_card	+	object	Object with open card information
number	+	string	Card number
expiration_month	+	string	Month of card expiration, `MM`. Example: `01`
expiration_year	+	string	Year of card expiration, `YY`. Example: `22`
security_code	+	string	CVC/CVV code
amount_details	+	object	Payment amount
amount	+	int	The amount in ruble decimal format. The value must be greater than zero. To pay 100 rubles, specify `10000`
currency	+	string	The ISO 4217 currency code. Case insensitive. Always: `rub`
participant_details	-	object	Participants information
customer	+	object	Information about payment sender on your side
reference	+	string	Payment sender ID in your system
payment_options	+	object	Additional payment parameters
return_url	+	string	The URL to which the user is redirected after the payment has been performed. The URL must be valid
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL

curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payment/sync \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "01",
        "expiration_year": "22",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  },
  "payment_options": {
    "return_url": "https://131.ru"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "accepted",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_203",
        "status": "succeeded",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "payment_options": {
          "return_url": "https://131.ru"
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

`session/init/payout`

Session creation with simultaneous payout initiation

This request can be used if you are ready to pass all the parameters needed for the payout at once, for example when transferring a payout to a Russian bank account. For payouts to bank cards, this is only possible if you have PCI DSS.

The response contains the parameters of the session created and an object with the information about the payout (Payment).

Endpoint

/api/v1/session/init/payout

Request parameters

Name	Mandatory	Type	Description
payment_method	+	object	Payment details (card, customer account, etc.)
amount_details	+	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
fiscalization_details	-	object	Fiscalization details
participant_details	-	object	Information about the participants (the sender and the recipient)
customer	-	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->initPayoutSession()
    ->setCard(new BankCard('4242424242424242'))
    ->setAmount(1000, 'rub')
    ->build();

$response = $client->session()->initPayout($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Successful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

`session/init/payout/fiscalization`

Session creation and payout start, with additional check that all the fiscalization data has been provided

Can be used for payouts to self-employed people if you are ready to provide all the information about the self-employed person and the details necessary to create the payout at once, for example when transferring a payout to a Russian bank account. For payouts to bank cards, this is only possible if you have PCI DSS.

The response contains the parameters of the session created and an object with the information about the payout (Payment) with the data necessary to send the receipt.

Endpoint

/api/v1/session/init/payout/fiscalization

Name	Mandatory	Type	Description
payment_method	-	object	Payment details (card, customer account, etc.)
amount_details	-	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
fiscalization_details	-	object	Fiscalization details
participant_details	-	object	Information about the participants (the sender and the recipient)
customer	-	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payout/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "fiscalization_details": {
    "professional_income_taxpayer": {
      "tax_reference": "590000000000",
      "payer_type": "legal",
      "payer_tax_number": "3300000000",
      "payer_name": "OOO Vector",
      "services": [
        {
          "name": "Service description",
          "amount_details": {
            "amount": 10000,
            "currency": "rub"
          }
        }
      ]
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "order123",
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;
use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection;
use Bank131\SDK\DTO\FiscalizationService;
use Bank131\SDK\DTO\Participant;
use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer;
use Bank131\SDK\DTO\Amount;


$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$services   = new FiscalizationServiceCollection();
$services[] = new FiscalizationService(
    'Delivery',
    new Amount(5000, 'rub'),
    1
);

$incomeInformation = new ProfessionalIncomeTaxpayer(
    $services,
    '590000000000'
);

$incomeInformation->setPayerName('OOO Vector');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

$recipient = new Participant();
$recipient->setFullName('Ivanov Ivan');

$request = RequestBuilderFactory::create()
    ->initPayoutSessionWithFiscalization()
    ->setIncomeInformation($incomeInformation)
    ->setCard(new BankCard('4242424242424242'))
    ->setAmount(5000, 'rub')
    ->setRecipient($recipient)
    ->setMetadata('good')
    ->build();

$response = $client->session()->initPayoutWithFiscalization($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2909",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "tax_reference": "590000000000",
            "payer_type": "legal",
            "payer_tax_number": "3300000000",
            "payer_name": "OOO Vector",
            "services": [
              {
                "name": "Service description",
                "amount_details": {
                  "amount": 10000,
                  "currency": "rub"
                }
              }
            ]
          }
        },
        "metadata": "order123",
        "participant_details": {
          "recipient": {
            "full_name": "Ivanov Ivan"
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "participant_details.recipient.full_name.not_blank"
  },
  "status": "error"
}

`session/refund`

Refund

You can use this request to return money to the user after a successful payment.

After completing the refund, Bank 131 will send you a payment_refunded webhook.

Endpoint

/api/v1/session/refund

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	The identifier of a successful payment session which needs to be refunded
amount_details	-	object	The amount of the refund. If not specified, the refund will be made for the full amount of the payment
metadata	-	*	Additional information

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/refund \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->refundSession('ps_3230')
    ->build();

$response = $client->session()->refund($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_2705",
        "status": "succeeded",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "finished_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "refunds": [
          {
            "id": "rf_23",
            "status": "in_progress",
            "created_at": "2018-05-27T02:03:00.000000Z",
            "amount_details": {
              "amount": 10000,
              "currency": "rub"
            }
          }
        ]
      }
    ]
  }
}

`session/start/payment`

Payment start

This request can be used to start a payment within an existing session. In the parameters, you can pass the data necessary to perform the payment or change pieces of data that have already been passed.

Endpoint

/api/v1/session/start/payment

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_details	-	object	Payment data
amount_details	-	object	Amount
participant_details	-	object	Information about the participants (the payer and the recipient)
customer	-	object	Payment sender information in your system
payment_options	-	object	Additional payment settings
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/start \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "01",
        "expiration_year": "26",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  },
  "payment_options": {
    "return_url": "https://www.131.ru"
  },
  "metadata": "good"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Card\BankCard;
use Bank131\SDK\DTO\Customer;
use Bank131\SDK\DTO\PaymentOptions;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$paymentOptions = new PaymentOptions();
$paymentOptions->setReturnUrl('return_url');

$request = RequestBuilderFactory::create()
    ->startPaymentSession('session_id')
    ->setCard(
        new BankCard(
            'number',
            'expiration_month',
            'expiration_year',
            'security_code'
        )
    )
    ->setCustomer(
        new Customer('reference')
    )
    ->setPaymentOptions($paymentOptions)
    ->setAmount(10000, 'rub')
    ->setMetadata('good')
    ->build();

$response = $client->session()->startPayment($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2024-08-21T06:21:36.913863Z",
    "updated_at": "2024-08-21T06:21:56.832509Z",
    "acquiring_payments": [
      {
        "id": "pm_3232",
        "status": "in_progress",
        "created_at": "2024-08-21T06:21:56.846204Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa",
            "country_iso3": "RUS"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "payment_options": {
          "return_url": "https://www.131.ru"
        },
        "metadata": "good"
      }
    ]
  }
}

{
  "status": "error",
  "error": {
    "description": "internal error",
    "code": "repository_record_not_found"
  }
}

`session/start/payout`

Payout start

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint

/api/v1/session/start/payout

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_method	-	object	Payout details (card, customer account, etc.)
amount_details	-	object	Amount
participant_details	-	object	Information on payout participants
customer	-	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/start/payout \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->startPayoutSession('session_id')
    ->build();

$response = $client->session()->startPayout($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Successful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

`session/start/payout/fiscalization`

Payout start, with check that all fiscalization data has been provided

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint

/api/v1/session/start/payout/fiscalization

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_method	-	object	Payment details (card, customer account, etc.)
amount_details	-	object	Amount
fiscalization_details	-	object	Fiscalization details
participant_details	-	object	Information on payout participants
customer	-	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "fiscalization_details": {
    "professional_income_taxpayer": {
      "tax_reference": "590000000000",
      "payer_type": "legal",
      "payer_tax_number": "330000000000",
      "payer_name": "OOO Vector",
      "services": [
        {
          "name": "Goods delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        }
      ]
    }
  }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\DTO\Collection\FiscalizationServiceCollection;
use Bank131\SDK\DTO\FiscalizationService;
use Bank131\SDK\DTO\ProfessionalIncomeTaxpayer;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$services   = new FiscalizationServiceCollection();
$services[] = new FiscalizationService(
    'Delivery',
    new Amount(5000, 'rub'),
    1
);

$incomeInformation = new ProfessionalIncomeTaxpayer(
    $services,
    '590000000000'
);

$incomeInformation->setPayerName('OOO Vector');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

$request = RequestBuilderFactory::create()
    ->startPayoutSessionWithFiscalization('3230', $incomeInformation)
    ->build();

$response = $client->session()->create($request);

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Successful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_203",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 5000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "services": [
              {
                "name": "Goods delivery",
                "amount_details": {
                  "amount": 5000,
                  "currency": "rub"
                },
                "quantity": 1
              }
            ],
            "tax_reference": "590613976192",
            "payer_type": "legal",
            "payer_tax_number": "3316004710",
            "payer_name": "ООО Vector"
          }
        }
      }
    ]
  }
}

`token`

Generation of a token to work with widgets

The token is needed to access Bank 131's JavaScript library. You can generate it using this request and use it to work with widgets.

The token is valid for 24 hours. It can be used for a single operation. When sending a request, you should pass the working parameters with widgets that you are going to use with that token.

Endpoint

/api/v1/token

Request parameters

Name	Mandatory	Type	Description
tokenize_widget	-	object	The data required by the tokenization widget
self_employed_widget	-	object	The data required by the self-employed registration widget
acquiring_widget	-	object	The data required by the payment form widget

An example of how to create a token to perform a payout which involves obtaining card details via the widget and linking a self-employed person

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tokenize_widget": {
    "access": true
  },
  "self_employed_widget": {
    "tax_reference": "111111111111"
  }
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$request = RequestBuilderFactory::create()
    ->issuePublicTokenBuilder()
    ->setTokenizeWidget()
    ->setSelfEmployedWidget('111111111111')
    ->setAcquiringWidget(
        'test_ps_id',
        'http://success.url',
        'http://failed.url',
false
    )
    ->build();

$response = $client->widget()->issuePublicToken($request);
$publicToken = $response->getPublicToken();

An example of a request to create a token to perform a payment through a payment form

curl -X POST \
https://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "acquiring_widget": {
    "session_id": "ps_123456"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
public_token	-	string	The public token
error	-	object	[Error
](/en/reference/objects/#error)

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539"
}

{
  "status": "error",
  "error": {
    "description": "acquiring_widget.session_id.not_unique",
    "code": "invalid_request"
  }
}

`token/info`

Receiving information via token

Operations with bank cards are often carried out with tokenized values. For payouts and payments through widgets, a public token is created. A token ca also be created for recurring payments.

For any payment token you can get information:

About the bank card for which that token was created – this will be the hidden card number and payment system.
About the token itself – type of token, time of creation, expiration date, active or inactive at the moment of inquiry.

This method can be used, for example, to learn the hidden card number and show the user which card the funds will be debited from. Or if you need to check the token expiration date.

Endpoint

/api/v1/token/info

Request parameters

Name	Mandatory	Type	Description
type	+	string	Type of request. Options: `card`, `public_token`, `recurrent_token`, `bank_account_ru`
card	- (mandatory for `type = card`)	object	Bank card details
public_token	- (mandatory for `type = public_token`)	object	Token details
recurrent_token	- (mandatory for `type = recurrent_token`)	object	Token details
bank_account_ru	- (mandatory for `type = bank_account_ru`)	object	Bank account details

Information request examples

Card information via token
Public token
Token for recurring payments or payouts
Bank account token

You send tokenized bank card details and receive a hidden card and payment system.

curl -X POST \
https://demo.bank131.ru/api/v1/token/info \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "card",
  "card": {
    "type": "encrypted_card",
    "encrypted_card": {
      "number_hash": "card_number_hash (token)"
    }
  }
}'

You send a public token and receive information about it.

curl -X POST \
https://demo.bank131.ru/api/v1/token/info \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "public_token",
  "public_token": {
    "token": "your_token"
  }
}'

You send a token and receive information about it.

curl -X POST \
https://demo.bank131.ru/api/v1/token/info \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "recurrent_token",
  "recurrent_token": {
    "token": "your_token"
  }
}'

You send a token and receive information about it.

curl -X POST \
https://proxy-stage.bank131.ru/api/v1/token/info \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "bank_account_ru",
  "bank_account_ru": {
    "token": "4371c4633033d3e7f468c8ca5f50f7dd10c00fe8655563c3da759c16b505ba93"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
info	-	object	Information about the token, depending on the type of request (`type`): tokenized bank card, public token, token for recurring payments or payouts, or bank account token
error	-	object	Error

Response examples

Card information via token
Information about a public token
Information about a token for recurring payments or payouts
Information about a bank account token

{
  "status": "ok",
  "info": {
    "number_hash": "card_number_hash",
    "brand": "visa",
    "last4": "4242",
    "type": "card"
  }
}

{
  "status": "ok",
  "info": {
    "token": "your_token",
    "created_at": "2021-03-17T14:10:56+03:00",
    "finished_at": "2021-03-18T14:10:56+03:00",
    "is_active": true,
    "type": "public_token"
  }
}

{
  "status": "ok",
  "info": {
    "token": "your_token",
    "created_at": "2021-03-17T14:19:05+03:00",
    "finished_at": "2021-04-17T14:19:05+03:00",
    "is_active": true,
    "type": "recurrent_token"
  }
}

{
  "status": "ok",
  "info": {
    "masked_account": "40817***9535",
    "created_at": "2024-02-08T17:17:44+03:00",
    "finished_at": "2124-02-08T17:17:44+03:00",
    "type": "bank_account_ru"
  }
}

`tokenize`

This method is used for tokenizing a bank account (payout). Use it to get a token and a masked account number. The token received in the response does not expire.

You can tokenize any account that passes verification against a specified range of accounts. Otherwise, the “Enter a different account number” error will be returned.

Endpoint

/api/v1/tokenize

Request parameters

Name	Mandatory	Type	Description
type	+	string	Bank account type
bank_account_ru	+	object	An object containing Russian bank account details
bik	+	string	Bank BIK
account	+	string	Account number

Request example

curl -X POST \
https://proxy-stage.bank131.ru/api/v1/tokenize \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "bank_account_ru",
  "bank_account_ru": {
    "bik": "044525974",
    "account": "40817810400003869535"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Bank account type
token	-	string	Token
data	-	object	Masked user account data object
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "token": "2c6ebe1368407b922057efee0fed58360dae1d28af50fa6734bb54c61a763c24",
  "data": {
    "masked_account": "40702***0025"
  }
}

{
  "status": "error",
  "error": {
    "description": "The public token is not found",
    "code": "public_token_invalid"
  }
}

`tokenize/elements`

Use this method to get a tokenized card number when you are not allowed to store card details on your side.

This method is only available if you have PCI DSS. To start using this method, please contact your manager in Bank 131.

Endpoint

/api/v1/tokenize/elements

Request parameters

Name	Mandatory	Type	Description
card_elements	+	object	An object with a card number

Request example

curl -X POST \
https://proxy-stage.bank131.ru/api/v1/tokenize/elements \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "card_elements": [
    {
      "ref": "number",
      "type": "card_number",
      "card_number": "4242424242424242"
    }
  ]
}'

Response example

{
  "status": "ok",
  "data": {
    "number": {
      "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919",
      "info": {
        "masked_card_number": "424242******4242",
        "card_network": "visa",
        "card_type": "visa"
      }
    }
  }
}

Information

`fps/banks`

You can use this request to get a list of names and identifiers of banks-recipients of the Faster Payment System.

Endpoint

/api/v1/fps/banks

Request example

cURL
PHP

curl -X GET
https://demo.bank131.ru/api/v1/fps/banks \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{}'

use Bank131\SDK\Client;
$response = $client->fps()->getBanks();

foreach ($response->getBanks() as $bank) {  
echo $bank->getId(), ' ', $bank->getRuName(), ' ', $bank->getEngName(), PHP_EOL;
}

Response example

{
  "banks": [
    {
      "id": "100000000243",
      "eng_name": "National Standard Bank",
      "ru_name": "Национальный стандарт"
    },
    {
      "id": "100000000056",
      "eng_name": "Khlynov",
      "ru_name": "Хлынов"
    },
    ...
  ]
}

`fps/customer_verification`

You can use this request to check whether a recipient is registered in the Faster Payment System (FPS). If the user is found in the FPS, the session will have a successful status, otherwise the session will be canceled. This operation is free of charge and is confirmed automatically (ready_to_confirm is not sent).

Endpoint

/api/v1/fps/customer_verification

Request parameters

Name	Mandatory	Type	Description
payment_method	+	object	Payment details (card, customer account, etc.)
participant_details	+	object	Information about the participants (the sender and the recipient)

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/fps/customer_verification \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "system_type": "faster_payment_system_verification",
      "faster_payment_system_verification": {
        "phone": "79261234567",
        "bank_id": "100000000069"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "first_name": "Иван",
      "last_name": "Иванов",
      "middle_name": "Иванович"
    }
  }
}

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

{
  "status": "ok",
  "session": {
    "id": "ps_109941",
    "status": "in_progress",
    "created_at": "2022-03-01T11:57:31.652396Z",
    "updated_at": "2022-03-01T11:57:31.861329Z",
    "payments": [
      {
        "id": "po_31668",
        "status": "in_progress",
        "created_at": "2022-03-01T11:57:31.895773Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "faster_payment_system_verification",
            "faster_payment_system_verification": {
              "phone": "79261234567",
              "bank_id": "100000000069"
            }
          }
        },
        "participant_details": {
          "recipient": {
            "first_name": "Иван",
            "last_name": "Иванов",
            "middle_name": "Иванович"
          }
        }
      }
    ]
  }
}

`report/account_balance`

Use this method to get your settlement or escrow account balance. More on account balance.

Endpoint

/api/v1/report/account_balance

Request parameters

Name	Mandatory	Type	Description
account_number	+	string	Account number. The account number must start as follows: `40702`, `40703`, `40802`, `40807`, `40701`

Request example

curl -X GET \
https://demo.bank131.ru/api/v1/report/account_balance \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "account_number": "40702810400000000333"
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Options: `error`, `ok`
account_number	-	string	Account number
account_currency	-	string	Account currency according to ISO 4217. Example: `RUB`
balance	-	object	Balance details
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "account_number": "40702810400000000333",
  "account_currency": "RUB",
  "balance": {
    "current_balance": 20900
  }
}

{
  "status": "error",
  "error": {
    "code": "Error code",
    "description": "Error description"
  }
}

`report/account_statement`

Use this method to get bank statements for your settlement or escrow account opened in rubles. Statements can only be generated for a day. To learn more, click here.

Endpoint

/api/v1/report/account_statement

Request parameters

Name	Mandatory	Type	Description
date_from	+	date	Statement start date. Example: 2023-06-01
date_to	+	date	Statement end date. Example: 2023-06-01
account_number	+	string	Account number (20 digits) for which you request a statement

The date_from and date_to values must match.

Request example

curl -X GET \
https://demo.bank131.ru/api/v1/report/account_statement \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
  "date_from": "2023-06-01",
  "date_to": "2023-06-01",
  "account_number": "40702810600200000014"
}

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Options: `error`, `ok`
name	+	string	Method name (`account_statement`)
account_statement	+	object	Statement details
date_from	+	date	Statement start date
date_to	+	date	Statement end date
account_number	+	string	Account number (20 digits) for which the statement is generated
total_turnover	+	object	Information on funds movement
debet	+	int	Total debits over the period covered by the statement
credit	+	int	Total credits over the period covered by the statement
total_balance	+	object	Balance information
opening	+	int	Opening balance on the statement start date
closing	+	int	Closing balance on the statement end date
transactions	+	object	Information on transactions
amount	+	int	Top-up amount (non-negative values only)
base_amount	-	int	Transaction amount in the currency. Should be filled out only for transactions in currencies other than Russian rubles. When using the base currency (RUB), the parameter is optional
currency	+	string	Transaction currency
payment_date	+	date	Transaction date
bank_system_id	+	string	Payment identifier. It is specified for all kinds of payments: - for payments sent via the API - for transfers from another bank - for payments made through online banking
transaction_id	-	string	Transaction identifier. It is specified for payments sent via the API
session_id	-	string	Session identifier. It is specified for payments sent via the API
purpose	+	string	Payment purpose
counter_party	+	object	Counterparty details
kpp	-	string	Counterparty's KPP
inn	-	string	Counterparty's INN
name	+	string	Counterparty's name
account_number	+	string	Counterparty's account number
bank_code	+	string	Counterparty's bank BIK
type	+	string	Transaction type. Possible values: `credit` (for replenishment operations), `debet` (for write-off operations) values

Successful response example

{
  "status": "ok",
  "method": {
    "name": "account_statement",
    "account_statement": {
      "date_from": "2022-11-12T18:19:32.487+0000",
      "date_to": "2022-11-13T18:19:32.487+0000",
      "account_number": "40703810500000000025",
      "total_turnover": {
        "debet": 0,
        "debet_base": null,
        "credit": 100,
        "credit_base": null
      },
      "total_balance": {
        "opening": 0,
        "opening_base": null,
        "closing": 100,
        "closing_base": null
      },
      "transactions": [
        {
          "amount": 10000,
          "base_amount": null,
          "currency": "RUB",
          "payment_date": "2022-11-13",
          "bank_system_id": "2080040097819020",
          "transaction_id": "c7b923ec-844f-4d98-ad02-795d62fe1989",
          "session_id": "ps_3230",
          "purpose": "Account replenishment",
          "counter_party": {
            "kpp": "165501001",
            "inn": "1655415696",
            "name": "Fee for money transfer processing services",
            "account_number": "70606810600004710401",
            "bank_code": "049205131"
          },
          "type": "credit"
        }
      ]
    }
  }
}

Unsuccessful response examples

Invalid dates
Invalid JSON format
Internal error

date_from does not match date_to

{
  "status": "error",
  "error": {
    "description": "Invalid input request parameters:  (max interval is 1 day)",
    "code": "invalid_request"
  }
}

date_from is greater than date_to

{
  "status": "error",
  "error": {
    "description": "Invalid input request parameters:  (date_to must be greater than date_from);  (max interval is 1 day)",
    "code": "invalid_request"
  }
}

Invalid date in date_from

{
  "status": "error",
  "error": {
    "description": "Invalid value in date_from",
    "code": "invalid_request"
  }
}

Invalid date in date_to

{
  "status": "error",
  "error": {
    "description": "Invalid value in date_to",
    "code": "invalid_request"
  }
}

{
  "status": "error",
  "error": {
    "description": "Invalid request",
    "code": "invalid_request"
  }
}

This response is returned in the following cases:

the account number is specified incorrectly
the specified account does not exist
the specified account does not belong to the user who initiated the request

{
  "status": "error",
  "error": {
    "description": "Internal error",
    "code": "internal_error"
  }
}

`session/status`

Obtaining session information

You can send this request if you want to obtain full information about the payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment.

The response contains the payment session with details about all the operations performed during it.

Endpoint

/api/v1/session/status

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/session/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$response = $client->session()->status('session_id');

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Successful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "next_action": "confirm",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa",
            "bin": "220220"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        },
        "metadata": "good"
      }
    ]
  }
}

`wallet/balance`

You can use this request to check your current Bank 131 deposit balance.

note

This method can be used for payouts only. You can find your acquiring balance information in your remote banking service account in the Statements section, provided that compensations are paid to your Bank 131 account.

This is necessary in order to make sure there is enough money on the balance:

for payouts
for returns

If the amount is insufficient, you can top up your deposit.

The request does not return the information about your escrow account balance. You may find this information in your remote banking service account in the Accounts section or use the report/account_balance method.

Endpoint

/api/v1/wallet/balance

Request parameters

Name	Mandatory	Type	Description
request_datetime	+	string	The timestamp of the request in ISO 8601

Request example

cURL
PHP

curl -X POST \
https://demo.bank131.ru/api/v1/wallet/balance  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_datetime": "2019-10-14T19:53:00+03:00"
}'

use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;

$config = new Config(
    'https://demo.bank131.ru',
    'your_project_name',
    file_get_contents('/path/to/your/private_key.pem')
);

$client = new Client($config);

$walletBalanceResponse = $client->wallet()->balance();

$wallets = $walletBalanceResponse->getWallets();

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
wallets	-	object	The list of guarantee payment accounts available at Bank 131
error	-	object	Error

Response example

{
  "status": "ok",
  "wallets": [
    {
      "id": "131",
      "amount_details": {
        "amount": 13100,
        "currency": "rub"
      }
    }
  ]
}

Self-employed people

`check` and `request/status`

Checking the status of a self-employed person

This request allows you to check whether an individual is self-employed or not using their INN.

The requests consists of two parts:

Send a check request, passing the individual's INN in the tax_reference parameter, and wait for a request_id identifier in response.
Send a request/status request with this identifier. The response will tell you whether the INN is registered with the Federal Tax Agency as belonging to a self-employed person and whether it is linked to Bank 131.

The check request should not be sent more than once every 30 seconds.

The endpoint to which the `check` request is sent

/api/v1/npd/check

Request parameters for `check`

Name	Mandatory	Type	Description
tax_reference	+	string	Individual's INN

Request example for check

curl -X POST \
https://demo.bank131.ru/api/v1/npd/check   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference": "123456789012"
}'

Response parameters for `check`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
request_id	+	string	Request identifier

Response example for check

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to which the `request/status` request is sent

/api/v1/npd/request/status

Request parameters for `request/status`

Name	Mandatory	Type	Description
request_id	+	string	The identifier from the `check` request

Request example for request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
is_professional_income_taxpayer	-	bool	Shows whether the individual is self-employed
is_linked	-	bool	Shows whether the self-employed person is linked to Bank 131
error	-	object	Error

Examples of responses to request/status for check

The individual is self-employed and is linked to Bank 131
The individual is self-employed but is not linked to Bank 131

{
  "status": "ok",
  "is_professional_income_taxpayer": true,
  "is_linked": true
}

{
  "status": "ok",
  "is_professional_income_taxpayer": true,
  "is_linked": false
}

`npd/accruals` and `npd/request/status`

The method allows to obtain detailed information about tax accruals and bonus amount for the self-employed.

The request consists of two parts:

Send an npd/accruals request, passing a self-employed person's details, and receive the request_id identifier in response.
Send an npd/request/status request with this identifier. In response, you will receive detailed information about tax accruals and bonus amount for the self-employed.

The endpoint to send the `npd/accruals` request

/api/v1/npd/accruals

Request parameters for `npd/accruals`

Name	Mandatory	Type	Description
tax_reference_list	+	array	List of tax reference numbers (INN). Limited to 100 INNs per single request

Request example for npd/accruals

curl -X POST \
https://demo.bank131.ru/api/v1/npd/accruals  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference_list": [
    "111111111111"
  ]
}'

Response parameters for `npd/accruals`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
request_id	-	string	Identifier

Response example for npd/accruals

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/accruals`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
accruals	-	jagged array
tax_charge_list	-	array	List of various taxes accrued
amount	-	string	Accrued amount
due_date	-	string	Payment due date
tax_period_id	-	string	Tax period identifier. The value format: YYYYMM
oktmo	-	string	Russian National Classification of Municipal Territories (OKTMO) of the activity region
kbk	-	string	Budgetary classification code
paid_amount	-	string	The amount of payments received in Automated Information System (AIS) Tax 3 by this accrual
create_time	-	string	Date and time of the tax accrual
id	-	string	Internal identifier of the tax accrual in the Self-employment tax (NPD) Payment order (PP)
krsb_list	-	array	Debt data by the fiscal compliance card
debt	-	string	Debt amount by the fiscal compliance card
penalty	-	string	Penalty amount by the fiscal compliance card
overpayment	-	string	Overpayment amount by the fiscal compliance card
oktmo	-	string	Russian National Classification of Municipal Territories (OKTMO) of the activity region related to the fiscal compliance card (KRSB)
kbk	-	string	Budgetary classification code related to the fiscal compliance card (KRSB)
tax_organ_code	-	string	Code of the tax authority related to the fiscal compliance card (KRSB)
update_time	-	string	Date / Time of card revision in the Self-employment tax (NPD) Payment order (PP)
id	-	string	Internal identifier of the card in the Self-employment tax (NPD) Payment order (PP)
inn	-	string	Tax reference number (INN)

Response example for npd/request/status

{
  "status": "ok",
  "accruals": [
    {
      "tax_charge_list": [
        {
          "amount": "",
          "due_date": "",
          "tax_period_id": "",
          "oktmo": "",
          "kbk": "",
          "paid_amount": "",
          "create_time": "",
          "id": ""
        }
      ],
      "krsb_list": [
        {
          "debt": "",
          "penalty": "",
          "overpayment": "",
          "oktmo": "",
          "kbk": "",
          "tax_organ_code": "",
          "update_time": "",
          "id": ""
        }
      ],
      "inn": "111111111111"
    }
  ]
}

`npd/notifications/count` and `npd/request/status`

The method allows to obtain the number of unread notifications the Federal Tax Service sent to the self-employed.

The request consists of two parts:

Send an npd/notifications/count request, passing a self-employed person's details, and receive the request_id identifier in response.
Periodically send an npd/request/status request with this identifier. In response, you will receive the number of unread notifications. The pending status indicates that you must repeat the request.

The endpoint to send the `npd/notifications/count` request

/api/v1/npd/notifications/count

Request parameters for `npd/notifications/count`

Name	Mandatory	Type	Description
tax_reference_list	+	array	List of tax reference numbers (INN) (limited to 1000 per single request)

Request example for npd/notifications/count

curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/count  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference_list": [
    "123456789012"
  ]
}'

Response parameters for `npd/notifications/count`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
request_id	+	string	Identifier

Response example for npd/notifications/count

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/notifications/count`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
info	-	array	The number of notifications

Response example for npd/request/status

{
  "status": "ok",
  "info": [
    {
      "tax_reference": "123456789012",
      "count": 0
    }
  ]
}

`npd/notifications/mark_as_delivered` and `npd/request/status`

The method allows to inform the Federal Tax Service that notifications were delivered to a self-employed person. This method must be used after the notifications/read method.

The request consists of two parts:

Send an npd/notifications/mark_as_delivered request, passing a self-employed person's details, and receive the request_id identifier in response;
Send an npd/request/status request with this identifier. In response, you will receive the status of the delivery.

The endpoint to send the `npd/notifications/mark_as_delivered` request

/api/v1/npd/notifications/mark_as_delivered

Request parameters for `npd/notifications/mark_as_delivered`

Name	Mandatory	Type	Description
notification_list	+	array	Information about notifications

Request example for npd/notifications/mark_as_delivered

curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/mark_as_delivered  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "notification_list": [
    {
      "message_id_list": [
        "123",
        "234"
      ],
      "tax_reference": "123456789012"
    }
  ]
}'

Response parameters for `npd/notifications/mark_as_delivered`

Name	Mandatory	Type	Description
request_id	+	string	Identifier

Response example for npd/notifications/mark_as_delivered

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/notifications/read`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`

Response example for npd/request/status

{
  "status": "ok"
}

`npd/notifications/read` and `npd/request/status`

The method allows to obtain the detailed information about unread notifications the Federal Tax Service sent to the self-employed.

The request consists of two parts:

Send an npd/notifications/read request, passing a self-employed person's details, and receive the request_id identifier in response.
Periodically send an npd/request/status request with this identifier. In response, you will receive detailed information about unread notifications. The pending status indicates that you must repeat the request.

The endpoint to send the `npd/notifications/read` request

/api/v1/npd/notifications/read

Request parameters for `npd/notifications/read`

Name	Mandatory	Type	Description
tax_reference_list	+	array	List of tax reference numbers (INN)
get_read	+	boolean	Send the already read notifications in response. Possible values: `true` – send; `false` – do not send
get_archived	+	boolean	Send the archived notifications in response. Possible values: `true` – send; `false` – do not send

Request example for npd/notifications/read

curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/read \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference_list": [
    "123456789012"
  ],
  "get_read": false,
  "get_archived": false
}'

Response parameters for `npd/notifications/read`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
request_id	+	string	Identifier

Response example for npd/notifications/read

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/notifications/read`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
info	-	array	List of parameters for each tax reference number (INN)

Response example for npd/request/status

{
  "status": "ok",
  "info": [
    {
      "tax_reference": "123456789012",
      "notifications": [
        {
          "id": "132313",
          "title": "131.ru is asking for permission to act on your behalf",
          "message": "131.ru has asked you for permission to perform certain operations on your behalf. You can view the list of the operations and grant the permission by clicking <b>Allow</b>, or deny by clicking <b>Deny</b>",
          "status": "NEW",
          "created_at": "2023-03-22T13:29:55+00:00"
        }
      ]
    }
  ]
}

`npd/notifications/update` and `npd/request/status`

The method allows to inform the Federal Tax Service that notifications were read by the self-employed. The method must be used after the notifications/mark_as_delivered method.

The request consists of two parts:

Send an npd/notifications/update request, passing a self-employed person's details, and receive the request_id identifier in response.
Send an npd/request/status request with this identifier. In response, you will receive the status of the request.

The endpoint to send the `npd/notifications/update` request

/api/v1/npd/notifications/update

Request parameters for `npd/notifications/update`

Name	Mandatory	Type	Description
notification_list	+	array	Information about notifications

Request example for npd/notifications/update

curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/update \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "notification_list": [
    {
      "tax_reference": "123456789012"
    }
  ]
}'

Response parameters for `npd/notifications/update`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
request_id	-	string	Identifier

Response example for npd/notifications/update

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/notifications/update`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`

Response example for npd/request/status

{
  "status": "ok"
}

`npd/taxpayer/account_status` and `npd/request/status`

The method allows to obtain general information about tax accruals and bonus amount for the self-employed.

The request consists of two parts:

Send an npd/taxpayer/account_status request, passing a self-employed person's details, and receive the request_id identifier in response.
Send an npd/request/status request with this identifier. In response, you will receive general information about tax accruals and bonus amount for the self-employed.

The endpoint to send the `npd/taxpayer/account_status` request

/api/v1/npd/taxpayer/account_status

Request parameters for `npd/taxpayer/account_status`

Name	Mandatory	Type	Description
tax_reference	+	string	Tax reference number (INN). Limited to 1 INN per single request

Request example for npd/taxpayer/account_status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/taxpayer/account_status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference": "123456789012"
}'

Response parameters for `npd/taxpayer/account_status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
request_id	-	string	Identifier

Response example for npd/taxpayer/account_status

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/taxpayer/account_status`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
bonus_amount	-	string	Bonus amount
unpaid_amount	-	string	Total unpaid amount
debt_amount	-	string	Unpaid debt, included into total unpaid amount

Response example for npd/request/status

{
  "status": "ok",
  "bonus_amount": "9972.3624",
  "unpaid_amount": "0",
  "debt_amount": "0"
}

`npd/taxpayer/check_personal_info` and `npd/request/status`

Verification of the self-employed data

This request allows to verify with the Federal Tax Service if there is any inconsistency in data (INN, full name, phone number) provided by a self-employed person.

The request consists of two parts:

Send an npd/taxpayer/check_personal_info request, passing a self-employed person's INN, full name, and phone number, and receive the request_id identifier in response.
Periodically send an npd/request/status request with this identifier. In response, you will receive a list of inconsistent parameters, if there is any. The pending status indicates that you must repeat the request.

The endpoint to send the `npd/taxpayer/check_personal_info` request

/api/v1/npd/taxpayer/check_personal_info

Request parameters for `npd/taxpayer/check_personal_info`

Name	Mandatory	Type	Description
first_name	+	string	First name
second_name	+	string	Family name
patronymic	+	string	Patronymic name
tax_reference	+	string	Tax reference number (INN)
phone	+	string	Phone number in the "7ХХХХХХХХХХ" format

Request example for npd/taxpayer/check_personal_info

curl -X POST \
https://demo.bank131.ru/api/v1/npd/taxpayer/check_personal_info  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "status": "ok",
  "bonus_amount": "9972.3624",
  "unpaid_amount": "0",
  "debt_amount": "0"
}'

Response parameters for `npd/taxpayer/check_personal_info`

Name	Mandatory	Type	Description
request_id	+	string	Identifier

Response example for npd/taxpayer/check_personal_info

{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the `npd/request/status` request

/api/v1/npd/request/status

Request parameters for `npd/request/status`

Name	Mandatory	Type	Description
request_id	+	string	Identifier passed in response at `npd/taxpayer/check_personal_info`

Request example for npd/request/status

curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for `npd/request/status`

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`, `pending`
success	-	bool	Inconsistency in data. `true` - consistent data; `false` - inconsistent data
violations	-	array[string]	Parameters with inconsistent data. Possible values: "first_name", "second_name", "patronymic", "tax_reference", "phone"
error	-	object	Error

Response example for npd/request/status

{
  "status": "ok",
  "success": false,
  "violations": [
    "first_name",
    "second_name",
    "phone"
  ]
}

Escrow account

`session/init/payout/nominal`

Creating a session with a simultaneous payout to a bank account

You can use this request to send payouts from an escrow account to a bank account.

Endpoint

api/v1/session/init/payout/nominal

Request parameters

Name	Mandatory	Type	Description
payment_method	+	object	Payment details
amount_details	-	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
participant_details	+	object	Information about the participants (the sender and the recipient)
fiscalization_details	-	object	Fiscalization details; only for payouts to the self-employed
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request examples

Payout to an individual's account
Payout to a legal entity's account

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
        "bik": "044525974",
        "account": "40817810400003869535",
        "full_name": "Ivanov Ivan Ivanovich",
        "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient": {
      "beneficiary_id": "1234567890"
    }
  }
}'

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
        "bik": "044525974",
        "account": "40702810500000000001",
        "full_name": "Company name",
        "inn": "1111111111",
        "kpp": "156605101",
        "description": "Funds transfer according to the contract for December of 2022 VAT exempt."
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient": {
      "beneficiary_id": "1234567890"
    }
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Valid values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_287403",
    "status": "in_progress",
    "created_at": "2023-05-10T16:58:43.586072Z",
    "updated_at": "2023-05-10T16:58:43.705620Z",
    "payments": [
      {
        "id": "po_72265",
        "status": "in_progress",
        "created_at": "2023-05-10T16:58:43.781934Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "049205131",
              "account": "40702810900000000001",
              "full_name": "Company name",
              "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt",
              "is_fast": false,
              "kpp": "156605001",
              "inn": "3111104710"
            }
          }
        },
        "amount_details": {
          "amount": 200,
          "currency": "rub"
        },
        "paymentMetadata": {},
        "participant_details": {
          "sender": {
            "account": "40702810300200000013"
          },
          "recipient": {
            "beneficiary_id": "1234567890"
          }
        }
      }
    ]
  }
}

{
  "status": "error",
  "error": {
    "description": "Invalid input request parameters: payment_method.bank_account.ru.inn (bank_account_ru.inn.invalid_length)",
    "code": "invalid_request"
  }
}

`session/multi/create/nominal`

Creating a payment session

Creates a payment session on Bank 131's side.

Payment operations can only be performed within a session. One or more operations can be performed within the session.

If you are ready to provide all the data needed to perform the operation in the request, you can use the session/multi/init/payment/nominal method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint

/api/v1/session/multi/create/nominal

Request parameters

Name	Mandatory	Type	Description
payment_details	+	object	Transfer details
payment_method	+	object	Payment details (card, customer account, etc.)
fiscalization_details	-	object	Fiscalization details; only for payouts to the self-employed
participant_details	- (mandatory for the payouts to card)	object	Information about the participants (the sender and the recipient)
amount_details	-	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
customer	+	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/create/nominal  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

`session/multi/init/payment/nominal`

Creating a session with a simultaneous payout

The response contains the parameters of the session created and an object with information about the payment (acquiring_payment).

Endpoint

/api/v1/session/multi/init/payment/nominal

Request parameters

Name	Mandatory	Type	Description
payment_details	+	object	Transfer details
payment_method	+	object	Payment details (card, customer account, etc.)
fiscalization_details	-	object	Fiscalization details; only for payouts to the self-employed
participant_details	- (mandatory for the payouts to card)	object	Information about the participants (the sender and the recipient)
amount_details	-	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
customer	+	object	Recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/init/payment/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Valid values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

`session/multi/start/payment/nominal`

Starting a payout

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed.

If you are using the widget for getting the user's tokenized bank card details, you can pass them using this request.

Endpoint

/api/v1/session/multi/start/payment/nominal

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session identifier
payment_details	-	object	Transfer details
payment_method	-	object	Payment details (card, customer account, etc.)
fiscalization_details	-	object	Fiscalization details; only for payouts to the self-employed
participant_details	- (mandatory for the payouts to card)	object	Information about the participants (the sender and the recipient)
amount_details	-	object	Amount. Transmitted in the ruble decimal format. To send 100 rubles, specify `10000`
customer	-	object	The recipient's data in your system
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_12345",
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	The payment session
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

Settlement account

`session/init/payout/rko`

The method creates a session with starting a payout from a settlement account to a bank account at once.

Endpoint

/api/v1/session/init/payout/rko

Request parameters

Name	Mandatory	Type	Description
payment_method	+	object	Payment details (bank account)
amount_details	+	object	Amount in kopecks. To send 100 rubles, specify `10000`
participant_details	+	object	Sender's details
metadata	-	*	Any additional details required for the transaction. The details return within responds and webhooks.

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/rko  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "system_type": "ru",
      "ru": {
        "bik": "049205131",
        "account": "40702810300000000006",
        "full_name": "Acme",
        "inn": "1234567890",
        "kpp": "165801002",
        "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt"
      }
    }
  },
  "amount_details": {
    "amount": 212,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810900000000011"
    }
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	Session details
error	-	object	Error

Response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "049205131",
              "account": "40702810300000000006",
              "full_name": "Acme ",
              "inn": "1234567890",
              "kpp": "165801002",
              "description": "Description of payment"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

`session/multi/create/rko`

Creates a payment session on Bank 131's side.

Payment operations can only be performed within a session. One or more operations can be performed within the session.

If you are ready to provide all the data needed to perform the operation in the request, you can use the (/api/v1/session/multi/init/payment/rko) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint

/api/v1/session/multi/create/rko

Name	Mandatory	Type	Description
payment_details	+	object	Transaction details
payment_method	+	object	Payment details (bank card, bank account, etc.)
fiscalization_details	-	object	Fiscalization details. Mandatory for payouts to the self-employed.
participant_details	- (mandatory for payouts to bank cards)	object	Transaction participants details (sender and recipient)
amount_details	-	object	Amount in kopecks. To send 100 rubles, specify `10000`
customer	-	object	Recipient's details in your system
metadata	-	*	Any additional details required for the transaction. The details return within responds and webhooks

Request example

curl -X POST \
https://demo.bank131.ru//api/v1/session/multi/create/rko   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_bank_account",
      "transfer_from_bank_account": {
        "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "****************"
      }
    }
  },
  "participant_details": {
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov"
    },
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov"
    }
  },
  "amount_details": {
    "amount": 293400,
    "currency": "RUB"
  },
  "customer": {
    "reference": "123456789012"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	Payment session details
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_bank_account",
            "transfer_from_bank_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

`session/multi/start/payment/rko`

Payout start

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Either, you can change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint

/api/v1/session/multi/start/payment/rko

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Payment session id
payment_details	-	object	Transaction details
payment_method	-	object	Payment details (bank card, bank account, etc.)
customer	-	object	Recipient's details in your system
amount_details	-	object	Amount in kopecks. To send 100 rubles, specify `10000`
fiscalization_details	-	object	Fiscalization details. Mandatory for payouts to the self-employed.
participant_details	- (mandatory when making a payout to a bank card)	object	Transaction participants details (sender and recipient)

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/rko   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_12345",
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_bank_account",
      "transfer_from_bank_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	Payment session details
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_bank_account",
            "transfer_from_bank_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "customer.reference.not_blank"
  },
  "status": "error"
}

Money transfers

`/bpa/session/init/payment`

This method is used to initiate the transfer.

Endpoint

/api/v1/bpa/session/init/payment

Request parameters

Name	Mandatory	Type	Description
payment_details	+	object	Transfer details
amount_details	-	object	Payment details
participant_details	-	object	Information about the participants
cash_details	+	object	Additional information on the cash payment

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/bpa/session/init/payment   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "moneysend",
    "moneysend": {}
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "citizenship_country_iso3": "AUS",
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "middle_name": "Ivanovich",
      "country_iso3": "RUS",
      "state": "New York",
      "city": "Kazan",
      "postal_code": "420000",
      "street": "Nekrasova",
      "building": "1",
      "flat": "131",
      "tax_reference": "123456789012",
      "date_of_birth": "2010-01-01",
      "contacts": {
        "phone": {
          "full_number": "+79371234567",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "1234567"
        },
        "email": "test@test.com"
      },
      "identity_document": {
        "id_type": "Паспорт гражданина Российской Федерации",
        "id_number": "123456789",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01",
        "division_code": "165-065",
        "issued_by": "OVD Kazani"
      },
      "documents_foreigner": {
        "id_type": "Виза",
        "issued_by": "OVD Kazani",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01"
      },
      "service_point": {
        "id": "1",
        "name": "point_on_lenina",
        "country_iso3": "RUS",
        "state": "Moscow",
        "city": "Moscow",
        "oktmo": "36634436111",
        "street": "Lenin avenue",
        "house": "1",
        "terminal_id": "123124"
      },
      "source_of_money": "salary",
      "description": "salary transfers"
    },
    "recipient": {
      "first_name": "Ivan",
      "last_name": "Sidorov",
      "middle_name": "Ivanovich",
      "date_of_birth": "2010-01-01",
      "currency": "TRY",
      "contacts": {
        "phone": {
          "full_number": "+79377654321",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "7654321"
        },
        "email": "test@test.com"
      }
    }
  },
  "cash_details": {
    "shift": "11"
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	Payment session details
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_592245",
    "status": "in_progress",
    "created_at": "2022-11-15T15:38:50.255803Z",
    "updated_at": "2022-11-15T15:38:50.336303Z",
    "acquiring_payments": [
      {
        "id": "pm_296251",
        "status": "in_progress",
        "created_at": "2022-11-15T15:38:50.357833Z",
        "payment_details": {
          "type": "moneysend",
          "moneysend": {}
        },
        "amount_details": {
          "amount": 978,
          "currency": "rub"
        },
        "participant_details": {
          "sender": {
            "citizenship_country_iso3": "AUS",
            "first_name": "Ivan",
            "last_name": "Ivanov",
            "middle_name": "Ivanovich",
            "country_iso3": "RUS",
            "state": "New York",
            "city": "Kazan",
            "postal_code": "420000",
            "street": "Nerkasova",
            "building": "1",
            "flat": "131",
            "tax_reference": "123456789012",
            "date_of_birth": "2010-01-01",
            "contacts": {
              "phone": {
                "full_number": "+79371234567",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "1234567"
              },
              "email": "test@test.com"
            },
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "123456789",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01",
              "division_code": "165-065",
              "issued_by": "OVD Kazani"
            },
            "documents_foreigner": {
              "id_type": "Виза",
              "issued_by": "OVD Kazani",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01"
            },
            "service_point": {
              "id": "1",
              "name": "point_on_lenina",
              "country_iso3": "RUS",
              "state": "Moscow",
              "city": "Moscow",
              "oktmo": "36634436111",
              "street": "Lenin avenue",
              "house": "1",
              "terminal_id": "123124"
            },
            "source_of_money": "salary",
            "description": "salary transfers"
          },
          "recipient": {
            "first_name": "Ivan",
            "last_name": "Sidorov",
            "middle_name": "Ivanovich",
            "date_of_birth": "2010-01-01",
            "currency": "TRY",
            "contacts": {
              "phone": {
                "full_number": "+79376151530",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "7654321"
              },
              "email": "test@test.com"
            }
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "participant_details.recipient.full_name.not_blank"
  },
  "status": "error"
}

`/cash/payout/session/init`

This method is used to initiate the payout of funds to the recipient or refund of the transfer to the sender. The set of parameters is the same in both cases. To refund the transfer to the sender, pass the same details for the sender (participant_details.sender) and the recipient (participant_details.recipient) of the transfer in the request.

Note that the received transfer code must be wrapped in BASE64 and put in the tcn_code_encoded parameter.

Endpoint

/api/v1/cash/payout/session/init

Request parameters

Name	Mandatory	Type	Description
tcn_code_encoded	+	string	Transaction code received from the recipient and wrapped in BASE64. Example: “MzU4MDctMjM1ODk=”
payment_method	+	object	Payment details. Pass the `moneysend` value.

Request example

curl -X POST \
https://demo.bank131.ru/api/v1/cash/payout/session/init   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tcn_code_encoded": "NTkyMjM3LTg5MjEzNDk5",
  "payment_method": {
    "type": "moneysend",
    "moneysend": {}
  },
  "cash_details": {
    "shift": "159"
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "recipient": {
      "citizenship_country_iso3": "AUS",
      "first_name": "Ivan",
      "last_name": "Sidorov",
      "middle_name": "Ivanovich",
      "country_iso3": "RUS",
      "state": "New York",
      "city": "Kazan",
      "postal_code": "420000",
      "street": "Nerkasova",
      "building": "1",
      "flat": "131",
      "tax_reference": "123456789012",
      "date_of_birth": "2008-01-01",
      "identity_document": {
        "id_type": "Паспорт гражданина Российской Федерации",
        "id_number": "123456789",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01",
        "division_code": "165-065",
        "issued_by": "OVD Kazani"
      },
      "documents_foreigner": {
        "id_type": "Виза",
        "issued_by": "OVD Kazani",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01"
      },
      "service_point": {
        "id": "1",
        "name": "point_on_lenina",
        "country_iso3": "RUS",
        "state": "Moscow",
        "city": "Moscow",
        "oktmo": "36634436111",
        "street": "Lenin avenue",
        "house": "1",
        "terminal_id": "123124"
      },
      "source_of_money": "salary",
      "description": "salary transfers",
      "contacts": {
        "phone": {
          "full_number": "+79377654321",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "7654321"
        },
        "email": "test@test.com"
      }
    },
    "sender": {
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "middle_name": "Ivanovich",
      "contacts": {
        "phone": {
          "full_number": "+79371234567",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "1234567"
        },
        "email": "test@test.com"
      }
    }
  }
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
session	-	object	Payment session details
error	-	object	Error

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2022-11-01T02:03:00.000000Z",
    "updated_at": "2022-11-01T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2022-11-01T02:03:00.000000Z",
        "payment_method": {
          "type": "moneysend"
        },
        "participant_details": {
          "recipient": {
            "citizenship_country_iso3": "AUS",
            "first_name": "Ivan",
            "last_name": "Sidorov",
            "middle_name": "Ivanovich",
            "country_iso3": "RUS",
            "state": "New York",
            "city": "Kazan",
            "postal_code": "420000",
            "street": "Nekrasova",
            "building": "1",
            "flat": "131",
            "tax_reference": "123456789012",
            "date_of_birth": "2010-01-01",
            "contacts": {
              "phone": {
                "full_number": "+79377654321",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "7654321"
              },
              "email": "test@test.com"
            },
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "123456789",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01",
              "division_code": "165-065",
              "issued_by": "OVD Kazani"
            },
            "documents_foreigner": {
              "id_type": "Виза",
              "issued_by": "OVD Kazani",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01"
            },
            "service_point": {
              "id": "1",
              "name": "point_on_lenina",
              "country_iso3": "RUS",
              "state": "Moscow",
              "city": "Moscow",
              "oktmo": "36634436111",
              "street": "Lenin avenue",
              "house": "1",
              "terminal_id": "123124"
            },
            "source_of_money": "salary",
            "description": "salary transfers",
            "customer_verification": {
              "first_name": "Ivan",
              "last_name": "Ivanov",
              "middle_name": "Ivanovich",
              "date_of_birth": "2010-01-01",
              "contacts": {
                "phone": {
                  "full_number": "+79371234567",
                  "country_iso3": "RUS",
                  "operator_code": "937",
                  "short_number": "1234567"
                },
                "email": "test@test.com"
              }
            }
          },
          "sender": {
            "first_name": "Ivan",
            "last_name": "Ivanov",
            "middle_name": "Ivanovich",
            "contacts": {
              "phone": {
                "full_number": "+79371234567",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "1234567"
              },
              "email": "test@test.com"
            }
          }
        }
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "description": "participant_details.recipient.full_name.not_blank"
  },
  "status": "error"
}

Other methods

`sberpay/push`

Method to send PUSH/SMS notifications to customers for SberPay transactions.

Endpoint

/api/v1/sberpay/push

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session ID
phone	+	string	Phone number to send PUSH or SMS

Request example

curl -X GET
https://proxy.bank131.ru/api/v1/sberpay/push \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_75459435",
  "phone": "+79638594ххх"
}'

Response parameters

Name	Mandatory	Type	Description
status	+	string	Status. Possible values: `error`, `ok`
error	-	object	Error description

Response examples

Successful response example
Unsuccessful response example

{
  "status": "ok"
}

{
    "status": "error",
    "error":
    {
        "description": "Internal error",
        "code": "internal_error"
    }
}

Performing operations
Information
Self-employed people
Escrow account
Settlement account
Money transfers
- /bpa/session/init/payment
- /cash/payout/session/init
Other methods
- sberpay/push

Performing operations​

fiscalization​

Fiscalization without payment​

Endpoint​

Request parameters​

Response parameters​

recurrent/disable​

Disable token for recurring payments​

Endpoint​

Request parameters​

Response parameters​

session/cancel​

Operation cancellation​

Endpoint​

Request parameters​

Response parameters​

session/capture​

Debiting amounts put on hold​

Endpoint​

Request parameters​

Response parameters​

session/confirm​

Operation confirmation​

Endpoint​

Request parameters​

Response parameters​

session/create​

Payment session creation​

Endpoint​

Request parameters​

Response parameters​

session/init/payment​

Session creation with simultaneous payout initiation​

Request parameters​

Response parameters​

session/init/payment/sync​

One-request payment​

Request parameters​

Response parameters​

session/init/payout​

Session creation with simultaneous payout initiation​

Endpoint​

Request parameters​

Response parameters​

session/init/payout/fiscalization​

Session creation and payout start, with additional check that all the fiscalization data has been provided​

Endpoint​

Response parameters​

session/refund​

Refund​

Endpoint​

Request parameters​

Response parameters​

session/start/payment​

Payment start​

Endpoint​

Request parameters​

Response parameters​

session/start/payout​

Payout start​

Endpoint​

Request parameters​

Response parameters​

session/start/payout/fiscalization​

Payout start, with check that all fiscalization data has been provided​

Endpoint​

Request parameters​

Response parameters​

token​

Generation of a token to work with widgets​

Endpoint​

Request parameters​

Response parameters​

token/info​

Receiving information via token​

Endpoint​

Request parameters​

Response parameters​

tokenize​

Endpoint​

Performing operations

`fiscalization`

Fiscalization without payment

Endpoint

Request parameters

Response parameters

`recurrent/disable`

Disable token for recurring payments

Endpoint

Request parameters

Response parameters

`session/cancel`

Operation cancellation

Endpoint

Request parameters

Response parameters

`session/capture`

Debiting amounts put on hold

Endpoint

Request parameters

Response parameters

`session/confirm`

Operation confirmation

Endpoint

Request parameters

Response parameters

`session/create`

Payment session creation

Endpoint

Request parameters

Response parameters

`session/init/payment`

Session creation with simultaneous payout initiation

Request parameters

Response parameters

`session/init/payment/sync`

One-request payment

Request parameters

Response parameters

`session/init/payout`

Session creation with simultaneous payout initiation

Endpoint

Request parameters

Response parameters

`session/init/payout/fiscalization`

Session creation and payout start, with additional check that all the fiscalization data has been provided

Endpoint

Response parameters

`session/refund`

Refund

Endpoint

Request parameters

Response parameters

`session/start/payment`

Payment start

Endpoint

Request parameters

Response parameters

`session/start/payout`

Payout start

Endpoint

Request parameters

Response parameters

`session/start/payout/fiscalization`

Payout start, with check that all fiscalization data has been provided

Endpoint

Request parameters

Response parameters

`token`

Generation of a token to work with widgets

Endpoint

Request parameters

Response parameters

`token/info`

Receiving information via token

Endpoint

Request parameters

Response parameters

`tokenize`

Endpoint