Methods
When processing requests, the system checks for valid input parameters, the presence of the necessary headers, and rights to perform operations.
Performing operations
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 | - | PaymentMethod | Payment details (card, customer account, etc.) |
amount_details | - | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
fiscalization_details | - | FiscalizationDetails | Fiscalization details; only for payouts to the self-employed |
participant_details | - | ParticipantDetails | Information about the participants (the sender and the recipient) |
customer | Mandatory for payments | Customer | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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);
Successful response example
{
"status": "ok",
"session": {
"id": "3230",
"status": "created",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
}
}
Unsuccessful response example
{
"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 | + | PaymentMethod | Payment details (card, customer account, etc.) |
amount_details | + | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
fiscalization_details | - | FiscalizationDetails | Fiscalization details |
participant_details | - | ParticipantDetails | Information about the participants (the sender and the recipient) |
customer | - | Customer | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
payment | - | PaymentMethod | Payout details (card, customer account etc.) |
error | - | Error | Error |
Request example
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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);
Successful response example
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "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 | - | PaymentMethod | Payment details (card, customer account, etc.) |
amount_details | - | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
fiscalization_details | - | FiscalizationDetails | Fiscalization details |
participant_details | - | ParticipantDetails | Information about the participants (the sender and the recipient) |
customer | - | Customer | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
payment | - | PaymentMethod | Payout details (card, customer account etc.) |
error | - | Error | Error |
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/fiscalization \
-H 'content-type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '{
"fiscalization_details": {
"professional_income_taxpayer": {
"tax_reference": "590000000000",
"payer_type": "legal",
"payer_tax_number": "3300000000",
"payer_name": "OOO Roga and Kopyta",
"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 Roga and Kopyta');
$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);
Successful 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 Roga and Kopyta",
"services": [
{
"name": "Service description",
"amount_details": {
"amount": 10000,
"currency": "rub"
}
}
]
}
},
"metadata": "order123",
"participant_details": {
"recipient": {
"full_name": "Ivanov Ivan"
}
}
}
]
}
}
Unsuccessful response example
{
"error": {
"code": "invalid_request",
"description": "participant_details.recipient.full_name.not_blank"
},
"status": "error"
}
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 | - | PaymentMethod | Payout details (card, customer account, etc.) |
amount_details | - | AmountDetails | The amount |
participant_details | - | ParticipantDetails | Information on payout participants |
customer | - | Customer | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
curl --location --request POST 'https://demo.bank131.ru/api/v1/session/start/payout' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: fd582e8a6619830e1e506ee68ece1ae0e2124f9047688617f7cf803ee492b9dd' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"session_id": "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);
Successful response example
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "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 | - | PaymentMethod | Payment details (card, customer account, etc.) |
amount_details | - | AmountDetails | The amount |
fiscalization_details | - | FiscalizationDetails | Fiscalization details |
participant_details | - | ParticipantDetails | Information on payout participants |
customer | - | Customer | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
curl --location --request POST 'https://demo.bank131.ru/api/v1/session/start/payout/fiscalization' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: 1cc6297fb447f038fd51f9e49d51fad3a0a37dfb801e6c830a2748e0b695a83b' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"session_id": "3230",
"fiscalization_details": {
"professional_income_taxpayer": {
"tax_reference": "590000000000",
"payer_type": "legal",
"payer_tax_number": "330000000000",
"payer_name": "OOO Roga and Kopyta",
"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 Roga and Kopyta');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');
$request = RequestBuilderFactory::create()
->startPayoutSessionWithFiscalization('3230', $incomeInformation)
->build();
$response = $client->session()->create($request);
Successful response example
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "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": "ООО Roga and Kopyta"
}
}
}
]
}
}
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 | + | FiscalizationDetails | Fiscalization details |
payment_method | - | PaymentMethod | Payout details (card, customer account, etc.) |
amount_details | - | AmountDetails | The amount |
participant_details | - | ParticipantDetails | Information on payout participants |
customer | - | Customer | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
curl --location --request POST 'https://demo.bank131.ru/api/v1/fiscalization' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: project' \
--data-raw '{
"session_id": "ps_2704",
"fiscalization_details": {
"professional_income_taxpayer": {
"tax_reference": "123456789012",
"payer_type": "legal",
"payer_tax_number": "3316004777",
"payer_name": "OOO Roga and Kopyta",
"services": [
{
"name": "Goods delivery",
"amount_details": {
"amount": 5000,
"currency": "rub"
}
},
{
"name": "Component delivery",
"amount_details": {
"amount": 5000,
"currency": "rub"
}
}
]
}
}
}'
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"
},
"amounts": {
"gross": {
"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": "ООО Roga and Kopyta"
}
}
}
]
}
}
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 (AcquiringPayment
).
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
payment_details | + | PaymentDetails | Payment data |
amount_details | + | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
participant_details | - | ParticipantDetails | Participants information |
customer | + | Customer | Client data in your system |
payment_options | - | PaymentOptions | Additional payment parameters |
metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
curl --location --request POST 'https://demo.bank131.ru/api/v1/session/init/payment' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"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);
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",
"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"
}
}
]
}
}
Unsuccessful response example
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}
session/init/payment/sync
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 object AcquiringPayment
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 | + | PaymentDetails | Payment data |
type | + | string | Payment method type. Possible values: card |
card | + | CardPaymentMethod | Object containing bank card details |
type | + | string | Method of card information transmission. Value: bank_card |
bank_card | + | BankCard | 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 | + | AmountDetails | Object with payment amount |
amount | + | int | The amount in ruble decimal format. The value must be greater than zero. If the payment amount is 100 rubles, you need to specify 10000 |
currency | + | string | The ISO 4217 currency code. Case insensitive. Always: rub |
participant_details | - | ParticipantDetails | Participants information |
customer | + | Customer | Information about payment sender on your side |
reference | + | string | Payment sender ID in your system |
payment_options | + | PaymentOptions | 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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: project' \
--data-raw '{
"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"
}
}'
Successful 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"
}
}
]
}
}
Unsuccessful response example
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}
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 | - | PaymentDetails | Payment data |
amount_details | - | AmountDetails | The amount |
participant_details | - | ParticipantDetails | Information about the participants (the payer and the recipient) |
customer | - | Customer | Payment sender information in your system |
metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
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: e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff' \
-d '{
"session_id": "3230",
"payment_method": {
"type": "encrypted_card",
"encrypted_card": {
"number_hash": "e05794ee22f47ee5f674e63303ea227e6113f42359f332945304f1e958542fff",
"expiration_date_hash":"f4286b9a8e0eb7974f34a996ee732fd861868f2fc7aaa7ed5cca8de2489534ad",
"cardholder_name_hash":"dd6cce1e06790019dd266c6f70430f87dd378df802c6b7494395156f62533ce6",
"security_code_hash":"7756b897e88c035f34c6658a147e263b29b480a5cdf76581012ff10ede478c4c"
}
},
"metadata": "good"
}'
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()
->startPaymentSession('session_id')
->setCard(
new EncryptedCard(
'number_hash',
'expiration_date_hash',
'cardholder_name_hash',
'security_code_hash'
)
)
->setMetadata('good')
->build();
$response = $client->session()->startPayment($request);
Successful response example
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"acquiring_payments": [
{
"id": "2018",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"customer": {
"reference": "user123",
"contacts": [
{
"email": "user@gmail.com"
}
]
},
"payment_details": {
"type": "card",
"card": {
"last4": "4242",
"brand": "visa"
}
},
"amount_details": {
"amount": 10000,
"currency": "rub"
},
"metadata": "good"
}
]
}
}
session/confirm (confirm_request)
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 confirm_request
to Bank 131. If something is not right, cancel the operation by sending a cancel_request
to Bank 131.
Endpoint
/api/v1/session/confirm
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
session_id | + | string | Session identifier |
confirm_information | - (mandatory only for the transactions with an escrow account) | ConfirmInformation | Transaction confirmation information |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example: confirm_request
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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "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 example
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "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 (capture_request)
Debiting amounts put on hold
This request can be used if you are sending payments with later capture. 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 capture_request
. You can debit the full amount on hold, or a portion of it.
To cancel the debit, send a cancel_request
.
Endpoint
/api/v1/session/capture
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
session_id | + | string | Bank 131 session identifier |
amount_details | - | AmountDetails | 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. |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example: capture_request
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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "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');
session/cancel (cancel_request)
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 cancel_request
.
If everything looks good, send a request to confirm the operation (confirm_request
) or a request to debit the amount being put on hold (capture_request
).
Endpoint
/api/v1/session/cancel
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
session_id | + | string | Session identifier |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example: cancel_request
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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "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 example
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2018-05-27T02:03:00.000000Z",
"updated_at": "2018-05-27T02:03:00.000000Z",
"payments": [
{
"id": "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/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 | - | AmountDetails | The amount of the refund. If not specified, the refund will be made for the full amount of the payment. |
metadata | - | * | Additional information |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example
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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9871' \
-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 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"
}
}
]
}
]
}
}
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 | - | TokenizeWidgetMetadata | The data required by the tokenization widget |
self_employed_widget | - | SelfEmployedWidgetMetadata | The data required by the self-employed registration widget |
acquiring_widget | - | AcquiringWidgetMetadata | The data required by the payment form widget |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
public_token | - | string | The public token |
error | - | Error | Error |
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 -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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '{
"acquiring_widget": {
"session_id": "ps_123456"
}
}'
Successful response example
{
"status": "ok",
"public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539"
}
Unsuccessful response example
{
"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 payments and payments through widgets, a public token is created. For recurrent payments, a recurrent token is created.
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,
- or 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 |
card | - (mandatory for type = card ) | CardPaymentMethod | Object containing bank card details |
public_token | - (mandatory for type = public_token ) | PublicToken | Object with token details |
recurrent_token | - (mandatory for type = recurrent_token ) | RecurrentToken | Object with recurrent token details |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
info | - | CardTokenInfo, PublicTokenInfo, or RecurrentTokenInfo | Information about the token, depending on the type of request (type ) |
error | - | Error | Error |
Request card information via token
Request example
You send tokenized bank card details and receive a hidden card and payment system.
curl --location --request POST 'https://demo.bank131.ru/api/v1/token/info' \
--header 'X-PARTNER-PROJECT: partner-project' \
--header 'X-PARTNER-SIGN: key' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "card",
"card": {
"type": "encrypted_card",
"encrypted_card": {
"number_hash": "card_number_hash (token)"
}
}
}'
Response example
"status": "ok",
"info": {
"number_hash": "card_number_hash",
"brand": "visa",
"last4": "4242",
"type": "card"
}
}
Request for information about a public token
Request example
You send a public token and receive information about it.
curl --location --request POST 'https://demo.bank131.ru/api/v1/token/info' \
--header 'X-PARTNER-PROJECT: partner-project' \
--header 'X-PARTNER-SIGN: key' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "public_token",
"public_token": {
"token": "your_token"
}
}'
Response example
{
"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"
}
}
Request for information about a recurring token
Request example
You send a recurring token and receive information about it.
curl --location --request POST 'https://demo.bank131.ru/api/v1/token/info' \
--header 'X-PARTNER-PROJECT: partner-project' \
--header 'X-PARTNER-SIGN: key' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "recurrent_token",
"recurrent_token": {
"token": "your_token"
}
}'
Response example
{
"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"
}
}
recurrent/disable
Disable recurrent token
You can disable a recurrent token with this request. Send the token in the request, in the response you will get is_active: false
. This means you cannot perform recurrent 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 | + | RecurrentToken | Object with a token |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
recurrent | + | RecurrentTokenInfo | Object with a token |
Request example
url --location --request POST 'https://demo.bank131.ru/api/v1/recurrent/disable' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"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 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"
}
Information
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 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
Request example: status_request
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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9872' \
-d '{
"session_id": "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');
Successful response example
{
"status": "ok",
"session": {
"id": "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": "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"
}
]
}
}
wallet/balance
You can use this request to check your current Bank 131 deposit balance.
This is necessary in order to make sure there is enough money on the balance:
- for mass 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 your remote banking service account.
Endpoint
/api/v1/wallet/balance
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
request_datetime | + | string | The timestamp of the request in ISO 8601 |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
wallets | - | WalletDetails | The list of guarantee payment accounts available at Bank 131. |
error | - | Error | Error |
Request example
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: 6eaf1e9cfa15f011e02c0a126187fe327a71e9d79be5e3fdb3f69dc5dfcd9871' \
-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 example
{
"status": "ok",
"wallets": [
{
"id": "131",
"amount_details": {
"amount": 13100,
"currency": "rub"
}
}
]
}
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 --location --request GET 'https://demo.bank131.ru/api/v1/fps/banks' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: test-partner' \
--data-raw '{}'
Response example
{
"banks": [
{
"id": "100000000243",
"eng_name": "National Standard Bank",
"ru_name": "Национальный стандарт"
},
{
"id": "100000000056",
"eng_name": "Khlynov",
"ru_name": "Хлынов"
},
...
]
}
fps/customer_verification
You may use this request to check whether a recipient is registered in the Faster Payment system. If the use if found in FPS the session will have a successful status, else the session will be cancelled. This operation is free of charge and is confirmed automatically (the ready_to_confirm
is not sent).
Endpoint
/api/v1/fps/customer_verification
Request parameters
Название | Обязательность | Тип | Описание |
---|---|---|---|
payment_method | - | PaymentMethod | Payment details (card, customer account, etc.) |
participant_details | - | ParticipantDetails | Information about the participants (the sender and the recipient) |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
wallets | - | WalletDetails | The list of guarantee payment accounts available at Bank 131. |
error | - | Error | Error |
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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 example
{
"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"
}
}
},
"amount_details": {
"amount": 100,
"currency": "rub"
},
"participant_details": {
"recipient": {
"first_name": "Иван",
"last_name": "Иванов",
"middle_name": "Иванович"
}
}
}
]
}
}
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:
- First, you send a
check
request, passing the individual's INN in thetax_reference
parameter, and receive arequest_id
identifier in response. - Then, you 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
The check request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
tax_reference | + | string | Individual's INN |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok , pending |
request_id | + | string | Request identifier |
Request example: check
curl -X POST \
https://demo.bank131.ru/api/v1/npd/check \
-H 'content-type: application/json' \
-H 'X-PARTNER-PROJECT: project' \
-H 'X-PARTNER-SIGN: rsa-signature' \
-d '{
"tax_reference": "123456789012"
}'
Example of response to: 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
The request/status request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
request_id | + | string | The identifier received in response to the check request |
Response parameters
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 | - | Error object | Error |
Request example: request/status for check
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'content-type: application/json' \
-H 'X-PARTNER-PROJECT: project' \
-H 'X-PARTNER-SIGN: rsa-signature' \
-d '{
"request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'
An example of a response to request/status for check: the individual is self-employed and is linked to Bank 131
{
"status": "ok",
"is_professional_income_taxpayer": true,
"is_linked": true
}
An example of a response to request/status for check: the individual is self-employed but is not linked to Bank 131
{
"status": "ok",
"is_professional_income_taxpayer": true,
"is_linked": false
}
Escrow account
session/multi/create/nominal
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 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/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 | + | PaymentDetails | Transfer details |
payment_method | + | PaymentMethod | Payment details (card, customer account, etc.) |
customer | + | Customer | The recipient's data in your system. |
amount_details | - | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
fiscalization_details | - | FiscalizationDetails | Fiscalization details; only for payouts to the self-employed |
participant_details | - (mandatory for the payouts to card) | ParticipantDetails | Information about the participants (the sender and the recipient) |
customer | - | Customer | Payee's details |
metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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 Test",
"beneficiary_id": "123412341234"
},
"sender": {
"full_name": "Ivan Ivanovich Test",
"beneficiary_id": "123412341234"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"customer": {
"reference": "test"
}
}
Successful 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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Unsuccessful response example
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}
session/multi/start/payment/nominal
Payout or payment start
This request can be used to start a payout or a payment within an existing session. In the parameters, you can pass the data necessary to perform the payout or payment. Or 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/nominal
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
session_id | + | string | Payment session identifier |
payment_details | - | PaymentDetails | Transfer details |
payment_method | - | PaymentMethod | Payment details (card, customer account, etc.) |
customer | - | Customer | The recipient's data in your system. |
amount_details | - | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
fiscalization_details | - | FiscalizationDetails | Fiscalization details; only for payouts to the self-employed |
participant_details | - (mandatory for the payouts to card) | ParticipantDetails | Information about the participants (the sender and the recipient) |
metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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 Test"
},
"sender": {
"full_name": "Ivan Ivanovich Test"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"customer": {
"reference": "test"
}
}
Successful 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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Unsuccessful response example
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}
session/multi/init/payment/nominal
Session creation with simultaneous payout or payment 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 information about the payment (AcquiringPayment
).
Endpoint
/api/v1/session/multi/init/payment/nominal
Request parameters
Name | Mandatory | Type | Description |
---|---|---|---|
payment_details | + | PaymentDetails | Transfer details |
payment_method | + | PaymentMethod | Payment details (card, customer account, etc.) |
customer | + | Customer | The recipient's data in your system. |
amount_details | - | AmountDetails | The amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000 |
fiscalization_details | - | FiscalizationDetails | Fiscalization details; only for payouts to the self-employed |
participant_details | - (mandatory for the payouts to card) | ParticipantDetails | Information about the participants (the sender and the recipient) |
metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
Response parameters
Name | Mandatory | Type | Description |
---|---|---|---|
status | + | string | Status. Possible values: error , ok |
session | - | PaymentSession | The payment session |
error | - | Error | Error |
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: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-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 Test",
"beneficiary_id": "123412341234"
},
"sender": {
"full_name": "Ivan Ivanovich Test",
"beneficiary_id": "123412341234"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"customer": {
"reference": "test"
}
}
Successful 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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Unsuccessful response example
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}