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

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

Чтобы у вас не возникло проблем с бухгалтерией, а у самозанятого — с ФНС, выплаты нужно фискализировать. Для этого вам потребуются: ИНН плательщика, ИНН самозанятого и данные для чека (наименование и стоимость услуг).

Перед выплатой нужно проверить следующее:

  • получатель имеет действующий статус самозанятого;
  • получатель подключен к Банку 131;
  • годовой доход получателя с учетом текущей выплаты не превышает 2,4 миллиона рублей (иначе получатель потеряет статус самозанятого).

Для этого используйте методы check и request/status. Если хотя бы одно из этих условий не выполняется, выплата не пройдет.

Проведение выплаты​

к сведению

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

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

Шаг 1. Сгенерируйте публичный токен​

Публичный токен нужен, чтобы подключить виджет. Отправьте запрос Банку 131 на создание токена (token), передав в нем тип виджета tokenize_widget. В ответе вы получите публичный токен.

Шаг 2. Подключите виджет на сайт​

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

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

Как инициализировать виджет для токенизации карты >

Как инициализировать виджет для токенизации счета >

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

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

Вы можете создать сессию и выплату одновременно (session/init/payout/fiscalization), сразу передав данные для фискализации, параметры выплаты (на карту или счет) с хешем номера карты или токеном счета из виджета, и пропустите следующий шаг. Не рекомендуем использовать этот способ.

Пример создания платежной сессии
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: signature' \
  -d '{
    "metadata": "good"
  }'

Шаг 4. Отправьте выплату​

Выполните запрос session/start/payout/fiscalization, передав идентификатор сессии, данные для фискализации и параметры выплаты (на карту или счет) с хешем номера карты или токеном счета из виджета.

Пример выплаты с фискализацией на карту
curl -X POST \
  https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id":"ps_3230",
    "fiscalization_details": {
      "professional_income_taxpayer": {
        "tax_reference": "590613976192",
        "payer_type": "legal",
        "payer_tax_number": "3316004710",
        "payer_name": "ООО Вектор",
        "services": [{
          "name": "Доставка товара",
          "amount_details": {
            "amount": 10000,
            "currency": "rub"
          }
        }]
      }
    },
    "payment_method": {
      "type": "card",
      "card": {
        "type": "encrypted_card",
        "encrypted_card": {
          "number_hash": "3589c9cad4c0e939f6e01a91710b1bef2db5a7a0a9dca274981511120268d420"
        }
      }
    },
    "amount_details": {
      "amount": 10000,
      "currency": "rub"
    },
    "metadata": "good",
    "participant_details": {
      "recipient": {
        "full_name": "Иванов Иван Иванович"
      }
    }
  }'
Примеры ответов
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2025-05-27T02:03:00.000000Z",
    "updated_at": "2025-05-27T02:03:00.000000Z",
    "payments": [{
      "id": "po_2909",
      "status": "in_progress",
      "created_at": "2025-05-27T02:03:00.000000Z",
      "payment_method": {
        "type": "card",
        "card": {
          "brand": "mir",
          "last4": "4940",
          "country_iso3": "RUS"
        }
      },
      "amount_details": {
        "amount": 10000,
        "currency": "rub"
      },
      "fiscalization_details": {
        "professional_income_taxpayer": {
          "tax_reference": "590613976192",
          "payer_type": "legal",
          "payer_tax_number": "3316004710",
          "payer_name": "ООО Вектор",
          "services": [{
            "name": "Доставка товара",
            "amount_details": {
              "amount": 10000,
              "currency": "rub"
            }
          }]
        }
      },
      "metadata": "good",
      "participant_details": {
        "recipient": {
          "full_name": "Иванов Иван Иванович"
        }
      }
    }]
  }
}

Шаг 5. Дождитесь вебхука о готовности выплаты​

Банк 131 отправит вам вебхук ready_to_confirm о готовности провести выплату и ожидании вашего подтверждения или отмены.

Пример вебхука о готовности выплаты
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "ready_to_confirm",
    "session": {
      "id": "ps_3230",
      "status": "in_progress",
      "created_at": "2025-05-27T02:03:00.000000Z",
      "updated_at": "2025-05-27T02:03:00.000000Z",
      "next_action": "confirm",
      "payments": [{
        "id": "po_2909",
        "status": "pending",
        "created_at": "2025-05-27T02:03:00.000000Z",
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "mir",
            "last4": "4940",
            "country_iso3": "RUS"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "tax_reference": "590613976192",
            "payer_type": "legal",
            "payer_tax_number": "3316004710",
            "payer_name": "ООО Вектор",
            "services": [{
              "name": "Доставка товара",
              "amount_details": {
                "amount": 10000,
                "currency": "rub"
              }
            }]
          }
        },
        "metadata": "good",
        "participant_details": {
          "recipient": {
            "full_name": "Иванов Иван Иванович"
          }
        }
      }]
    }
  }'
Пример обработки вебхука с помощью 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
}

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

Проверьте данные и подтвердите (session/confirm) или отмените (session/cancel) выплату.

Пример с подтверждением выплаты
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: signature' \
  -d '{
    "session_id": "ps_3230"
  }'
Пример с отменой выплаты
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: signature' \
  -d '{
    "session_id": "ps_3230"
  }'

Шаг 7. Дождитесь вебхука о результате выплаты​

Банк 131 отправит вам вебхук payment_finished. Информация о результате выплаты содержится в параметре status объекта payments/payout_list.

Статус succeeded означает, что выплата прошла успешно. Если статус 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
}




ИИ-помощник