Формирование чеков

Введение

Что такое кассовый (фискальный) чек

Кассовый или фискальный чек — это первичный учетный документ, который отражает факт взаиморасчёта между магазином и покупателем и подтверждает, что покупатель внёс денежные средства, а магазин передал ему товар или оказал услугу.

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

Практический каждый магазин, который продаёт в онлайне, обязан формировать чек в соответствии с 54-ФЗ, поскольку непредоставление чека влечёт за собой наложение штрафа со стороны налоговых органов.

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

Онлайн-касса - это контрольно-кассовая техника (ККТ) которая подключена к сети интернет. Онлайн-кассы бывают двух видов:

В виде портативного ПК, который можно купить и установить в офисе или в точке продаж
В виде облачного решения, в этом случае касса будет находиться не у вас, а вЦОДе провайдера

В чём роль Paybox
Paybox не является онлайн-кассой, но он интегрирован с различными онлайн-кассами и сервисами в РФ и умеет отправлять им данные для регистрации кассовых чеков в момент выполнения платежа.

Что нужно сделать для отправки чеков через Paybox
Для того чтобы воспользоваться сервисом Paybox по отправке данных для регистрации чеков, необходимо выполнить несколько шагов:

1. Подключить Paybox

Если вы ещё не являетесь нашим клиентом.

2. Приобрести онлайн-кассу

Купить или арендовать онлайн-кассу у одного из наших технологических партнёров

3. Связать онлайн-кассу и Paybox

Пройти процедуру подключения вашей онлайн-кассы к Paybox в личном кабинете магазина.

4. Настроить отправку данных для регистрации чека на стороне своего магазина

Если вы хотите воспользоваться нашим API, необходимо ознакомиться с документацией по этой ссылке.
Если вы используете готовый CMS, ознакомьтесь с перечнем наших модулей, поддерживающих функционал по отправке чеков.
Функционал отправки чеков при работе с личным кабинетом магазина, а также в модулях CMS на данный момент находится в разработке.

С какими технологическими партнёрами работает Paybox

Атол Онлайн*

* Сервисы, не указанные в списке, находятся в разработке.

Какие возможности есть в нашем API
Подключившись к нашему API, вы сможете:

отправлять данные для регистрации чеков в онлайн-кассу в соответствии с требованиями к формату фискальных данных ФФД 1.05 и ФФД 1.2;
формировать чеки в момент проведения платежей и возвратов, в т.ч. при выполнении двухэтапных платежей;
формировать чеки предоплаты, аванса или кредита, а также чеки зачёта предоплаты (окончательного расчёта или реализации)
независимо формировать чеки после совершения платежей и возвратов;
получать данные по отдельно взятым чекам магазина, сформированным с помощью Paybox;
выгружать список чеков, применяя необходимые фильтры.

Существующие способы формирования чеков
1. Чек вместе с платежом

Данный способ формирования чеков подойдёт большинству магазинов, которые хотят максимально автоматизировать эту процедуру.

Как передавать данные в Paybox:

для формирования чека прихода (продажи), необходимо отправить объект pg_receipt в момент выполнения запроса на создание платежа (внутри тела платежа)
для формирования чека возврата прихода (возврата), необходимо отправить объект pg_receipt в момент выполнения запроса на создание частичного возврата (внутри тела возврата)

Paybox отправит чек в онлайн-кассу сразу после успешного завершения платежа/возврата.

Если по какой-либо причине чек не зарегистрируется, вы сможете зарегистрировать его с помощью своей онлайн-кассы или попытаться отправить этот чек повторно, воспользовавшись API Paybox.

Поскольку Paybox отправляет чек в онлайн-кассу только после успешной операции платежа/возврата, ошибка при регистрации чека никак не повлияет на основную операцию, платёж или возврат всё равно будет выполнен.

Для подключения этого способа в личном кабинете Paybox, в разделе Настройки → Онлайн-касса → 2. Настройка → Способ формирования чека, выберите режим Чек вместе с платежом.

2. Чек отдельно от платежа

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

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

Этот способ обязателен для тех, кто использует функционал Сплитования платежей.

Как передавать данные в Paybox:

для формирования чека прихода (продажи), необходимо отправить отдельный запрос на создание чека, после того как платёж будет успешно выполнен;
для формирования чека возврата прихода (возврата), необходимо отправить отдельный запрос на создание чека, после того как возврат будет успешно выполнен;

При выборе этого способа, запрос на создание платежа или возврата необходимо отправлять без объекта pg_receipt. Если в этих запросах передать объект pg_receipt, то Paybox проигнорирует его.

Paybox немедленно отправит вашей онлайн-кассе данные для регистрации чека, а вам в ответ на запрос вернёт объект чека. Ошибка при регистрации чека никак не повлияет на платёж или возврат.

Для подключения этого способа в личном кабинете Paybox, в разделе Настройки → Онлайн-касса → 2 Настройка → Способ формирования чека, выберите режим Чек отдельно от платежа.

Необходимые шаги для интеграции

Подключите онлайн-кассу, которая входит в перечень наших технологических партнёров.
Заключите договор с оператором фискальных данных, не забудьте подключить услугу по отправке чеков на электронную почту покупателя.
Выполните настройки в разделе "Онлайн-касса" вашего личного кабинета Paybox:

Откройте раздел Настройки на левой панели главного меню и перейдите на вкладку Онлайн-касса (рис.1).
В поле Выберите магазин, выберите магазин, к которому вы хотите подключить свою онлайн-кассу (рис. 2).
На шаге №1 Выбор онлайн-кассы, в поле Ваша касса, выберите название вашей кассы (рис. 2).
В поле Версия ФФД, выберите версию формата фискального документа, которую поддерживает ваша онлайн-касса ( рис. 2), если у вас возникли трудности с определением версии ФФД, обратитесь к вашему поставщику онлайн-кассы для получения консультации.
Нажмите кнопку Перейти к настройкам (рис. 2), после чего раскроется шаг №2 Настройка
В разделе Параметры подключения введите данные, которые вы получили в личном кабинете вашей онлайн-кассы, набор параметров может отличаться в зависимости от используемой онлайн-кассы (рис. 3).
В разделе Система налогообложения (СНО) перейдите к полю, Выберите СНО по умолчанию и укажите вашу систему налогообложения, выбранная система налогообложения будет отображена в чеке покупателя (рис. 3).
Перейдите в раздел Другие настройки и введите в поле Почта отправителя чека адрес электронной почты вашего магазина, который будет отображен в чеке покупателя (рис. 4)
Введите в поле Почта для получения ошибок адрес электронной почты, на который мы отправим письмо с уведомлением, в случае если Paybox не сможет зарегистрировать чек (рис. 4).
Введите в поле Место приема платежей информацию о том, где именно вы принимаете платежи (например электронный адрес вашего интернет-магазина). Если вы осуществляете приём платежей ещё и на физической торговой точке, то её адрес необходимо ввести в данное поле через запятую. Информация, введённая в это поле, будет также отображена в чеке покупателя (рис. 4)
Введите в поле ИНН идентификационный номер налогоплательщика, на который была зарегистрирована ваша онлайн-касса (рис. 4)
В поле Способ формирования чека, выберите в раскрывающемся списке тот способ, с помощью которого вы будете отправлять чеки в онлайн-кассу (рис. 4)
Далее необходимо нажать кнопку Проверка подключения, после чего Paybox попытается подключиться к вашей онлайн-кассе. В случае, если все поля раздела Параметры подключения были заполнены корректными данными, Paybox выведет сообщение об успешном подключении. Если попытка подключения к онлайн-кассе завершилась неудачно, необходимо скорректировать параметры подключения и выполнить проверку ещё раз (рис. 4)
Для завершения настройки онлайн-кассы необходимо нажать кнопку Включить онлайн-кассу (рис. 4)*
Готово, все 3 шага по настройке выполнены и вы можете начать отправку чеков (рис. 5).

4.Настройте отправку чеков со стороны вашего магазина:

Если вы выполняете интеграцию через API, добавьте параметры для чека (наименования товаров, их цены, ставку НДС, информацию о покупателе, признаки способа и предмета расчёта и проч.) в запросы на создание платежа/возврата. Подробнее- тут.
Если вы пользуетесь CMS и подключали Paybox через платежный модуль, обновите модуль, зайдите в его настройки и включите там передачу данных по 54-ФЗ — подробнее смотрите в инструкции к вашему модулю. Если такой настройки в платёжном модуле нет, напишите в службу поддержки Paybox.

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

Если вы хотите внести какие-то изменения в настройки онлайн-кассы, не связанные с параметрами подключения, то вам необходимо открыть раздел Настройки, на левой панели главного меню, и перейдите на вкладку Онлайн-касса, а затем нажать кнопку Отключить онлайн-кассу (рис. 5). После внесения изменений необходимо включить онлайн-кассу, в противном случае Paybox не будет отправлять чеки.

Рисунок 1

Рисунок 2

Рисунок 3

Рисунок 4

Рисунок 5

Чеки при платежах

Общий сценарий

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

Чек прихода вместе с платежом
Если вы выбрали способ отправки чеков Чек вместе с платежом, данные для формирования чека прихода необходимо передавать в следующих сценариях:

при инициализации, в случае проведения платежа в один этап (запрос на init_payment.php** с параметром pg_auto_clearing=1)
при инициализации, в случае проведения платежа в два этапа (запрос на init_payment.php** с параметром pg_auto_clearing=0)
при частичном клиринге платежа, в случае двухэтапной оплаты (запрос на do_capture.php)

Проведение платежа
Чтобы сформировать чек прихода, необходимо вместе с данными для инициализации платежа передать в запросе объект pg_receipt.

Пример запроса на инициализацию платежа с параметрами для чека прихода

curl --location --request POST 'https://api.freedompay.uz/init_payment.php' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw \
'{
  "pg_order_id": "3552",
  "pg_merchant_id": 542088,
  "pg_amount": 200.00,
  "pg_description": "Заказ №052641",
  "pg_auto_clearing": 1,
  "pg_salt": "default",
  "pg_receipt": {
    "receipt_format": "ru_1_05",
    "customer": {
      "email": "customer@mail.ru"
    },
    "positions": [
      {
        "price": 50.00,
        "name": "Товар №1",
        "quantity": 2.00,
        "vat_code": "vat_20",
        "payment_method": "full_payment",
        "payment_object": "goods"
      },
      {
        "price": 100.00,
        "name": "Товар №2",
        "quantity": 1.00,
        "vat_code": "vat_20",
        "payment_method": "full_payment",
        "payment_object": "goods"
      }
    ]
  },
  "pg_sig": "{{Ваша подпись запроса}}"
}'

В ответ Paybox вернёт объект платежа.

<?xmlversion="1.0"encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>771889578</pg_payment_id>
    <pg_redirect_url>https://freedompay.uz/pay.html?customer=8f613c0d0e874e40247c7b4d20d7b10e</pg_redirect_url>
    <pg_redirect_url_type>needdata</pg_redirect_url_type>
    <pg_salt>v0MKA0IJS8GhHwfr</pg_salt>
    <pg_sig>{{Ваша подпись запроса}}</pg_sig>
</response>

Если платёж будет завершён успешно, в личном кабинете магазина, при клике на платеже и переходе на вкладку Чеки платежа, появится чек с названием "Чек прихода". Также данный чек будет доступен в разделе Чеки, расположенном** на левой панели главного меню.

Частичный клиринг платежа

Если вы принимаете оплату в два этапа, то причастичном клиринге платежа будет сформировано два новых чека:

Чек №1 - чек возврата прихода на полную сумму, с товарами, которые присутствовали в чеке прихода, сформированного в результате выполнения первого этапа платежа (блокирования денежных средств)
Чек №2 - новый чек прихода, с теми товарами, которые были проданы по факту, в результате второго этапа - операции клиринга

Вам необходимо сформировать Чек №2, и вместе с данными для клиринга платежа передать в запросе do_capture.php объект pg_receipt, включающий скорректированные товарные позиции.

Чек №1 передавать не надо, Paybox сформирует его автоматический.

Пример запроса на частичный клиринг платежа

curl--location--requestPOST'https://api.freedompay.uz/do_capture.php' \
--header'Content-Type: application/json' \
--data-raw \
'{
  "pg_merchant_id": 542088,
  "pg_payment_id": 764197452,
  "pg_clearing_amount": 100,
  "pg_salt": "default",
  "pg_receipt": {
    "receipt_format": "ru_1_05",
    "customer": {
      "email": "customer@mail.ru"
    },
    "positions": [
      {
        "price": 50.00,
        "name": "Товар№1",
        "quantity": 2.00,
        "vat_code": "vat_20",
        "payment_method": "full_payment",
        "payment_object": "goods"
      }
    ]
  },
  "pg_sig": "{{Ваша подпись запроса}}"
}'

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

В случае, если вы выполняете отмену платежа до клиринга (запрос на cancel.php) передавать данные для чека также не нужно, Paybox сформирует чек возврата прихода автоматический, как только статус транзакции изменится на revoked.

Если частичный клиринг будет завершён успешно, в личном кабинете магазина, при клике на платеже и переходе на вкладку Чеки платежа, появится 3 чека:

Чек прихода с первоначальными товарами, сформированный в результате выполнения первого этапа платежа
Чек возврата прихода, сформированный в результате выполнения частичного клиринга
Чек прихода, содержащий скорректированные товары, также сформированный в результате выполнения частичного клиринга

Все эти чеки будут доступны в разделе Чеки.

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

Данные для формирования чека нужно передавать всегда в отдельном запросе, сразу после того как вы убедились, что платёж завершён успешно (параметр pg_transaction_status равен значению ok).

В этом случае при отправке запроса на инициализацию платежа вам не нужно передавать в теле запроса объект pg_receipt.

Принцип создания чека прихода
При проведении платежа, вы должны выполнить следующую последовательность действий:

Отправить запрос на инициализацию платежа;
Сохранить полученный в ответе от Paybox идентификатор платежа pg_payment_id;
Выполнить запрос на получение статуса платежа и убедиться, что платёж завершился успешно;
Отправить запрос на создание чека прихода, при этом в теле запроса передать параметр payment_id, значением которого будет идентификатор платежа, полученный от Paybox на шаге №2. Также необходимо передать тип кассовой операции operation_type равный sell, и другие обязательные для создания чека параметры.

Пример запроса на создание чека прихода отдельно от платежа

curl --location --request POST 'https://api.freedompay.uz/v5/receipts' \
--header'Accept: application/json' \
--header'X-JWS-Signature:{{Ваш JWS-токен}}' \
--header'Content-Type: application/json' \
--data-raw \
'{
  "receipt_format": "ru_1_05",
  "merchant_id": 542088,
  "payment_id": 764239789,
  "operation_type": "sell",
  "customer": {
    "email": "customer@mail.ru"
  },
  "positions": [
    {
      "price": 50.00,
      "name": "Товар№1",
      "quantity": 2.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    },
    {
      "price": 100.00,
      "name": "Товра№2",
      "quantity": 1.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    }
  ],
  "settlements": [
    {
      "type": "cashless",
      "sum": 200.00
    }
  ]
}'

В ответе Paybox вернёт объект вашего чека

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

{
    "data": {
        "merchant_id": "542088",
        "receipt_id": "bb938d6c-6c1c-44a0-aa54-32c3e14fddb7",
        "operation_type": "sell",
        "receipt_format": "ru_1_05",
        "status": "registered",
        "fiscal_document_number": 10605,
        "fiscal_storage_number": "9999078900006286",
        "fiscal_attribute": 923085333,
        "registered_at": "29.03.202317:37:00",
        "created_at": "29.03.202320:39:16",
        "fiscal_provider_id": "5e402526-0c20-41c3-b30a-b52e7f903922",
        "positions": [
            {
                "name": "Товар №1",
                "quantity": 2,
                "price": 50,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            },
            {
                "name": "Товар №2",
                "quantity": 1,
                "price": 100,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            }
        ],
        "total": 200,
        "settlements": [
            {
                "type": "cashless",
                "sum": 200
            }
        ],
        "company": {
            "inn": "5544332219",
            "email": "customer@mail.ru",
            "tax_system": "osn",
            "payment_address": "shop.ru"
        },
        "receipt_method": "separately",
        "error": null,
        "link": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006286&fp=923085333&i=10605&t=20230329T173700&s=7&n=2",
        "payment_id": "764239789"
    }
}

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

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

Чек №1 - чек возврата прихода на полную сумму, с товарами, которые присутствовали в чеке прихода, сформированного в результате выполнения первого этапа платежа (блокирования денежных средств)
Чек №2 - новый чек прихода, с товарами, которые были проданы по факту, в результате второго этапа - операции клиринга

В этом случае запрос на частичный клиринг do_capture.php необходимо отправлять без объекта pg_receipt.

Если вы выполнили полный клиринг платежа (на всю сумму), то создавать ещё один чек прихода не нужно.

Ниже описана последовательность действий, которую необходимо выполнить для создания описанных выше чека №1 и чека №2:

Отправить запрос на частичный клиринг платежа;
Выполнить запрос на получение статуса платежа и убедиться, что клиринг по нему завершился успешно;
Отправить запрос на создание чека возврата прихода, при этом, в теле запроса передать параметр refund_id, значением которого будет идентификатор платежа. Также необходимо передать тип кассовой операции operation_type, равный sell_refund, и другие обязательные для создания чека параметры.
Отправить запрос на создание чека прихода, при этом, в теле запроса передать параметр payment_id, значением которого будет идентификатор платежа. Также, необходимо передать тип кассовой операции operation_type равный sell, и другие обязательные для создания чека параметры.

3.4. Создание чека зачёта предоплаты (окончательного расчёта или реализации)

Формирование чека зачёта предоплаты зависит от того, какой тип товара вы продаёте в своём магазине.

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

Примером может служить продажа лицензий на ПО, фильмов в онлайн-кинотеатре или услуг такси.

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

Чек прихода - в момент приёма оплаты на сайте. При этом все товары в сформированном чеке должны иметь признак способа расчета с одним из следующих значений: “Предоплата”, “Предоплата 100%” или Аванс
Чек зачёта предоплаты - сразу после передачи товара покупателю. Все товары в этом чеке должны содержать признак способа расчета “Полный расчет”, а в массиве settlements должны быть переданы объекты, с суммой всех ранее совершенных расчетов.

Чтобы сформировать чек зачёта предоплаты, вам необходимо отправить отдельный запрос на создание чека (способом Чек отдельно от платежа) и добавить в тело запроса специальный параметр offset равный значению true* При этом способ отправки чека не зависит от того способа, который подключен в вашем личном кабинете. Поэтому, если вы хотите сформировать чек зачёта предоплаты способом Чек отдельно от платежа, но при этом в настройках онлайн-кассы у вас подключен другой способ, то вносить изменения в настройки не нужно.

*Если вы не передадите этот параметр, то Paybox не сможет создать чек зачёта предоплаты.

Пример запроса на создание чека зачёта предоплаты

curl --location --request POST 'https://api.freedompay.uz/v5/receipts' \
--header'Accept: application/json' \
--header'X-JWS-Signature:{{Ваш JWS-токен}}' \
--header'Content-Type: application/json' \
--data-raw \
'{
  "receipt_format": "ru_1_05",
  "merchant_id": 542088,
  "payment_id": 754810596,
  "offset": true,
  "operation_type": "sell",
  "customer": {
    "email": "customer@mail.ru"
  },
  "positions": [
    {
      "price": 200.00,
      "name": "Товар№1",
      "quantity": 1.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    }
  ],
  "settlements": [
    {
      "type": "prepayment",
      "sum": 200.00
    }
  ]
}'

В ответе Paybox вернёт объект вашего чека

{
    "data": {
        "merchant_id": "542088",
        "receipt_id": "bb938d6c-6c1c-44a0-aa54-32c3e14fddb7",
        "operation_type": "sell",
        "receipt_format": "ru_1_05",
        "status": "registered",
        "fiscal_document_number": 10605,
        "fiscal_storage_number": "9999078900006286",
        "fiscal_attribute": 923085333,
        "registered_at": "29.03.202317:37:00",
        "created_at": "29.03.202320:39:16",
        "fiscal_provider_id": "5e402526-0c20-41c3-b30a-b52e7f903922",
        "positions": [
            {
                "name": "Товар №1",
                "quantity": 1,
                "price": 200,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 200
            }
        ],
        "total": 200,
        "settlements": [
            {
                "type": "prepayment",
                "sum": 200
            }
        ],
        "company": {
            "inn": "5544332219",
            "email": "customer@mail.ru",
            "tax_system": "osn",
            "payment_address": "shop.ru"
        },
        "receipt_method": "separately",
        "error": null,
        "link": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006286&fp=923085333&i=10605&t=20230329T173700&s=7&n=2",
        "payment_id": "754810596"
    }
}

Краткое руководство по подготовке данных для чека
Проверьте, что вы корректно передаете данные для чеков в объекте pg_receipt:

если вы формируете чек прихода вместе с платежом, проверьте, что объект pg_receipt присутствует только в тех запросах, где он действительно необходим;
переданы все обязательные параметры;
значения параметров имеют корректный формат;
в чеке содержится не более 100товаров;
сумма платежа в pg_amount совпадает с общей суммой чека вpg_receipt (чтобы определить сумму чека, для каждого товара умножьте quantity на price и просуммируйте получившиеся значения по всем товарам);
сумма частичного клиринга вpg_clearing_amount совпадает с общей суммой чека вpg_receipt (чтобы определить сумму чека, для каждого товара умножьте quantity на price и просуммируйте получившиеся значения по всем товарам);
сумма
все суммы в чеке положительные.

Чеки при возвратах
Чек возврата прихода вместе с возвратом
Если вы выбрали способ отправки чеков Чек вместе с платежом, данные для формирования чека возврата прихода необходимо передавать только при выполнении частичного возврата (запрос на revoke.php).

Чтобы сформировать чек возврата прихода, необходимо вместе с данными для частичного возврата платежа передать в запросе объект pg_receipt.

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

curl --location --request POST 'https://api.freedompay.uz/revoke.php' \
--header 'Content-Type: application/json' \
--data-raw \
'{
  "pg_merchant_id": 542088,
  "pg_payment_id": 764197452,
  "pg_refund_amount": 100,
  "pg_salt": "default",
  "pg_receipt": {
    "receipt_format": "ru_1_05",
    "customer": {
      "email": "vinni@mail.ru"
    },
    "positions": [
      {
        "price": 100.00,
        "name": "Товар №1",
        "quantity": 1.00,
        "vat_code": "vat_20",
        "payment_method": "full_payment",
        "payment_object": "goods"
      }
    ]
  },
  "pg_sig": "{{Ваша подпись запроса}}"
}'

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

Если вы проводите двухэтапный платёж и после завершения операции частичного клиринга хотите полностью вернуть списанную сумму, то такой возврат будет считаться не полным, а частичным, поэтому при выполнении возврата списанной суммы вам необходимо передать объект pg_receipt

Если возврат будет завершён успешно, в личном кабинете магазина, при клике на возврате и переходе на вкладку Чеки платежа, появится чек под названием "Чек возврата прихода". Также данный чек будет доступен в разделе
**Чеки, расположенном на левой панели главного меню.

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

Данные для формирования чека возврата прихода нужно передавать всегда в отдельном запросе, сразу после того как вы убедились, что возврат завершён успешно (параметр pg_transaction_status равен значению refunded).

В этом случае при отправке запроса на возврат платежа, вам не нужно передавать в теле запроса объект pg_receipt.

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

Отправить запрос на возврат платежа;
Сохранить полученный в ответе идентификатор возврата pg_revoke_payment_id;
Выполнить запрос на получение статуса платежа и убедиться, что возврат по нему завершён успешно;
Отправить запрос на создание чека возврата прихода, при этом в теле запроса передать параметр refund_id, значением которого будет идентификатор возврата, полученный от Paybox на шаге №2. Также необходимо передать тип кассовой операции operation_type, равный sell_refund, и другие обязательные для создания чека параметры.

Пример запроса на создание чека возврата прихода отдельно от возврата

curl --location --request POST 'https://api.freedompay.uz/v5/receipts' \
--header 'Accept: application/json' \
--header 'X-JWS-Signature:{{Ваш JWS-токен}}' \
--header 'Content-Type: application/json' \
--data-raw \
'{
  "receipt_format": "ru_1_05",
  "merchant_id": 542088,
  "refund_id": 764266262,
  "operation_type": "sell_refund",
  "customer": {
    "email": "customer@mail.ru"
  },
  "positions": [
    {
      "price": 50.00,
      "name": "Товар №1",
      "quantity": 2.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    },
    {
      "price": 100.00,
      "name": "Товар №2",
      "quantity": 1.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    }
  ],
  "settlements": [
    {
      "type": "cashless",
      "sum": 200.00
    }
  ]
}'

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

{
    "data": {
        "merchant_id": "542088",
        "receipt_id": "bb938d6c-6c1c-44a0-aa54-32c3e14fddb7",
        "operation_type": "sell_refund",
        "receipt_format": "ru_1_05",
        "status": "registered",
        "fiscal_document_number": 10605,
        "fiscal_storage_number": "9999078900006286",
        "fiscal_attribute": 923085333,
        "registered_at": "29.03.202317:37:00",
        "created_at": "29.03.202320:39:16",
        "fiscal_provider_id": "5e402526-0c20-41c3-b30a-b52e7f903922",
        "positions": [
            {
                "name": "Товар №1",
                "quantity": 2,
                "price": 50,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            },
            {
                "name": "Товар №2",
                "quantity": 1,
                "price": 100,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            }
        ],
        "total": 200,
        "settlements": [
            {
                "type": "cashless",
                "sum": 200
            }
        ],
        "company": {
            "inn": "5544332219",
            "email": "customer@mail.ru",
            "tax_system": "osn",
            "payment_address": "shop.ru"
        },
        "receipt_method": "separately",
        "error": null,
        "link": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006286&fp=923085333&i=10605&t=20230329T173700&s=7&n=2",
        "refund_id": "764266262"
    }
}

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

Если по платежу, для которого вы ранее создали чек прихода, был выполнен частичный клиринг или по каким-то причинам вы были вынуждены его отменить (платёж в статусе revoked), вам необходимо самостоятельно сформировать чек возврата прихода.

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

Отправить запрос на отмену платежа;
Сохранить полученный в ответе идентификатор отмены pg_cancel_payment_id;
Выполнить запрос на получение статуса платежа и убедиться, что отмена по нему завершена успешно;
Отправить запрос на создание чека возврата прихода, при этом, в теле запроса передать параметр refund_id, значением которого будет идентификатор отмены, полученный от Paybox на шаге №2. Также необходимо передать тип кассовой операции operation_type, равный sell_refund, и другие обязательные для создания чека параметры.

если вы формируете чек возврата прихода вместе с возвратом, проверьте, что объект pg_receipt присутствует только в запросе на частичный возврат;
переданы все обязательные параметры;
значения параметров имеют корректный формат;
количество товара не превышает то количество, которое было указано в чеке прихода;
сумма возврата вpg_refund_amount совпадает с общей суммой чека вpg_receipt (чтобы определить сумму чека, для каждого товара умножьте quantity на price и просуммируйте получившиеся значения по всем товарам);
все суммы в чеке положительные.

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

Формат чека
Тип операции
Система налогообложения
Код вида документа
Налоговые ставки НДС
Признак предмета расчета
Признак способа расчета
Мера количества предмета расчета
Тип расчета
Признак агента по предмету расчета
Идентификатор ФОИВ

Формат чека передаётся в параметре receipt_format. Возможные значения:

Значение	Описания
ru_1_05	ФФД 1.05
ru_1_1	ФФД 1.1
ru_1_2	ФФД 1.2

Значение	Описания
sell	Приход
sell_refund	Возврат прихода

Система налогообложения (СНО)
Система налогообложения передаётся в параметре tax_system. Возможные значения:

Значение	Описания
osn	Общая система налогообложения
usn_income	Упрощенная (УСН, доходы)
usn_income_outcome	Упрощенная (УСН, доходы минус расходы)
envd	Единый налог на вмененный доход (ЕНВД)
esn	Единый сельскохозяйственный налог (ЕСН)
patent	Патентная система налогообложения

Код вида документа

Код вида документа передаётся в параметре document_code. Возможные значения:

Документы, удостоверяющие личность граждан Российской Федерации

Значение	Описание
21	Паспорт гражданина Российской Федерации
22	Паспорт гражданина Российской Федерации, дипломатический паспорт, служебный паспорт, удостоверяющие личность гражданина Российской Федерации за пределами Российской Федерации
26	Временное удостоверение личности гражданина Российской Федерации, выдаваемое на период оформления паспорта гражданина Российской Федерации
27	Свидетельство о рождении гражданина Российской Федерации (для граждан Российской Федерации в возрасте до 14 лет)
28	Иные документы, признаваемые документами, удостоверяющими личность гражданина Российской Федерации в соответствии с законодательством Российской Федерации

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

Значение	Описание
31	Паспорт иностранного гражданина
32	Иные документы, признаваемые документами, удостоверяющими личность иностранного гражданина в соответствии с законодательством Российской Федерации и международным договором Российской Федерации
33	Документ, выданный иностранным государством и признаваемый в соответствии с международным договором Российской Федерации в качестве документа, удостоверяющего личность лица без гражданства.
34	Вид на жительство (для лиц без гражданства)
35	Разрешение на временное проживание (для лиц без гражданства)
36	Свидетельство о рассмотрении ходатайства о признании лица без гражданства беженцем на территории Российской Федерации по существу
37	Удостоверение беженца
38	Иные документы, признаваемые документами, удостоверяющими личность лиц без гражданства в соответствии с законодательством Российской Федерации и международным договором Российской Федерации
40	Документ, удостоверяющий личность лица, не имеющего действительного документа, удостоверяющего личность, на период рассмотрения заявления о признании гражданином Российской Федерации или о приеме в гражданство Российской Федерации

31;Паспорт иностранного гражданина 32;Иные документы, признаваемые документами, удостоверяющими личность иностранного гражданина в соответствии с законодательством Российской Федерации и международным договором Российской Федерации 33;Документ, выданный иностранным государством и признаваемый в соответствии с международным договором Российской Федерации в качестве документа, удостоверяющего личность лица без гражданства. 34;Вид на жительство (для лиц без гражданства) 35;Разрешение на временное проживание (для лиц без гражданства) 36;Свидетельство о рассмотрении ходатайства о признании лица без гражданства беженцем на территории Российской Федерации по существу 37;Удостоверение беженца 38;Иные документы, признаваемые документами, удостоверяющими личность лиц без гражданства в соответствии с законодательством Российской Федерации и международным договором Российской Федерации 40;Документ, удостоверяющий личность лица, не имеющего действительного документа, удостоверяющего личность, на период рассмотрения заявления о признании гражданином Российской Федерации или о приеме в гражданство Российской Федерации

**Налоговые ставки НДС**
Налоговая ставка НДС передаётся в массиве positions.vat_code. Возможные значения:

Значение	Описание
none	Без НДС
vat_0	НДС 0%
vat_10	НДС 10%
vat_20	НДС 20%
vat_110	НДС 10/110
vat_120	НДС 20/120

Признак предмета расчета
Признак предмета расчета передаётся в массиве positions.payment_object. Возможные значения:
** Доступно, начиная сФФД 1.05

Значение	Описание
goods	Товар
excise_goods	Подакцизный товар
job	Работа
service	Услуга
gambling_bet	Ставка азартной игры
gambling_win	Выигрыш азартной игры
lottery_ticket	Лотерейный билет
lottery_win	Выигрыш в лотереи
intellectual_activity	Результаты интеллектуальной деятельности
payment	Платеж
agent_commission	Агентское вознаграждение
payout	Выплата
another_subject	Иной предмет расчета
property_right	Имущественное право
non_operating_income	Внереализационный доход
insurance_contributions	Страховые взносы
trade_collection	Торговый сбор
resort_collection	Курортный сбор
pledge	Залог
expense	Расход
pension_insurance_ip	Взносы на обязательное пенсионное страхование ИП
pension_insurance	Взносы на обязательное пенсионное страхование
health_insurance_ip	Взносы на обязательное медицинское страхование ИП
health_insurance	Взносы на обязательное медицинское страхование
social_insurance	Взносы на обязательное социальное страхование
casino	Платеж казино
insurance_collection	Страховые взносы

Доступно, начиная сФФД 1.2

Значение	Описание
others	Иные платежи и взносы
money_withdrawals	Выдача денежных средств
non_marked_excise_goods	Подакцизный товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки (в чеке— АТНМ). Пример: алкогольная продукция
marked_excise_goods	Подакцизный товар, подлежащий маркировке средством идентификации, имеющий код маркировки (в чеке— АТМ). Пример: табак
non_marked_goods	Товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки, за исключением подакцизного товара (в чеке— ТНМ). Пример: меховые изделия
marked_goods	Товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара (в чеке— ТМ). Пример: обувь, духи, товары легкой промышленности

Признак способа расчета
Признак способа расчета передаётся в массиве positions.payment_method. Возможные значения:

Значение	Описание
full_prepayment	Предоплата 100%
partial_prepayment	Предоплата
advance	Аванс
full_payment	Полный расчет
partial_payment	Частичный расчет и кредит
credit	Передача в кредит
credit_payment	Выплата по кредиту

Мера количества предмета расчета
Мера количества предмета расчета передаётся в массиве positions.measure. Возможные значения:

Значение	Описание
piece	Штука
gram	Грамм
kilogram	Килограмм
ton	Тонна
centimeter	Сантиметр
decimeter	Дециметр
meter	Метр
square_centimeter	Квадратный сантиметр
square_decimeter	Квадратный дециметр
square_meter	Квадратный метр
milliliter	Миллилитр
liter	Литр
cubic_meter	Кубический метр
kilowatt_hour	Киловатт-час
gigacalorie	Гигакалория
day	Сутки
hour	Час
minute	Минута
second	Секунда
kilobyte	Килобайт
megabyte	Мегабайт
gigabyte	Гигабайт
terabyte	Терабайт
rest	Остальное

Тип расчета
Тип расчета передаётся в массиве settlements.type. Возможные значения:

Значение	Описание
cashless	Безналичный расчет
prepayment	Предоплата (аванс)
postpayment	Постоплата (кредит)
counter_providing	Встречное предоставление

Признак агента по предмету расчета
Признак агента по предмету расчета передаётся в массиве positions.agent_type. Возможные значения:

Значение	Описание
bank_payment_agent	Банковский платежный агент
bank_payment_subagent	Банковский платежный субагент
payment_agent	Платежный агент
payment_subagent	Платежный субагент
attorney	Поверенный
commissioner	Комиссионер
agent	Агент

Идентификатор ФОИВ
Идентификатор ФОИВ передаётся в массиве payment_object_industry_details.federal_id и массиве receipt_industry_details.federal_id. Возможные значения - от 001 до 072.

Описание	Значение
Министерство внутренних дел Российской Федерации	001
Министерство Российской Федерации по делам гражданской обороны, чрезвычайным ситуациям и ликвидации последствий стихийных бедствий	002
Министерство иностранных дел Российской Федерации	003
Федеральное агентство по делам Содружества Независимых Государств, соотечественников, проживающих за рубежом, и по международному гуманитарному сотрудничеству	004
Министерство обороны Российской Федерации	005
Федеральная служба по военно-техническому сотрудничеству	006
Федеральная служба по техническому и экспортному контролю	007
Министерство юстиции Российской Федерации	008
Федеральная служба исполнения наказаний	009
Федеральная служба судебных приставов	010
Государственная фельдъегерская служба Российской Федерации (федеральная служба)	011
Служба внешней разведки Российской Федерации (федеральная служба)	012
Федеральная служба безопасности Российской Федерации (федеральная служба)	013
Федеральная служба войск национальной гвардии Российской Федерации (федеральная служба)	014
Федеральная служба охраны Российской Федерации (федеральная служба)	015
Федеральная служба по финансовому мониторингу (федеральная служба)	016
Федеральное архивное агентство (федеральное агентство)	017
Главное управление специальных программ Президента Российской Федерации (федеральное агентство)	018
Управление делами Президента Российской Федерации (федеральное агентство)	019
Министерство здравоохранения Российской Федерации	020
Федеральная служба по надзору в сфере здравоохранения	021
Министерство культуры Российской Федерации	022
Министерство науки и высшего образования Российской Федерации	023
Министерство природных ресурсов и экологии Российской Федерации	024
Федеральная служба по гидрометеорологии и мониторингу окружающей среды	025
Федеральная служба по надзору в сфере природопользования	026
Федеральное агентство водных ресурсов	027
Федеральное агентство лесного хозяйства	028
Федеральное агентство по недропользованию	029
Министерство промышленности и торговли Российской Федерации	030
Федеральное агентство по техническому регулированию и метрологии	031
Министерство просвещения Российской Федерации	032
Министерство Российской Федерации по развитию Дальнего Востока и Арктики	033
Министерство сельского хозяйства Российской Федерации	034
Федеральная служба по ветеринарному и фитосанитарному надзору	035
Федеральное агентство по рыболовству	036
Министерство спорта Российской Федерации	037
Министерство строительства и жилищно-коммунального хозяйства Российской Федерации	038
Министерство транспорта Российской Федерации	039
Федеральная служба по надзору в сфере транспорта	040
Федеральное агентство воздушного транспорта	041
Федеральное дорожное агентство	042
Федеральное агентство железнодорожного транспорта	043
Федеральное агентство морского и речного транспорта	044
Министерство труда и социальной защиты Российской Федерации	045
Федеральная служба по труду и занятости	046
Министерство финансов Российской Федерации	047
Федеральная налоговая служба	048
Федеральная пробирная палата (федеральная служба)	049
Федеральная служба по регулированию алкогольного рынка	050
Федеральная таможенная служба	051
Федеральное казначейство (федеральная служба)	052
Федеральное агентство по управлению государственным имуществом	053
Министерство цифрового развития, связи и массовых коммуникаций Российской Федерации	054
Федеральная служба по надзору в сфере связи, информационных технологий и массовых коммуникаций	055
Федеральное агентство по печати и массовым коммуникациям	056
Федеральное агентство связи	057
Министерство экономического развития Российской Федерации	058
Федеральная служба по аккредитации	059
Федеральная служба государственной статистики	060
Федеральная служба по интеллектуальной собственности	061
Федеральное агентство по туризму	062
Министерство энергетики Российской Федерации	063
Федеральная антимонопольная служба	064
Федеральная служба государственной регистрации, кадастра и картографии	065
Федеральная служба по надзору в сфере защиты прав потребителей и благополучия человека	066
Федеральная служба по надзору в сфере образования и науки	067
Федеральная служба по экологическому, технологическому и атомному надзору	068
Федеральное агентство по государственным резервам	069
Федеральное медико-биологическое агентство	070
Федеральное агентство по делам молодежи	071
Федеральное агентство по делам национальностей	072

Министерство внутренних дел Российской Федерации;001 Министерство Российской Федерации по делам гражданской обороны, чрезвычайным ситуациям и ликвидации последствий стихийных бедствий;002 Министерство иностранных дел Российской Федерации;003 Федеральное агентство по делам Содружества Независимых Государств, соотечественников, проживающих за рубежом, и по международному гуманитарному сотрудничеству;004 Министерство обороны Российской Федерации;005 Федеральная служба по военно-техническому сотрудничеству;006 Федеральная служба по техническому и экспортному контролю;007 Министерство юстиции Российской Федерации;008 Федеральная служба исполнения наказаний;009 Федеральная служба судебных приставов;010 Государственная фельдъегерская служба Российской Федерации (федеральная служба);011 Служба внешней разведки Российской Федерации (федеральная служба);012 Федеральная служба безопасности Российской Федерации (федеральная служба);013 Федеральная служба войск национальной гвардии Российской Федерации (федеральная служба);014 Федеральная служба охраны Российской Федерации (федеральная служба);015 Федеральная служба по финансовому мониторингу (федеральная служба);016 Федеральное архивное агентство (федеральное агентство);017 Главное управление специальных программ Президента Российской Федерации (федеральное агентство);018 Управление делами Президента Российской Федерации (федеральное агентство);019 Министерство здравоохранения Российской Федерации;020 Федеральная служба по надзору в сфере здравоохранения;021 Министерство культуры Российской Федерации;022 Министерство науки и высшего образования Российской Федерации;023 Министерство природных ресурсов и экологии Российской Федерации;024 Федеральная служба по гидрометеорологии и мониторингу окружающей среды;025 Федеральная служба по надзору в сфере природопользования;026 Федеральное агентство водных ресурсов;027 Федеральное агентство лесного хозяйства;028 Федеральное агентство по недропользованию;029 Министерство промышленности и торговли Российской Федерации;030 Федеральное агентство по техническому регулированию и метрологии;031 Министерство просвещения Российской Федерации;032 Министерство Российской Федерации по развитию Дальнего Востока и Арктики;033 Министерство сельского хозяйства Российской Федерации;034 Федеральная служба по ветеринарному и фитосанитарному надзору;035 Федеральное агентство по рыболовству;036 Министерство спорта Российской Федерации;037 Министерство строительства и жилищно-коммунального хозяйства Российской Федерации;038 Министерство транспорта Российской Федерации;039 Федеральная служба по надзору в сфере транспорта;040 Федеральное агентство воздушного транспорта;041 Федеральное дорожное агентство;042 Федеральное агентство железнодорожного транспорта;043 Федеральное агентство морского и речного транспорта;044 Министерство труда и социальной защиты Российской Федерации;045 Федеральная служба по труду и занятости;046 Министерство финансов Российской Федерации;047 Федеральная налоговая служба;048 Федеральная пробирная палата (федеральная служба);049 Федеральная служба по регулированию алкогольного рынка;050 Федеральная таможенная служба;051 Федеральное казначейство (федеральная служба);052 Федеральное агентство по управлению государственным имуществом;053 Министерство цифрового развития, связи и массовых коммуникаций Российской Федерации;054 Федеральная служба по надзору в сфере связи, информационных технологий и массовых коммуникаций;055 Федеральное агентство по печати и массовым коммуникациям;056 Федеральное агентство связи;057 Министерство экономического развития Российской Федерации;058 Федеральная служба по аккредитации;059 Федеральная служба государственной статистики;060 Федеральная служба по интеллектуальной собственности;061 Федеральное агентство по туризму;062 Министерство энергетики Российской Федерации;063 Федеральная антимонопольная служба;064 Федеральная служба государственной регистрации, кадастра и картографии;065 Федеральная служба по надзору в сфере защиты прав потребителей и благополучия человека;066 Федеральная служба по надзору в сфере образования и науки;067 Федеральная служба по экологическому, технологическому и атомному надзору;068 Федеральное агентство по государственным резервам;069 Федеральное медико-биологическое агентство;070 Федеральное агентство по делам молодежи;071 Федеральное агентство по делам национальностей;072