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

NameMandatoryTypeDescription
payment_method-PaymentMethodPayment details (card, customer account, etc.)
amount_details-AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
fiscalization_details-FiscalizationDetailsFiscalization details; only for payouts to the self-employed
participant_details-ParticipantDetailsInformation about the participants (the sender and the recipient)
customerMandatory for paymentsCustomerThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
payment_method+PaymentMethodPayment details (card, customer account, etc.)
amount_details+AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
fiscalization_details-FiscalizationDetailsFiscalization details
participant_details-ParticipantDetailsInformation about the participants (the sender and the recipient)
customer-CustomerThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
payment-PaymentMethodPayout details (card, customer account etc.)
error-ErrorError

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

NameMandatoryTypeDescription
payment_method-PaymentMethodPayment details (card, customer account, etc.)
amount_details-AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
fiscalization_details-FiscalizationDetailsFiscalization details
participant_details-ParticipantDetailsInformation about the participants (the sender and the recipient)
customer-CustomerThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
payment-PaymentMethodPayout details (card, customer account etc.)
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_method-PaymentMethodPayout details (card, customer account, etc.)
amount_details-AmountDetailsThe amount
participant_details-ParticipantDetailsInformation on payout participants
customer-CustomerThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_method-PaymentMethodPayment details (card, customer account, etc.)
amount_details-AmountDetailsThe amount
fiscalization_details-FiscalizationDetailsFiscalization details
participant_details-ParticipantDetailsInformation on payout participants
customer-CustomerThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringPayment session identifier
fiscalization_details+FiscalizationDetailsFiscalization details
payment_method-PaymentMethodPayout details (card, customer account, etc.)
amount_details-AmountDetailsThe amount
participant_details-ParticipantDetailsInformation on payout participants
customer-CustomerThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
payment_details+PaymentDetailsPayment data
amount_details+AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
participant_details-ParticipantDetailsParticipants information
customer+CustomerClient data in your system
payment_options-PaymentOptionsAdditional payment parameters
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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.

NameMandatoryTypeDescription
payment_details+PaymentDetailsPayment data
type+stringPayment method type. Possible values: card
card+CardPaymentMethodObject containing bank card details
type+stringMethod of card information transmission. Value: bank_card
bank_card+BankCardObject with open card information
number+stringCard number
expiration_month+stringMonth of card expiration, MM. Example: 01
expiration_year+stringYear of card expiration, YY. Example: 22
security_code+stringCVC/CVV code
amount_details+AmountDetailsObject with payment amount
amount+intThe 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+stringThe ISO 4217 currency code. Case insensitive. Always: rub
participant_details-ParticipantDetailsParticipants information
customer+CustomerInformation about payment sender on your side
reference+stringPayment sender ID in your system
payment_options+PaymentOptionsAdditional payment parameters
return_url+stringThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_details-PaymentDetailsPayment data
amount_details-AmountDetailsThe amount
participant_details-ParticipantDetailsInformation about the participants (the payer and the recipient)
customer-CustomerPayment 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringSession identifier
confirm_information- (mandatory only for the trasactions with a nominal account)ConfirmInformationTransaction confirmation information

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringBank 131 session identifier
amount_details-AmountDetailsThe 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringSession identifier

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringThe identifier of a successful payment session which needs to be refunded.
amount_details-AmountDetailsThe amount of the refund. If not specified, the refund will be made for the full amount of the payment.
metadata-*Additional information

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
tokenize_widget-TokenizeWidgetMetadataThe data required by the tokenization widget
self_employed_widget-SelfEmployedWidgetMetadataThe data required by the self-employed registration widget
acquiring_widget-AcquiringWidgetMetadataThe data required by the payment form widget

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
public_token-stringThe public token
error-ErrorError

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

NameMandatoryTypeDescription
type+stringType of request. Options: card, public_token, recurrent_token
card- (mandatory for type = card)CardPaymentMethodObject containing bank card details
public_token- (mandatory for type = public_token)PublicTokenObject with token details
recurrent_token- (mandatory for type = recurrent_token)RecurrentTokenObject with recurrent token details

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
info-CardTokenInfo, PublicTokenInfo, or RecurrentTokenInfoInformation about the token, depending on the type of request (type)
error-ErrorError

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

NameMandatoryTypeDescription
recurrent+RecurrentTokenObject with a token

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
recurrent+RecurrentTokenInfoObject 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

NameMandatoryTypeDescription
session_id+stringPayment session identifier

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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 nominal account balance. You may find this information your your remote banking service account.

Endpoint

/api/v1/wallet/balance

Request parameters

NameMandatoryTypeDescription
request_datetime+stringThe timestamp of the request in ISO 8601

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
wallets-WalletDetailsThe list of guarantee payment accounts available at Bank 131.
error-ErrorError

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-PaymentMethodPayment details (card, customer account, etc.)
participant_details-ParticipantDetailsInformation about the participants (the sender and the recipient)

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
wallets-WalletDetailsThe list of guarantee payment accounts available at Bank 131.
error-ErrorError

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:

  1. First, you send a check request, passing the individual's INN in the tax_reference parameter, and receive a request_id identifier in response.
  2. 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

NameMandatoryTypeDescription
tax_reference+stringIndividual's INN

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id+stringRequest 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

NameMandatoryTypeDescription
request_id+stringThe identifier received in response to the check request

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
is_professional_income_taxpayer-boolShows whether the individual is self-employed
is_linked-boolShows whether the self-employed person is linked to Bank 131
error-Error objectError

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
}

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:

  1. First, you send a request in the npd/taxpayer/check_personal_info, passing a self-employes person's INN, full name, and phone number, and receive the request_id identifier in response;
  2. Then, you periodically send the npd/request/status request with this identifier. In response, you receive a list of inconsistent parameters, if there is any. The pending status indicates that you must repeat the request.

The endpoint to send the npd/taxpayer/check_personal_info request

/api/v1/npd/taxpayer/check_personal_info

Request parameters for npd/taxpayer/check_personal_info

NameMandatoryTypeDescription
first_name+stringFirst name
second_name+stringFamily name
patronymic+stringPatronymic name
tax_reference+stringTax reference number (INN)
phone+stringPhone number in the "7ХХХХХХХХХХ" format.

Response parameters

NameMandatoryTypeDescription
request_id+stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "first_name": "Test",
    "second_name": "Test",
    "patronymic": "Test",
    "tax_reference": "123456789012",
    "phone": "71234567890"
}'

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/taxpayer/check_personal_info

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
success-boolInconsistency 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 ErrorError

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

Response example

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

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:

  1. First, you send a request in the npd/notifications/count method, passing a self-employes person's details, and receive the request_id identifier in response;
  2. Then, you periodically send the npd/request/status request with this identifier. In response, you receive the number of unread notifications. The pending status indicates that you must repeat the request.

The endpoint to send the npd/notifications/count request

/api/v1/npd/notificaitons/count

Request parameters for npd/notifications/count

NameMandatoryTypeDescription
tax_reference_list+arrayList of tax reference numbers (INN) (limited to 1000 per single request)

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id+stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "tax_reference_list": ["123456789012"]
    }

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/count

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
info-array<NotificationCountInformation>

The npd/request/status request example

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"
}

Response example

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

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:

  1. First, you send a request in the npd/notifications/read method, passing a self-employes person's details, and receive the request_id identifier in response;
  2. Then, you periodically send the npd/request/status request with this identifier. In response, you receive the detailed information about unread notifications. The pending status indicates that you must repeat the request.

The endpoint to send the npd/notifications/read request

api/v1/npd/notifications/read

Request parameters for npd/notifications/read

NameMandatoryTypeDescription
tax_reference_list+arrayList of tax reference numbers (INN)
get_read+booleanSend the already read notifications in response. Possible values: true — send; false — do not send.
get_archived+booleanSend the archived notificatrions in response. Possible values: true — send; false — do not send.

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id+stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "tax_reference_list": ["123456789012"],
    "get_read": false,
    "get_archived":  false
}

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/read

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
info-array<NotificationInformation>List of parameters for each tax reference number (INN)

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

Response example

{
    "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/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 methos must be used after the notifications/read method.

The request consists of two parts:

  1. First, you send a request in the npd/notifications/mark_as_delivered method, passing a self-employes person's details, and receive the request_id identifier in response;
  2. Then, you send the npd/request/status request with this identifier. In response, you 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

NameMandatoryTypeDescription
notification_list+array<Notification_list>Information about notifications

Response parameters

NameMandatoryTypeDescription
request_id+stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "notification_list": [
        {
            "message_id_list": ["123", "234"],
            "tax_reference": "123456789012"
        }
    ]
}

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/read

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

Response example

{
    "status": "ok"
}

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:

  1. First, you send a request in the npd/notifications/update method, passing a self-employes person's details, and receive the request_id identifier in response.
  2. Then, you send the npd/request/status request with this identifier. In response, you 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

NameMandatoryTypeDescription
notification_list+array<Notification_list>Information about notifications

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id-stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "notification_list": [
        {
            "tax_reference": "123456789012"
        }
    ]
}

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/update

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

Response example

{
    "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:

  1. First, you send a request in the npd/taxpayer/account_status method, passing a self-employes person's details, and receive the request_id identifier in response.
  2. Then, you send the npd/request/status request with this identifier. In response, you receive the 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

NameMandatoryTypeDescription
tax_reference+stringTax reference number (INN). Limited to 1 INN per single request.

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id-stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
            "tax_reference": "123456789012"
    }

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/taxpayer/account_status

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
bonus_amount-stringBonus amount
unpaid_amount-stringTotal unpaid amount
debt_amount-stringUnpaid debt, included into total unpaid amount

Request example

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"
}

Response example

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

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:

  1. First, you send a request in the npd/accruals method, passing a self-employes person's details, and receive the request_id identifier in response.
  2. Then, you send the npd/request/status request with this identifier. In response, you receive the 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 parameter for npd/accruals

NameMandatoryTypeDescription
tax_reference_list+arrayList of tax reference numbers (INN). Limited to 100 INNs per single request.

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id-stringIdentifier

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{ 
    "tax_reference_list":["111111111111"] 
}

Response example

{
    "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

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/accruals

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
accruals-jagged array
tax_charge_list-arrayList of various taxes accrued
amount-stringAccrued amount
due_date-stringPayment due date
tax_period_id-stringTax period identifier. The value format: YYYYMM
oktmo-stringRussian National Classification of Municipal Territories (OKTMO) of the activity region
kbk-stringBudgetary classification code
paid_amount-stringThe amount of payments received in Automated Information System (AIS) Tax 3 by this accrual
create_time-stringDate and time of the tax accrual
id-stringInternal identifier of the tax accrual in the Self-employment tax (NPD) Payment order (PP)
krsb_list-arrayDebt data by the fiscal compliance card
debt-stringDebt amount by the fiscal compliance card
penalty-stringPenalty amount by the fiscal compliance card
overpayment-stringOverpayment amount by the fiscal compliance card
oktmo-stringRussian National Classification of Municipal Territories (OKTMO) of the activity region related to the fiscal compliance card (KRSB)
kbk-stringBudgetary classification code related to the fiscal compliance card (KRSB)
tax_organ_code-stringCode of the tax authority related to the fiscal compliance card (KRSB)
update_time-stringDate / Time of card revision in the Self-employment tax (NPD) Payment order (PP)
id-stringInternal identifier of the card in the Self-employment tax (NPD) Payment order (PP)
inn-stringTax reference number (INN)

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: project' \
  -H 'X-PARTNER-SIGN: rsa-signature' \
  -d '{
    "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

Response example

{ 
    "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" 
        } 
    ] 
}

Taxes

alias/ru_vat_lite

VAT payment

This method allows paying VAT which is related to the delivery of e-services to Russian consumers, with Bank 131.

VAT payment will be transferred to these bank details:

BIC: 004525988
Treasury Account: 03100643000000017300
Treasury Single Account: 40102810545370000003
Recipient: Federal Treasury Directorate for Moscow (FTS of Russia Interregional Inspectorate for Large Taxpayers 7)
INN: 7707500730
KPP: 770701001

Endpoint

/api/v1/alias/ru_vat_lite

Request parameters

NameMandatoryTypeDescription
period_type+stringThe tax period.
period_number+stringThe period type. Possible values: month, quarter.
period_year+stringDepends upon period type. Number from 1 to 12 for month, number from 1 to 4 for quarter.
amount+stringThe tax amount in ruble decimal format. The value must be greater than zero. If you are sending 100 rubles, you will need to specify 10000.
currency+stringThe currency code. Always rub.

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

Request example

curl --location --request POST 'https://demo.bank131.ru/api/v1/alias/ru_vat_lite' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: project' \
--data-raw '{
    "period_type": "quarter",
    "period_number": "4",
    "period_year": "2020",
    "amount": 20000,
    "currency": "rub"
}'

Response example

{
    "status": "ok",
    "session": {
        "id": "ps_2909",
        "status": "in_progress",
        "created_at": "2018-05-27T03:02:00.935351Z",
        "updated_at": "2018-05-27T03:02:00.935351Z",
        "payments": [
            {
                "id": "po_3230",
                "status": "in_progress",
                "created_at": "2018-05-27T03:02:00.935351Z",
                "payment_method": {
                    "type": "tax",
                    "tax": {
                        "type": "tax_short",
                        "tax_short": {
                            "tax_details": {
                                "period": {
                                    "type": "quarter",
                                    "number": 4,
                                    "year": "2020"
                                }
                            }
                        }
                    }
                },
                "amount_details": {
                    "amount": 20000,
                    "currency": "rub"
                }
            }
        ]
    }
}

Nominal 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

NameMandatoryTypeDescription
payment_details+PaymentDetailsTransfer details
payment_method+PaymentMethodPayment details (card, customer account, etc.)
customer+CustomerThe recipient's data in your system.
amount_details-AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
fiscalization_details-FiscalizationDetailsFiscalization details; only for payouts to the self-employed
participant_details- (mandatory for the payouts to card)ParticipantDetailsInformation about the participants (the sender and the recipient)
customer-CustomerPayee's details
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks

Response parameters

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_details-PaymentDetailsTransfer details
payment_method-PaymentMethodPayment details (card, customer account, etc.)
customer-CustomerThe recipient's data in your system.
amount_details-AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
fiscalization_details-FiscalizationDetailsFiscalization details; only for payouts to the self-employed
participant_details- (mandatory for the payouts to card)ParticipantDetailsInformation 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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

NameMandatoryTypeDescription
payment_details+PaymentDetailsTransfer details
payment_method+PaymentMethodPayment details (card, customer account, etc.)
customer+CustomerThe recipient's data in your system.
amount_details-AmountDetailsThe amount. Transmitted in the ruble decimal format. If you are sending 100 rubles, you will need to specify 10000
fiscalization_details-FiscalizationDetailsFiscalization details; only for payouts to the self-employed
participant_details- (mandatory for the payouts to card)ParticipantDetailsInformation 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

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-PaymentSessionThe payment session
error-ErrorError

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"
}
← ObjectsWebhooks →