Методы
При обработке запросов проверяется корректность входных параметров, наличие необходимых заголовков, права на выполнение действий.
Проведение операций
session/create
Cоздание платежной сессии
Этот запрос создает платежную сессию на стороне Банка 131.
Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций одного или разных типов (например, несколько выплат, платеж и возврат, оплата с последующим разделением платежей).
Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или оплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.
Если вы готовы передать в запросе все данные, которые нужны для проведения операции, можете использовать метод, при котором сразу после создания сессии стартует выплата (
session/start/payout
) или оплата (session/start/payment
). В этом случае запускать операцию отдельным запросом не нужно.
В ответе возвращаются параметры созданной сессии.
Адрес для отправки запроса
api/v1/session/create
Параметры запроса
Название | Обязательность | Тип | Описание |
---|---|---|---|
payment_method | - | PaymentMethod | Платежные данные (карта, банковский счет и др.) |
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"
}'
use Bank131\SDK\API\Request\Builder\RequestBuilderFactory;
use Bank131\SDK\Client;
use Bank131\SDK\Config;
$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem')
);
$client = new Client($config);
$request = RequestBuilderFactory::create()
->createPaymentSession() //OR ->createPayoutSession()
->setAmount(10000, 'rub')
->setMetadata('order123')
->build();
$response = $client->session()->create($request);
Пример успешного ответа
{
"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"
},
"amounts": {
"gross": {
"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 | + | string | URL, на который нужно перенаправить пользователя после проведения платежа. 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 | Данные отправителя платежа в вашей системе |
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"
}
}
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"
}
}
]
}
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
Проверка статуса самозанятого
Этот запрос позволяет проверить по ИНН, является физлицо самозанятым или нет.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос
check
, передаете в параметреtax_reference
ИНН физлица и получаете в ответ идентификаторrequest_id.
- Затем отправляете запрос
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
Проверка соответствия данных самозанятого
Запрос позволяет проверить соответвие данных (ИНН, ФИО, номер телефона) самозанятого с теми, которые имеются в ФНС.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/taxpayer/check_personal_info
, передаете в параметрах ИНН, ФИО и номер телефона самозанятого, и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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
Метод для получения количества непрочитанных оповещений из ФНС для самозанятых.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/notifications/count
, передаете в параметрах ИНН и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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
Метод для получения подробной информации о непрочитанных оповещениях для самозанятых из ФНС.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/notifications/read
, передаете в параметрах ИНН и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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 |
Параметры ответа
Название | Обязательность | Тип | Описание |
---|---|---|---|
status | + | string | Статус. Возможные варианты: error , ok , pending |
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
.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/notifications/mark_as_delivered
, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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
.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/notifications/update
, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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
Метод для получения общей информации о наличии налоговой задолженности и остатке налогового бонуса у самозанятых.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/taxpayer/account_status
, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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
Метод для получения подробной информации о наличии налоговой задолженности и остатке налогового бонуса у самозанятых.
Запрос состоит из двух частей:
- Сначала вы отправляете запрос в методе
npd/accruals
, передаете в параметрах данные самозанятого и получаете в ответ идентификатор в параметреrequest_id.
- Затем отправляете запрос с этим идентификатором в методе
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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_15174",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545232Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_nominal_account",
"transfer_from_nominal_account": {
"description": "test payout",
"card_mask": "400000******0002"
}
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Пример неуспешного ответа
{
"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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_15174",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545232Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_nominal_account",
"transfer_from_nominal_account": {
"description": "test payout",
"card_mask": "400000******0002"
}
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Пример неуспешного ответа
{
"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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_15174",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545232Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_nominal_account",
"transfer_from_nominal_account": {
"description": "test payout",
"card_mask": "400000******0002"
}
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test",
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Пример неуспешного ответа
{
"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"
},
"amounts": {
"gross": {
"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 | Данные о переводе |
| payment_method | + | PaymentMethod | Платежные данные (карта, банковский счет и др.) |
| 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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_15174",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545232Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_bank_account",
"transfer_from_bank_account": {
"description": "test payout",
"card_mask": "400000******0002"
}
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Пример неуспешного ответа
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}
session/multi/start/payment/rko
Этот запрос можно использовать, чтобы начать выплату с расчетного счета на банковскую карту в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения операции или заменить уже переданные.
Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.
Адрес для отправки запроса
/api/v1/session/multi/start/payment/rko
Параметры запроса
Название | Обязательность | Тип | Описание |
---|---|---|---|
session_id | + | string | Идентификатор платежной сессии |
payment_details | - | PaymentDetails | Данные о переводе |
payment_method | - | PaymentMethod | Платежные данные (карта, банковский счет и др.) |
customer | - | Customer | Данные получателя в вашей системе |
amount_details | - | AmountDetails | Сумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000 |
fiscalization_details | - | FiscalizationDetails | Данные для фискализации, только для выплат самозанятым |
participant_details | - (обязателен при выплатах на карту) | ParticipantDetails | Информация об участниках операции (отправителе и получателе) |
Пример запроса
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/rko \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: 721af394d5a7aefd0e91f5390abc4d7e20fb2b5784b091fef621f3c61b7abb4b' \
-d '{
"session_id": "ps_12345",
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_bank_account",
"transfer_from_bank_account": {
"description": "test payout"
}
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "4242424242424242"
}
}
},
"participant_details": {
"recipient": {
"full_name": "Ivan Ivanovich Test"
},
"sender": {
"full_name": "Ivan Ivanovich Test"
}
},
"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"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
],
"acquiring_payments": [
{
"id": "pm_15174",
"status": "in_progress",
"created_at": "2021-08-06T11:34:51.545232Z",
"customer": {
"reference": "lucky"
},
"payment_details": {
"type": "internal_transfer",
"internal_transfer": {
"type": "transfer_from_bank_account",
"transfer_from_bank_account": {
"description": "test payout",
"card_mask": "400000******0002"
}
}
},
"amount_details": {
"amount": 1011,
"currency": "RUB"
},
"amounts": {
"gross": {
"amount": 1011,
"currency": "RUB"
}
},
"metadata": {
"key": "value"
},
"participant_details": {
"sender": {
"full_name": "Ivan Ivanovich Test"
},
"recipient": {
"full_name": "Ivan Ivanovich Test",
"reference": "1234"
}
}
}
]
}
}
Пример неуспешного ответа
{
"error": {
"code": "invalid_request",
"description": "customer.reference.not_blank"
},
"status": "error"
}
session/init/payout/rko
Метод инициализации сессии и старта выплаты с расчетного счета.
Адрес для отправки запроса
/api/v1/session/init/payout/rko
Параметры запроса
Название | Обязательность | Тип | Описание |
---|---|---|---|
payment_method | + | PaymentMethod | Платежные данные (банковский счет) |
amount_details | + | AmountDetails | Сумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000 |
participant_details | + | ParticipantDetails | Информация об отправителе |
metadata | - | * | Дополнительная информация. Любые данные, которые вам необходимы для проведения операции. Возвращаются в ответах и вебхуках |
Параметры ответа
Название | Обязательность | Тип | Описание |
---|---|---|---|
status | + | string | Статус. Возможные варианты: error , ok |
session | - | PaymentSession | Платежная сессия |
error | - | Error | Ошибка |
Пример запроса
curl --location 'https://proxy-stage.bank131.ru/api/v1/session/init/payout/rko' \
--header 'X-PARTNER-PROJECT: project-test' \
--header 'X-PARTNER-SIGN: sign' \
--header 'Content-Type: application/json' \
--data '{
"payment_method": {
"type": "bank_account",
"bank_account": {
"system_type":