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
anddate_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.
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 thetax_reference
parameter, and wait for arequest_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 therequest_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 therequest_id
identifier in response. - Periodically send an
npd/request/status
request with this identifier. In response, you will receive the number of unread notifications. Thepending
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 therequest_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 therequest_id
identifier in response. - Periodically send an
npd/request/status
request with this identifier. In response, you will receive detailed information about unread notifications. Thepending
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 therequest_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 therequest_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 therequest_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. Thepending
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.
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
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
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 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.
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 (
/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. |
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/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"
}
}