Перейти к основному содержимому

Методы

При обработке запросов проверяется корректность входных параметров, наличие необходимых заголовков, права на выполнение действий.

Проведение операций

session/create

Cоздание платежной сессии

Этот запрос создает платежную сессию на стороне Банка 131.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций одного или разных типов (например, несколько выплат, платеж и возврат, оплата с последующим разделением платежей).

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или оплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (session/start/payout) или оплата (session/start/payment). В этом случае запускать операцию отдельным запросом не нужно.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса

api/v1/session/create

Параметры запроса

НазваниеОбязательностьТипОписание
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
payment_details-PaymentDetailsПлатежные данные
amount_details-AmountDetailsСумма. Передается в минорных единицах. Если отправляете 100 рублей, евро или долларов США, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
participant_details-ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customerОбязательно для платежейCustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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

Пример успешного ответа

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

Пример неуспешного ответа

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

session/init/payout

Cоздание сессии с одновременным стартом выплаты

Можно использовать этот запрос, если вы сразу готовы передать все параметры для создания выплаты. Например, при отправке выплаты на российский банковский счет. При выплате на банковскую карту — только если у вас есть PCI DSS.

Также можно стартовать выплату с использованием токена, который был получен при создании рекуррентного платежа

В ответе возвращаются параметры созданной сессии и объект с информацией о выплате (Payment).

Адрес для отправки запроса

/api/v1/session/init/payout

Параметры запроса

НазваниеОбязательностьТипОписание
payment_method+PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details+AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации
participant_details-ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customer+CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
payment-PaymentMethodПлатёжные данные (карта, банковский счёт и др.)
error-ErrorОшибка

Пример запроса

  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);

Пример успешного ответа

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

Создание сессии и старт выплаты с дополнительной проверкой заполненности данных для фискализации

Можно использовать при выплатах самозанятым, если вы сразу готовы передать всю информацию о самозанятом и платежные данные для создания выплаты. Например, при отправке выплаты на российский банковский счет. При выплате на банковскую карту — только если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии, объект с информацией о выплате (Payment) с данными для отправки чека.

Адрес для отправки запроса

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

НазваниеОбязательностьТипОписание
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации
participant_details-ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
payment-PaymentMethodПлатёжные данные (карта, банковский счёт и др.)
error-ErrorОшибка

Пример запроса

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(
'Доставка товара',
new Amount(5000, 'rub'),
1
);

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

$incomeInformation->setPayerName('ООО Рога и Копыта');
$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);

Пример успешного ответа

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

Пример неуспешного ответа

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

session/start/payout

Старт выплаты

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения выплаты или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса

/api/v1/session/start/payout

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_method-PaymentMethodПлатежные данные (карта, банковский счёт и др.)
amount_details-AmountDetailsСумма
participant_details-ParticipantDetailsИнформация об участниках выплаты
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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);

Пример успешного ответа

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

Старт выплаты с проверкой на заполненность данных для фискализации

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения выплаты или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса

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

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
amount_details-AmountDetailsСумма
fiscalization_details-FiscalizationDetailsДанные для фискализации
participant_details-ParticipantDetailsИнформация об участниках выплаты
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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": "ООО Рога и Копыта",
"services": [
{
"name": "Доставка товара",
"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(
'Доставка товара',
new Amount(5000, 'rub'),
1
);

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

$incomeInformation->setPayerName('ООО Рога и Копыта');
$incomeInformation->setPayerType('legal');
$incomeInformation->setPayerTaxNumber('330000000000');

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

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

Пример успешного ответа

{
"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": "Доставка товара",
"amount_details": {
"amount": 5000,
"currency": "rub"
},
"quantity": 1
}
],
"tax_reference": "590613976192",
"payer_type": "legal",
"payer_tax_number": "3316004710",
"payer_name": "ООО Рога и Копыта"
}
}
}
]
}
}

fiscalization

Фискализация без выплаты

Этот запрос можно использовать, чтобы зарегистрировать выплату самозанятому в налоговой и получить ссылку на чек. Саму выплату проводить не нужно (можно провести до или после, любым удобным способом).

Чтобы отправить запрос на фискализацию, нужно сначала создать платежную сессию и получить идентификатор сессии (session_id).

Адрес для отправки запроса

/api/v1/fiscalization

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
fiscalization_details+FiscalizationDetailsДанные для фискализации
payment_method-PaymentMethodПлатежные данные (карта, банковский счёт и др.)
amount_details-AmountDetailsСумма
participant_details-ParticipantDetailsИнформация об участниках выплаты
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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": "ООО Рога и Копыта",
"services": [
{
"name": "Доставка товара",
"amount_details": {
"amount": 5000,
"currency": "rub"
}
},
{
"name": "Доставка сырья",
"amount_details": {
"amount": 5000,
"currency": "rub"
}
}
]
}
}
}'

Пример успешного ответа

{
"status": "ok",
"session": {
"id": "ps_2704",
"status": "in_progress",
"created_at": "2021-05-27T08:13:33.736384Z",
"updated_at": "2021-05-27T08:13:33.871729Z",
"payments": [
{
"id": "po_2705",
"status": "in_progress",
"created_at": "2021-05-27T08:13:33.860754Z",
"amount_details": {
"amount": 15000,
"currency": "rub"
},
"fiscalization_details": {
"professional_income_taxpayer": {
"services": [
{
"name": "Доставка товара",
"amount_details": {
"amount": 5000,
"currency": "rub"
},
"quantity": 2
},
{
"name": "Доставка сырья",
"amount_details": {
"amount": 5000,
"currency": "rub"
},
"quantity": 1
}
],
"tax_reference": "123456789012",
"payer_type": "legal",
"payer_tax_number": "3316004777",
"payer_name": "ООО Рога и Копыта"
}
}
}
]
}
}

session/init/payment

Создание сессии с одновременным стартом платежа

Можно использовать, если вы сразу готовы передать все параметры, необходимые для оплаты. Например, при оплате банковской картой, если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект с информацией о платеже (AcquiringPayment).

Параметры запроса

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsПлатежные данные
amount_details+AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_details-ParticipantDetailsИнформация об участниках
customer+CustomerДанные клиента вашей системе
payment_options-PaymentOptionsДополнительные параметры платежа
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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);

Пример успешного ответа

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

Пример неуспешного ответа

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

session/init/payment/sync

Данный метод не рекомендуется к использованию, кроме тех случаев, когда он уже был реализован вами ранее.

Платеж одним запросом

Этот метод позволяет отправить запрос на оплату и сразу получить ответ. Можно использовать, если вы готовы в этом запросе передать все параметры для оплаты. Например, при оплате банковской картой, если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект AcquiringPayment с результатом платежа и всей информацией о нем.

Параметры запроса

Здесь перечислены только обязательные параметры запроса. Дополнительные параметры есть по ссылкам в описании объектов.

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsПлатежные данные
type+stringТип способа оплаты. Возможные варианты: card
card+CardPaymentMethodОбъект с данными банковской карты
type+stringСпособ передачи данных карты. Значение: bank_card
bank_card+BankCardОбъект с данными карты в открытом виде
number+stringНомер карты
expiration_month+stringМесяц, до которого действует карта, в формате ММ. Например 01
expiration_year+stringМесяц, до которого действует карта, в формате ГГ. Например 22
security_code+stringСекретный код CVC или CVV
amount_details+AmountDetailsОбъект с данными для суммы платежа
amount+intСумма в копейках. Значение должно быть больше нуля. Если сумма оплаты 100 рублей, нужно передать 10000
currency+stringКод валюты согласно ISO 4217. Регистр не важен. Всегда: rub
participant_details-ParticipantDetailsИнформация об участниках
customer+CustomerДанные отправителя платежа на вашей стороне
reference+stringИдентификатор отправителя платежа в вашей системе
payment_options+PaymentOptionsДополнительные параметры платежа
return_url+stringURL, на который нужно перенаправить пользователя после проведения платежа. URL должен быть валидным
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

curl --location --request POST 'https://proxy.bank131.ru/api/v1/session/init/payment/sync' \
--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"
}
}'

Пример успешного ответа

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

Пример неуспешного ответа

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

session/start/payment

Старт платежа

Этот запрос можно использовать, чтобы начать платеж в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения оплаты или заменить уже переданные.

Адрес для отправки запроса

/api/v1/session/start/payment

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_details-PaymentDetailsПлатежные данные
amount_details-AmountDetailsСумма
participant_details-ParticipantDetailsИнформация об участниках (отправителе и получателе платежа)
customer-CustomerДанные отправителя платежа в вашей системе
payment_options-PaymentOptionsДополнительные параметры платежа
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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);

Пример успешного ответа

{
"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 (confrm_request)

Подтверждение операции

Этот запрос можно отправлять, когда Банк 131 готов провести операцию — выплату или платеж. Например, вы получили вебхук ready_to_confirm.

Вам нужно проверить параметры операции и принять решение. Если всё в порядке, подтвердите операцию: отправьте Банку confirm_request. Если что-то не так, отмените операцию: отправьте запрос cancel_request.

Адрес для отправки запроса

/api/v1/session/confirm

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии
confirm_information- (обязательно при операциях с номинальным счетом и при requier_confirm_information = true)ConfirmInformationИнформация для подтверждения операции

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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');

Пример ответа

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

Списание захолдированной суммы

Этот запрос можно использовать, если вы отправляете холдированные платежи. Такой платеж проходит в две стадии: сначала деньги замораживаются (например, на банковской карте пользователя), а потом списываются по вашей команде.

Запрос можно отправлять, когда Банк 131 готов списать деньги и прислал вам вебхук ready_to_capture.

Если вы хотите списать замороженную сумму, отправьте запрос capture_request. Можно списать замороженную сумму или меньше.

Чтобы отменить списание, отправьте cancel_request.

Адрес для отправки запроса

/api/v1/session/capture

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии Банка 131
amount_details-AmountDetailsСумма к списанию. Может быть меньше захолдированной, но обязательно больше 0. Если параметр отсутствует, то захолдированная сумма будет списана полностью.

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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)

Отмена операции

Этот запрос можно отправлять, когда Банк 131 готов провести операцию — выплату или платеж. Например, вы получили вебхук ready_to_confirm или ready_to_capture.

Если не хотите проводить эту операцию, можете ее отменить: отправьте запрос cancel_request.

Если всё в порядке, отправьте запрос на подтверждение операции (confirm_request) или на списание замороженной суммы (capture_request).

Адрес для отправки запроса

/api/v1/session/cancel

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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');

Пример ответа

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

Возврат

С помощью этого запроса можно вернуть деньги пользователю после успешного платежа.

После проведения возврата Банк 131 отправит вам вебхук payment_refunded.

Адрес для отправки запроса

/api/v1/session/refund

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор успешной платежной сессии, по которой необходимо провести возврат.
amount_details-AmountDetailsСумма возврата. Если не указывать, то возврат будет на полную сумму платежа.
metadata-*Дополнительная информация

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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);

Пример ответа

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

Генерация публичного токена для работы с виджетами

Токен нужен для доступа к JavaScript-библиотеке Банка 131. Вы можете сгенерировать его этим запросом и использовать для работы с виджетами.

Токен действителен 24 часа. Его можно использовать для одной операции. При отправке запроса следует передать параметры для работы с виджетами, которые вы собираетесь использовать с этим токеном.

Адрес для отправки запроса

/api/v1/token

Параметры запроса

НазваниеОбязательностьТипОписание
tokenize_widget-TokenizeWidgetMetadataДанные для работы виджета токенизации
self_employed_widget-SelfEmployedWidgetMetadataДанные для работы виджета регистрации самозанятого
acquiring_widget-AcquiringWidgetMetadataДанные для работы виджета платежной формы

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
public_token-stringПубличный токен
error-ErrorОшибка

Пример запроса на создание токена для проведения выплаты с получением данных карты через виджет и с привязкой самозанятого

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();

Пример запроса на создание токена для проведения платежа с оплатой через платежную форму

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

Пример успешного ответа

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

Пример неуспешного ответа

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

token/info

Получение информации по токену

Операции с банковскими картами часто проводятся с токенизированными данными. При выплатах и платежах через виджеты создается публичный токен, при рекуррентных платежах — рекурентный токен.

По любому платежному токену можно получить информацию:

  • о банковской карте, для которой создан этот токен — это будет маскированный номер карты и платежная система,
  • или о самом токене — тип токена, время создания, срок действия, активен ли этот токен на момент запроса.

Этот метод можно использовать, чтобы, например, узнать маскированный номер карты и показать пользователю, с какой карты спишутся деньги по подписке. Или если понадобится проверить срок действия токена.

Адрес для отправки запроса

/api/v1/token/info

Параметры запроса

НазваниеОбязательностьТипОписание
type+stringТип запроса. Варианты: card, public_token, recurrent_token
card- (обязателен для type = card)CardPaymentMethodОбъект с данными банковской карты
public_token- (обязателен для type = public_token)PublicTokenОбъект с данными токена
recurrent_token- (обязателен для type = recurrent_token)RecurrentTokenОбъект с данными рекуррентного токена

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
info-CardTokenInfo, PublicTokenInfo или RecurrentTokenInfoИнформация о токене, зависит от типа запроса (type)
error-ErrorОшибка

Запрос информации о карте по токену

Пример запроса

Вы отправляете токенизированные данные банковской карты и получаете маску карты и платежную систему.

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

Пример ответа

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

Запрос информации о публичном токене

Пример запроса

Вы отправляете публичный токен и получаете информацию о нем.

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

Пример ответа

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

Запрос информации о рекуррентном токене

Пример запроса

Вы отправляете рекуррентный токен и получаете информацию о нем.

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

Пример ответа

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

tokenize/elements

Метод для токенизации номера карты с хранением токенизированных данных на стороне Банка 131.

Метод доступен только для мерчантов с PCI DSS. Для использования этого метода нужно обратиться к вашему менеджеру в Банке 131.

Адрес для отправки запроса

/api/v1/tokenize/elements

Параметры запроса

НазваниеОбязательностьТипОписание
card_elements+CardElementsОбъект с номером банковской карты для токенизации

Пример запроса

Пример запроса
curl --location 'https://proxy-stage.bank131.ru/cds/v1/tokenize/elements' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-PROJECT: shop1' \
--header 'X-PARTNER-SIGN: key' \
--data '{
"card_elements": [
{
"ref": "number",
"type": "card_number",
"card_number": "4242424242424242"
}
]
}'

Пример ответа

Пример ответа
{
"status": "ok",
"data": {
"number": {
"token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919",
"info": {
"masked_card_number": "424242******4242",
"card_network": "visa",
"card_type": "visa"
}
}
}
}

tokenize

Метод для токенизации банковского счета (выплаты). Используйте его, чтобы получить токен и маскированный номер счета. Токен, полученный в ответе, не имеет срока действия.

Вы можете токенизировать любой счет, который пройдет проверку на соответствие заданному диапазону счетов. В противном случае вернется ошибка "Введите другой номер счета".

Адрес для отправки запроса

/api/v1/tokenize

Параметры запроса

ПараметрТипОписание
typestringТип банковского счета
bank_account_ruBankAccountRUОбъект дополнительной информации о банковском счете
bikstringБИК банка
accountstringНомер счета

Параметры ответа

ПараметрТипОписание
statusstringТип банковского счета
tokenstringТокен
dataDataОбъект с маскированным счетом
errorErrorОбъект с описанием ошибки

Пример запроса

curl --location 'https://proxy-stage.bank131.ru/api/v1/tokenize' \
--header 'X-PUBLIC-TOKEN: public token' \
--header 'Content-Type: application/json' \
--data '{
"type": "bank_account_ru",
"bank_account_ru": {
"bik": "044525974",
"account": "40817810400003869535"
}
}'

Пример успешного ответа

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

Пример неуспешного ответа

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

recurrent/disable

Отключение рекуррентного токена

С помощью этого запроса можно отключить рекуррентный токен. Отправьте в запросе токен, в ответ придет is_active: false. Это значит, что с этим токеном больше нельзя проводить рекуррентные платежи.

После отключения токена в параметре даты окончания действия токена finished_at может появиться дата, относящаяся к 2000 году — она ни на что не влияет, можно не обращать на неё внимание.

Адрес для отправки запроса

/api/v1/recurrent/disable

Параметры запроса

НазваниеОбязательностьТипОписание
recurrent+RecurrentTokenОбъект с токеном, который нужно отключить

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
recurrent+RecurrentTokenInfoОбъект с токеном

Пример запроса

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);

Пример ответа

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

Информация

session/status

Получение информации по сессии

Вы можете отправить этот запрос, если хотите получить полную информацию о платежной сессии. Например, проверить, прошла выплата или нет. Или узнать, можно ли списывать сумму, захолдированную при оплате картой.

В ответ на запрос приходит платежная сессия с данными обо всех операциях, которые проводились в ее рамках.

Адрес для отправки запроса

/api/v1/session/status

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса 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');

Пример успешного ответа

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

С помощью этого запроса можно узнать ваш текущий баланс на депозите в Банке 131.

Это нужно, чтобы убедиться, что на депозите достаточно денег:

  • для проведения массовых выплат;
  • для проведения возвратов.

Если денег недостаточно, вы можете пополнить депозит.

Данный метод не передает информацию о балансе номинального счета. Эта информация доступна в вашем аккаунте ДБО.

Адрес для отправки запроса

/api/v1/wallet/balance

Параметры запроса

НазваниеОбязательностьТипОписание
request_datetime+stringТекущее время запроса в формате ISO 8601

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
wallets-WalletDetailsСписок доступных счетов обеспечения в Банке 131
error-ErrorОшибка

Пример запроса

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();

Пример ответа

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

report/account_balance

Используйте этот метод, чтобы запросить баланс по вашему расчетному или номинальному счету. Чтобы узнать больше, переходите по ссылке.

Адрес для отправки запроса

/api/v1/report/account_statement

Параметры запроса

НазваниеОбязательностьТипОписание
account_number+stringНомер счета. Счет должен начинаться с цифр: 40702, 40703, 40802, 40807, 40701

Пример запроса

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

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
account_number-stringНомер счета
account_currency-stringВалюта счета согласно ISO 4217. Пример: RUB
balance-BalanceDetailsИнформация о балансе
error-ErrorОшибка

Примеры ответов

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

report/account_statement

Используйте этот метод, чтобы запросить выписку по расчетному или номинальному счету в рублях. Выписку можно получить по данным за одни сутки. Чтобы узнать больше, переходите по ссылке.

Адрес для отправки запроса

/api/v1/report/account_statement

Параметры запроса

НазваниеОбязательностьТипОписание
X-PARTNER-PROJECT+stringИдентификатор проекта. Выдается менеджером Банка 131
X-PARTNER-SIGN+stringПодпись запроса
date_from+dateДата начала выписки. Пример: 2023-06-01
date_to+dateДата окончания выписки. Пример: 2023-06-01
account_number+stringНомер счета (20 цифр), по которому запрашивается выписка

Значения в date_from и date_to должны совпадать.

Пример запроса

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

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
name+stringНазвание метода account_statement
account_statement+AccountStatementДетали выписки
  date_from+dateДата начала выписки
  date_to+dateДата окончания выписки
  account_number+stringНомер счёта (20 цифр), по которому сформирована выписка
total_turnover+TotalTurnoverИнформация по движению средств
  debet+intСумма списаний по счёту за период выписки
  credit+intСумма пополнений по счёту за период выписки
total_balance+TotalBalanceИнформация по балансу
  opening+intВходящий остаток по счёту на дату начала выписки
  closing+intИсходящий остаток по счёту на дату окончания выписки
transactions+TransactionsСписок транзакций
  amount+intСумма транзакции (только неотрицательные значения)
  base_amount-intСумма операции в валюте. Заполняется только для транзакций в валюте, отличной от рублей. При использовании базовой валюты (RUB) параметр является необязательным
  currency+stringВалюта операции
  payment_date+dateДата операции
  bank_system_id+stringИдентификатор платежа. Указывается для любого движения денежных средств по счету:
- для платежей, отправленных по API
- для переводов из другого банка
- для платежей, совершенных через ДБО
  transaction_id-stringИдентификатор транзакции. Передается для платежей, отправленных по API
  session_id-stringИдентификатор сессии. Передается для платежей, отправленных по API
  purpose+stringНазначение платежа
counter_party+CounterPartyИнформация о контрагенте
  kpp-stringКПП контрагента
  inn-stringИНН контрагента
  name+stringНаименование контрагента
  account_number+stringНомер счета контрагента
  bank_code+stringБИК банка контрагента
  type+stringТип транзакции. Может принимать знения credit (для операции пополнения) или debet (для операции списания)

Пример успешного ответа

{
"status": "ok",
"method": {
"name": "account_statement",
"account_statement": {
"date_from": "2022-11-12T18:19:32.487+0000",
"date_to": "2022-11-13T18:19:32.487+0000",
"account_number": "40703810500000000025",
"total_turnover": {
"debet": 0,
"debet_base": null,
"credit": 100,
"credit_base": null
},
"total_balance": {
"opening": 0,
"opening_base": null,
"closing": 100,
"closing_base": null
},
"transactions": [
{
"amount": 10000,
"base_amount": null,
"currency": "RUB",
"payment_date": "2022-11-13",
"bank_system_id": "2080040097819020",
"transaction_id": "c7b923ec-844f-4d98-ad02-795d62fe1989",
"session_id": "5aa0e1fe-3ccb-4e0e-ba4e-018649f81983",
"purpose": "Пополнение счета для тестов",
"counter_party": {
"kpp": "165501001",
"inn": "1655415696",
"name": "Плата за услуги процессинга по переводам без открытия счета",
"account_number": "70606810600004710401",
"bank_code": "049205131"
},
"type": "credit"
}
]
}
}
}

Примеры неуспешных ответов

date_from не равна date_to

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

date_from больше date_to

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

Невалидная дата в date_from


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

Невалидная дата в date_to


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

fps/banks

С помощью этого запроса вы можете получить список наименований и идентификаторов банков-участников Системы быстрых платежей.

Адрес для отправки запроса

/api/v1/fps/banks

Пример запроса

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 '{}'

Пример ответа

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

fps/customer_verification

С помощью этого запроса можно проверить зарегистрирован ли получатель в Системе Быстрых Платежей. Если пользователь найден в СБП, то сессия примет успешный статус, иначе сессия отменится. Эта операция не тарифицируется и подтверждается автоматически (вебхук ready_to_confirm не отправляется).

Адрес для отправки запроса

/api/v1/fps/customer_verification

Параметры запроса

НазваниеОбязательностьТипОписание
payment_method+PaymentMethodПлатежные данные (карта, банковский счёт и др.)
participant_details+ParticipantDetailsИнформация об участниках выплаты

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса


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": "Иванович"
}
}
}

Пример ответа

{
"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": "Иванович"
}
}
}
]
}
}

Самозанятые

check и request/status

Проверка статуса самозанятого

Этот запрос позволяет проверить по ИНН, является физлицо самозанятым или нет.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос check, передаете в параметре tax_reference ИНН физлица и получаете в ответ идентификатор request_id.
  2. Затем отправляете запрос request/status с этим идентификатором. В ответе придет информация, зарегистрирован ли этот ИНН в налоговой как самозанятый и привязан ли он к Банку 131.

Запрос check не следует отправлять чаще, чем раз в 30 секунд.

Адрес для отправки запроса check

/api/v1/npd/check

Параметры запроса check

НазваниеОбязательностьТипОписание
tax_reference+stringИНН физлица

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
request_id+stringИдентификатор запроса

Пример запроса 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"
}'

Пример ответа на check

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

Адрес для отправки запроса request/status

api/v1/npd/request/status \

Параметры запроса request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос check

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
is_professional_income_taxpayer-boolЯвляется ли физлицо самозанятым
is_linked-boolПривязан ли самозанятый к Банку 131
error-object ErrorОшибка

Пример запроса request/status для 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"
}'

Пример ответа на request/status для check: физлицо является самозанятым и привязано к Банку 131

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

Пример ответа на request/status для check: физлицо является самозанятым и не привязано к Банку 131

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

npd/taxpayer/check_personal_info и npd/request/status

Проверка соответствия данных самозанятого

Запрос позволяет проверить соответвие данных (ИНН, ФИО, номер телефона) самозанятого с теми, которые имеются в ФНС.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/taxpayer/check_personal_info, передаете в параметрах ИНН, ФИО и номер телефона самозанятого, и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет информация о возможных расхождениях с данными, которые есть у ФНС.

Адрес для отправки запроса npd/taxpayer/check_personal_info

/api/v1/npd/taxpayer/check_personal_info

Параметры запроса npd/taxpayer/check_personal_info

НазваниеОбязательностьТипОписание
first_name+stringИмя самозанятого
second_name+stringФамилия самозанятого
patronymic+stringОтчество самозанятого
tax_reference+stringИНН самозанятого
phone+stringНомер телефона самозанятого. Формат: "7ХХХХХХХХХХ".

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
request_id-stringИдентификатор, который пришел в ответ на запрос 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",
"first_name": "Test",
"patronymic": "Test",
"tax_reference": "123456789012",
"phone": "71234567890"
}'

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/check_personal_info

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
success-booleanРасхождение в параметрах. true - расхождение не обнаружено; false - обнаружено расхождение.
violations-array\<string>Массив с названиями параметров, в значениях которых обнаружены расхождения. Возможные значения: "first_name", "second_name", "patronymic", "tax_reference", "phone"
error-object ErrorОшибка

Пример запроса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"
}

Пример ответа

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

npd/notifications/count и npd/request/status

Метод для получения количества непрочитанных оповещений из ФНС для самозанятых.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/count, передаете в параметрах ИНН и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет информация о количестве непрочитанных оповещений.

Адрес для отправки запроса npd/notifications/count

/api/v1/npd/notificaitons/count

Параметры запроса npd/notifications/count

НазваниеОбязательностьТипОписание
tax_reference_list+arrayСписок ИНН (не более 1000 штук в одном запросе)

Параметры ответа

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/count

Пример запроса 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"]
}

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/count

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
info-array<NotificationCountInformation>

Пример запроса 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"
}

Пример ответа

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

npd/notifications/read и npd/request/status

Метод для получения подробной информации о непрочитанных оповещениях для самозанятых из ФНС.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/read, передаете в параметрах ИНН и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет информация о непрочитанных оповещениях для самозанятых из ФНС.

Адрес для отправки запроса npd/notifications/read

api/v1/npd/notifications/read

Параметры запроса npd/notifications/read

НазваниеОбязательностьТипОписание
tax_reference_list+arrayСписок ИНН
get_read+booleanВыводить в ответе уже прочитанныхе оповещения. Возможные варианты: true — выводить; false — не выводить.
get_archived+booleanВыводить в ответе архивные оповещения. Возможные варианты: true — выводить; false — не выводить.

Параметры ответа

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/read

Пример запроса 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
}

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/read

Параметры ответа

НазваниеОбязательностьТипОписание
s--------s+------------+s----------------------------------------------------------------------------------------gС----------------------------`
info-array<NotificationInformation>Список параметров для ИНН

Пример запроса 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"
}

Пример ответа

{
"status": "ok",
"info": [
{
"tax_reference": "123456789012",
"notifications": [
{
"id": "132313",
"title": "131.ru запрашивает разрешение на осуществление определенных действий от Вашего имени",
"message": "131.ru запросил у Вас разрешение на осуществление определенных действий от Вашего имени. Вы можете ознакомиться с перечнем запрошенных разрешений и дать свое согласие (уполномочить 131.ru), нажав кнопку \"Разрешить\", или отказать ему, нажав кнопку \"Отказать\".",
"status": "NEW",
"created_at": "2023-03-22T13:29:55+00:00"

}
]
}
]
}

npd/notifications/mark_as_delivered и npd/request/status

Метод для отправки в ФНС уведомления о доставке оповещений самозанятому. Метод необходимо вызывать после метода notifications/read.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/mark_as_delivered, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет статус доставки.

Адрес для отправки запроса npd/notifications/mark_as_delivered

/api/v1/npd/notifications/mark_as_delivered

Параметры запроса npd/notifications/mark_as_delivered

НазваниеОбязательностьТипОписание
notification_list+array<Notification_list>Данные об оповещениях

Параметры ответа

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/mark_as_delivered

Пример запроса 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"
}
]
}

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/mark_as_delivered

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending

Пример запроса 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"
}

Пример ответа

{
"status": "ok"
}

npd/notifications/update и npd/request/status

Метод для отправки в ФНС уведомления о том, что оповещение было прочитано самозанятым. Метод необходимо вызывать после метода notifications/mark_as_delivered.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/notifications/update, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет статус отправки.

Адрес для отправки запроса npd/notifications/update

/api/v1/npd/notifications/update

Параметры запроса npd/notifications/update

НазваниеОбязательностьТипОписание
notification_list+array<Notification_list>Данные об оповещениях

Параметры ответа

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/update

Пример запроса 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"
}
]
}

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/notifications/update

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending

Пример запроса 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"
}

Пример ответа

{
"status": "ok"
}

npd/taxpayer/account_status и npd/request/status

Метод для получения общей информации о наличии налоговой задолженности и остатке налогового бонуса у самозанятых.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/taxpayer/account_status, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет общая информация о наличии налоговой задолженности и остатке налогового бонуса у самозанятого.

Адрес для отправки запроса npd/taxpayer/account_status

/api/v1/npd/taxpayer/account_status

Параметры запроса npd/taxpayer/account_status

НазваниеОбязательностьТипОписание
tax_reference+stringИНН самозанятого. Не более 1 ИНН в запросе.

Параметры ответа

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/account_status

Пример запроса 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"
}

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/taxpayer/account_status

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
bonus_amount-stringСумма бонусного счета
unpaid_amount-stringОбщая сумма неоплаченных платежей
debt_amount-stringСумма задолжности (включена в общая сумму неоплаченных платежей)

Пример запроса 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"
}

Пример ответа

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

npd/accruals и npd/request/status

Метод для получения подробной информации о наличии налоговой задолженности и остатке налогового бонуса у самозанятых.

Запрос состоит из двух частей:

  1. Сначала вы отправляете запрос в методе npd/accruals, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметре request_id.
  2. Затем отправляете запрос с этим идентификатором в методе npd/request/status. В ответе придет подробная информация о наличии налоговой задолженности и остатке налогового бонуса у самозанятого.

Адрес для отправки запроса npd/accruals

/api/v1/npd/accruals

Параметры запроса npd/accruals

НазваниеОбязательностьТипОписание
tax_reference_list+arrayСписок ИНН самозанятых. Не более 100 ИНН в обном запросе.

Параметры ответа

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/accruals

Пример запроса 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"]
}

Пример ответа

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

Адрес для отправки запроса npd/request/status

api/v1/npd/request/status

Параметры запроса npd/request/status

НазваниеОбязательностьТипОписание
request_id+stringИдентификатор, который пришел в ответ на запрос npd/accruals

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok, pending
accruals-jagged array
tax_charge_list-arrayИнформация о налоговой задолженности
amount-stringСумма начисления
due_date-stringСрок оплаты
tax_period_id-stringИдентификатор налогового периода. Формат: ГГГГММ
oktmo-stringОКТМО региона ведения деятельности
kbk-stringКод бюджетной классификации
paid_amount-stringСумма поступивших оплат в АИС Налог 3 по данному начислению
create_time-stringДата и время создания налогового начисления
id-stringВнутренний идентификатор налогового начисления в ПП НПД
krsb_list-array of reference-objects.mdИнформация о задолженности по карточке
debt-stringСумма о задолженности по карточке
penalty-stringСумма пени по карточке
overpayment-stringСумма переплаты по карточке
oktmo-stringОКТМО региона ведения деятельности, связанного с КРСБ
kbk-stringКод бюджетной классификации, связанный с КРСБ
tax_organ_code-stringКод налогового органа, связанного с КРСБ
update_time-stringДата/Время обновления информации по карточке в ПП НПД
id-stringВнутренний идентификатор карточки в ПП НПД
inn-stringИНН

Пример запроса 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"
}

Пример ответа

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

Номинальный счет

Cоздание платежной сессии

session/multi/create/nominal

Этот запрос создает платежную сессию на стороне Банка 131.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций.

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или платежа. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (/api/v1/session/multi/init/payment/nominal). В этом случае запускать операцию отдельным запросом не нужно.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса

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

Параметры запроса

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsДанные о переводе
payment_method+PaymentMethodПлатежные данные (карта, банковский счет и др.)
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
participant_details- (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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": "Назначение платежа"
}
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "****************"
}
}
},
"participant_details": {
"sender": {
"full_name": "Данные отправителя",
"beneficiary_id": "1234567890"
},
"recipient": {
"full_name": "Иванов Иван Иванович"
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"customer": {
"reference": "123456789012"
}
}

Пример успешного ответа

{
"status": "ok",
"session": {
"id": "ps_72974",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.274416Z",
"updated_at": "2021-08-06T11:34:51.466550Z",
"payments": [
{
"id": "po_25657",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545329Z",
"customer": {
"reference": "lucky"
},
"payment_method": {
"type": "card",
"card": {
"brand": "visa",
"last4": "0002"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich 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"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}

Пример неуспешного ответа

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

session/multi/start/payment/nominal

Старт выплаты

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения операции или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса

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

Параметры запроса

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_details-PaymentDetailsДанные о переводе
payment_method-PaymentMethodПлатежные данные (карта, банковский счет и др.)
participant_details- (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
customer-CustomerДанные получателя в вашей системе
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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",
"beneficiary_id": "123412341234"
},
"sender": {
"full_name": "Ivan Ivanovich Test",
"beneficiary_id": "123412341234"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"customer": {
"reference": "test"
}
}

Пример успешного ответа

{
"status": "ok",
"session": {
"id": "ps_72974",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.274416Z",
"updated_at": "2021-08-06T11:34:51.466550Z",
"payments": [
{
"id": "po_25657",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545329Z",
"customer": {
"reference": "lucky"
},
"payment_method": {
"type": "card",
"card": {
"brand": "visa",
"last4": "0002"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich 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"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}

Пример неуспешного ответа

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

session/multi/init/payment/nominal

Cоздание сессии с одновременным стартом выплаты на банковскую карту

Можно использовать этот запрос, если вы сразу готовы передать все параметры для создания выплаты. При выплате на банковскую карту — только если у вас есть PCI DSS.

В ответе возвращаются параметры созданной сессии и объект с информацией о выплате (acquiring_payments).

Адрес для отправки запроса

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

Параметры запроса

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsДанные о переводе
payment_method+PaymentMethodПлатежные данные (карта)
participant_details+ (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
customer+CustomerДанные получателя в вашей системе
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

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

Пример успешного ответа

{
"status": "ok",
"session": {
"id": "ps_72974",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.274416Z",
"updated_at": "2021-08-06T11:34:51.466550Z",
"payments": [
{
"id": "po_25657",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545329Z",
"customer": {
"reference": "lucky"
},
"payment_method": {
"type": "card",
"card": {
"brand": "visa",
"last4": "0002"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich 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"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test",
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}

Пример неуспешного ответа

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

api/v1/session/init/payout/nominal

Cоздание сессии с одновременным стартом выплаты на банковский счет

Этот запрос можно использовать для отправки выплаты с номинального счета на банковский счет.

Адрес для отправки запроса

api/v1/session/init/payout/nominal

Параметры запроса

НазваниеОбязательностьТипОписание
payment_method+PaymentMethodПлатежные данные
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_details+ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса для выплаты на счет физического лица

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"payment_method": {
"type": "bank_account",
"bank_account": {
"ru": {
"bik": "044525974",
"account": "40817810400003869535",
"full_name": "Иванов Иван Иванович",
"description": "Перевод средств по договору № 5015553111 Иванов Иван Иванович НДС не облагается"
},
"system_type": "ru"
}
},
"amount_details": {
"amount": 300,
"currency": "rub"
},
"participant_details": {
"sender": {
"account": "40702810300200000013"
},
"recipient":{
"beneficiary_id": "1234567890"
}
}
}'

Пример запроса для выплаты на счет юридического лица

curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
"payment_method": {
"type": "bank_account",
"bank_account": {
"ru": {
"bik": "044525974",
"account": "40702810500000000001",
"full_name": "ООО Наименование организации",
"inn": "1111111111",
"kpp": "156605101",
"description": "Перечисление денежных средств по договору за декабрь 2022 г. НДС не облагается."
},
"system_type": "ru"
}
},
"amount_details": {
"amount": 300,
"currency": "rub"
},
"participant_details": {
"sender": {
"account": "40702810300200000013"
},
"recipient":{
"beneficiary_id": "1234567890"
}
}
}'

Пример успешного ответа

"status": "ok",
"session": {
"id": "ps_287403",
"status": "in_progress",
"created_at": "2023-05-10T16:58:43.586072Z",
"updated_at": "2023-05-10T16:58:43.705620Z",
"payments": [
{
"id": "po_72265",
"status": "in_progress",
"created_at": "2023-05-10T16:58:43.781934Z",
"payment_method": {
"type": "bank_account",
"bank_account": {
"system_type": "ru",
"ru": {
"bik": "049205131",
"account": "40702810900000000001",
"full_name": "Наименование организации",
"description": "Перечисление денежных средств по договору № 1 НС от 01.09.2021 комиссия площадки за декабрь 2022 г. НДС не облагается.",
"is_fast": false,
"kpp": "156605001",
"inn": "3111104710"
}
}
},
"amount_details": {
"amount": 200,
"currency": "rub"
},
"paymentMetadata": {},
"participant_details": {
"sender": {
"account": "40702810300200000013"
},
"recipient": {
"beneficiary_id": "1234567890"
}
}
}
]
}

Пример неуспешного ответа

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

Расчетный счет

session/multi/create/rko

Этот запрос создает платежную сессию на стороне Банка 131 для выплаты с расчетного счета.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций.

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (/api/v1/session/multi/init/payment/rko). В этом случае запускать операцию отдельным запросом не нужно.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса

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

Параметры запроса

НазваниеОбязательностьТипОписание
payment_details+PaymentDetailsДанные о переводе
amount_details-AmountDetailsСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
fiscalization_details-FiscalizationDetailsДанные для фискализации, только для выплат самозанятым
participant_details- (обязателен при выплатах на карту)ParticipantDetailsИнформация об участниках операции (отправителе и получателе)
customer-CustomerДанные получателя в вашей системе
metadata-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках

Параметры ответа

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session-PaymentSessionПлатежная сессия
error-ErrorОшибка

Пример запроса

curl -X POST \
https://demo.bank131.ru//api/v1/session/multi/create/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d {
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_bank_account",
"transfer_from_bank_account": {
"description": "Назначение платежа"
}
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "****************"
}
}
},
"participant_details": {
"sender": {
"full_name": "Данные отправителя",
},
"recipient": {
"full_name": "Иванов Иван Иванович"
}
},
"amount_details": {
"amount": 293400,
"currency": "RUB"
},
"customer": {
"reference": "123456789012"
}
}

Пример успешного ответа

{
"status": "ok",
"session": {
"id": "ps_72974",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.274416Z",
"updated_at": "2021-08-06T11:34:51.466550Z",
"payments": [
{
"id": "po_25657",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545329Z",
"customer": {
"reference": "lucky"
},
"payment_method": {
"type": "card",
"card": {
"brand": "visa",
"last4": "0002"
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich 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_bank_account",
"transfer_from_bank_account": {
"description": "test payout",
"card_mask": "400000******0002"
}
}
},
"amount_details": {
"amount":