Введение

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

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

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

Практический каждый магазин, который продаёт в онлайне, обязан формировать чек в соответствии с 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 Настройка → Способ формирования чека, выберите режим Чек отдельно от платежа.
Необходимые шаги для интеграции
  1. Подключите онлайн-кассу, которая входит в перечень наших технологических партнёров.
  2. Заключите договор с оператором фискальных данных, не забудьте подключить услугу по отправке чеков на электронную почту покупателя.
  3. Выполните настройки в разделе "Онлайн-касса" вашего личного кабинета 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
Чеки при платежах
Общий сценарий
  1. Выберите способ формирования чека
  2. Сформируйте чек прихода в запросе на инициализацию платежа или отдельным запросом, в зависимости от выбранного способа.
  3. Если в чеке прихода были товары с предоплатой, то при их выдаче сформируйте чек зачёта предоплаты
Чек прихода вместе с платежом
Если вы выбрали способ отправки чеков Чек вместе с платежом, данные для формирования чека прихода необходимо передавать в следующих сценариях:
  • при инициализации, в случае проведения платежа в один этап (запрос на 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.

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

  1. Отправить запрос на инициализацию платежа;
  2. Сохранить полученный в ответе от Paybox идентификатор платежа pg_payment_id;
  3. Выполнить запрос на получение статуса платежа и убедиться, что платёж завершился успешно;
  4. Отправить запрос на создание чека прихода, при этом в теле запроса передать параметр 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:

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

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

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

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

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

  1. Чек прихода - в момент приёма оплаты на сайте. При этом все товары в сформированном чеке должны иметь признак способа расчета с одним из следующих значений: “Предоплата”, “Предоплата 100%” или Аванс
  2. Чек зачёта предоплаты - сразу после передачи товара покупателю. Все товары в этом чеке должны содержать признак способа расчета “Полный расчет”, а в массиве 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.

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

  1. Отправить запрос на возврат платежа;
  2. Сохранить полученный в ответе идентификатор возврата pg_revoke_payment_id;
  3. Выполнить запрос на получение статуса платежа и убедиться, что возврат по нему завершён успешно;
  4. Отправить запрос на создание чека возврата прихода, при этом в теле запроса передать параметр 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), вам необходимо самостоятельно сформировать чек возврата прихода.

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

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

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

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

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


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


Документы, удостоверяющие личность иностранных граждан или лиц без гражданства
**Налоговые ставки НДС**
Налоговая ставка НДС передаётся в массиве positions.vat_code. Возможные значения:
Признак предмета расчета
Признак предмета расчета передаётся в массиве positions.payment_object. Возможные значения:
** Доступно, начиная сФФД 1.05
Доступно, начиная сФФД 1.2
Признак способа расчета
Признак способа расчета передаётся в массиве positions.payment_method. Возможные значения:

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

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

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

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