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

Выплата с фискализацией

Этот сценарий описывает отправку самозанятому выплаты c фискализацией. В чем особенности:

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

Что сделать перед выплатами самозанятому

Перед тем как проводить первую выплату, привяжите самозанятого к Банку 131.

Если самозанятый привязан к Банку 131, можно проводить выплату.

Шаг 1. Покажите пользователю виджет для получения номера карты

Если вы проводите выплату на банковскую карту и у вас нет сертификата PCI DSS, получите токенизированные данные банковской карты через виджет. Для этого:

  1. Получите токен с помощью запроса token (токен можно использовать только один раз).

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

Как добавить виджет

Теперь можно отправлять выплату.

Шаг 2. Создайте платежную сессию

Создайте платежную сессию — в ее рамках будут проходить все действия. Отправьте запрос session/create и получите идентификатор сессии.

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

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

Шаг 3. Начните выплату с фискализацией

Создайте выплату с помощью метода session/start/payout/fiscalization. В параметре session_id передайте идентификатор сессии, созданной в самом начале. В объекте ProfessionalIncomeTaxpayer передайте данные для фискализации:

  • в поле payer_type значение legal (если выплату отправляет российская компания);
  • в поле payer_tax_number— ИНН компании, которая отправляет выплату (нужен, если payer_type: legal);
  • в поле tax_reference — ИНН самозанятого;
  • в поле FiscalizationDetails — данные для формирования чека.

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

банковский счет.

Пример запроса на выплату

curl --location --request POST 'https://demo.bank131.ru/api/v1/session/start/payout/fiscalization' \
--header 'Content-Type: application/json' \
--header 'X-PARTNER-SIGN: sign' \
--header 'X-PARTNER-PROJECT: your_project_name' \
--data-raw '{
"fiscalization_details": {
"professional_income_taxpayer": {
"tax_reference": "590613976192",
"payer_type": "legal",
"payer_tax_number": "3316004710",
"payer_name": "ООО Рога и Копыта",
"services": [
{
"name": "Доставка товара",
"amount_details": {
"amount": 5000,
"currency": "rub"
}
}
]
}
},
"payment_method": {
"type": "card",
"card": {
"type": "bank_card",
"bank_card": {
"number": "4242424242424242"
}
}
},
"amount_details": {
"amount": 5000,
"currency": "rub"
},
"metadata": "good",
"participant_details": {
"recipient": {
"full_name": "Ivanov Ivan"
}
}
}'

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

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

Шаг 4. Дождитесь уведомления о готовности сделать выплату

Банк 131 отправит вам вебхук ready_to_confirm (на адрес для вебхуков, который вы заранее передали менеджеру Банка). Это значит, что выплату можно провести и Банк ждет вашего подтверждения (или отмены). В теле вебхука придут все данные для выплаты.

В ответ следует отдавать HTTP-код 200.

Пример вебхука ready_to_confirm

curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
-d '{
"type": "ready_to_confirm",
"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": "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"
}
]
}
}'

Пример обработки вебхука с помощью SDK

use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;

$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem'),
file_get_contents('/path/to/bank131/public_key.pem')
);

$client = new Client($config);

$hook = $client->handleWebHook('sign from headers', 'request body');

if ($hook->getType() === WebHookTypeEnum::READY_TO_CONFIRM) {
$session = $hook->getSession();
//do your logic here
}

Шаг 5. Подтвердите или отмените выплату

Проверьте данные для выплаты и подтвердите, что готовы её провести (с помощью запроса confirm_request) или отмените (отправьте запрос cancel_request).

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

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

Шаг 6. Дождитесь уведомления о результате выплаты

Банк 131 отправит вам вебхук payment_finished. В теле вебхука придут все данные, с которыми проводилась выплата. Результат выплаты приходит в поле payment.status.

Если статус succeeded, значит, выплата самозанятому успешно отправлена. Если статуc failed — выплата не прошла из-за ошибки.

Подробнее о статусах выплаты

Также в теле вебхука в параметре receipt передается идентификатор чека ФНС и ссылка на него. Перейдите по ссылке, чтобы скачать чек.

Пример чека

Пример обработки вебхука с помощью SDK

use Bank131\SDK\Client;
use Bank131\SDK\Config;
use Bank131\SDK\Services\WebHook\Hook\WebHookTypeEnum;

$config = new Config(
'https://demo.bank131.ru',
'your_project_name',
file_get_contents('/path/to/your/private_key.pem'),
file_get_contents('/path/to/bank131/public_key.pem')
);

$client = new Client($config);

$hook = $client->handleWebHook('sign from headers', 'request body');

if ($hook->getType() === WebHookTypeEnum::PAYMENT_FINISHED) {
$session = $hook->getSession();
//do your logic here
}
Обратная связь