# Mandarin.Kassir

Mandarin.Kassir — сервис фискализации операций Mandarin. Он формирует фискальные чеки при приеме платежей, возвратах и выплатах и передает данные в онлайн-кассу для регистрации в ФНС.

# Начало работы

Mandarin передает фискальные данные в облачные онлайн-кассы. Поддерживаются провайдеры:

Также доступна агентская касса Mandarin — подключение без собственной кассы (см. ниже).

Схемы формирования чеков:

Схема	Когда использовать
Автоматическое формирование	Блок `fiscalInformation` передается в запросе платежа, возврата или выплаты
Самостоятельное формирование	Чек создается отдельным запросом после операции

# БИФИТ Онлайн

Что нужно до интеграции

Аккаунт Mandarin — регистрация (opens new window);
Аккаунт в «БИФИТ Касса» — инструкция (opens new window);
Облачная касса в аренде, зарегистрированная в ФНС и подключенная к ОФД — инструкция (opens new window).

Шаги подключения

Получите токен кассы в «БИФИТ Касса» — инструкция (opens new window).
Передайте токен и Client ID (opens new window) в службу поддержки (opens new window) Mandarin или вашему менеджеру.
Добавьте объект fiscalInformation в запросы — см. Автоматическое формирование чека.

# АТОЛ Онлайн

Что нужно до интеграции

Аккаунт Mandarin — регистрация (opens new window);
Аккаунт в «АТОЛ Онлайн» — регистрация (opens new window);
Облачная касса в аренде, зарегистрированная в ФНС и подключенная к ОФД — инструкция (opens new window).

Шаги подключения

Получите данные от кассы в файле «Настройки интегратора» в ЛК «АТОЛ Онлайн» — инструкция (opens new window) (стр. 75–76).
Передайте файл и Client ID (opens new window) в службу поддержки (opens new window) Mandarin или вашему менеджеру.
Добавьте объект fiscalInformation в запросы — см. Автоматическое формирование чека.

# Агентская касса Mandarin

Подключение онлайн-кассы по агентской схеме без аренды собственной ККТ. В чеке указываются:

агент — ООО «Мандарин», ИНН 7708816952;
поставщик — ваша компания.

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

Для автоматического формирования чека передайте fiscalInformation по инструкции для агентского чека. При использовании кассы Mandarin блок shipper в запросе платежа не передается — данные поставщика настраиваются на стороне Mandarin.

При самостоятельном формировании чека через API api.psp.io блок shipper обязателен: в нем указываются данные вашей компании как поставщика услуг/товаров. Подробнее — в разделе Самостоятельное формирование чека.

Важно!

При использовании кассы Mandarin в параметре taxationSystem указывайте только Common (ОСН). Другие значения приведут к ошибке формирования чека.

# Справочники

# Справочник систем налогообложения

Значение	Описание
`Common`	Общая (ОСН)
`Simplified`	Упрощенная (УСН) «Доходы»
`SimplifiedMinusOutlay`	Упрощенная (УСН) «Доходы минус расходы»
`UnifiedImputedIncome`	Единый налог на вмененный доход (ЕНВД)
`UnifiedAgricultural`	Единый сельскохозяйственный налог (ЕСХН)
`Patent`	Патентная (ПСН)

# Справочник ставок НДС

Значение	Описание
`None`	Без НДС
`Vat0`	НДС по ставке 0%
`vat5`	НДС по ставке 5%
`vat7`	НДС по ставке 7%
`Vat10`	НДС по ставке 10%
`Vat20`	НДС по ставке 20%
`Vat22`	НДС по ставке 22%
`vat105`	НДС по расчетной ставке 5/105
`vat107`	НДС по расчетной ставке 7/107

# Справочник способов расчета

Значение	Описание
`PREPAY_FULL`	Полная предварительная оплата до момента передачи предмета расчета
`PREPAY_PARTIAL`	Частичная предварительная оплата до момента передачи предмета расчета
`AVANS`	Аванс
`FULL_PAY`	Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета
`PARTIAL_SETTLEMENT_AND_CREDIT`	Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит
`TRANSFER_ON_CREDIT`	Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит
`CREDIT_PAYMENT`	Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита)

# Справочник предметов расчета

Значение	Описание
`AGENCY`	Агентское вознаграждение
`COMPOUND_SUBJECT`	Составной предмет расчета
`EXCISABLE_PRODUCT`	Подакцизный товар
`GAMBLING_RATE`	Ставка азартной игры
`GAMBLING_WIN`	Выигрыш азартной игры
`INSURANCE_CONTRIBUTIONS`	Страховые взносы
`JOB`	Работа
`LOTTERY_TICKET`	Лотерейный билет
`LOTTERY_WIN`	Выигрыш лотереи
`NON_OPERATING_INCOME`	Внереализационный доход
`OTHER_SUBJECT`	Иной предмет расчета
`PAYMENT`	Платеж
`PLEDGE`	Залог
`PRODUCT`	Товар
`PROPERTY_LAW`	Имущественное право
`PROVISION_RID`	Представление РИД
`RESORT_FEE`	Курортный сбор
`SERVICE`	Услуга
`TRADE_FEE`	Торговый сбор

# Типы чеков и их назначение

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

Тип чека	Когда формируется	Описание
Приход	При поступлении денежных средств от покупателя	Стандартный чек на оплату товаров/услуг. Формируется при успешном платеже.
Возврат прихода	При возврате денежных средств покупателю	Чек, подтверждающий возврат ранее оплаченных средств. Формируется при отмене платежа или возврате.
Расход	При выдаче денежных средств (например, выплата поставщику или вывод средств)	Чек, подтверждающий расходную операцию. Формируется при выплатах.
Возврат расхода	При возврате ранее выданных денежных средств	Чек, подтверждающий возврат средств от контрагента. Формируется при отмене выплаты.
Чек коррекции прихода	Для исправления ошибок в ранее сформированных чеках прихода	Формируется, если в исходном чеке была допущена ошибка (не был выбит чек изначально, неверная сумма, ставка НДС, наименование и т.п.) и требуется корректно отразить операцию в фискальной системе.
Чек коррекции расхода	Для исправления ошибок в ранее сформированных чеках расхода	Аналогично коррекции прихода, но для расходных операций.
Чек коррекции возврата прихода	Для исправления ошибок в чеках возврата прихода	Корректирует некорректно оформленный возврат средств или если чек не был выбит на возврат.
Чек коррекции возврата расхода	Для исправления ошибок в чеках возврата расхода	Корректирует некорректно оформленный возврат расходной операции или если чек не был выбит на возврат.

# Автоматическое формирование чека

Чек формируется автоматически при успешном проведении операции, если в запрос на POST https://secure.mandarinpay.com/api/transactions передан объект fiscalInformation.

# Поддерживаемые операции

`payment.action`	Операция	Тип фискального чека
`pay`	Списание средств с карты (платеж)	Приход
`reversal`	Разблокировка средств после двухстадийной авторизации (`preauth`). Деньги на карту не списывались	Возврат прихода
`refund`	Возврат средств покупателю по уже успешно проведенной операции списания (`pay`), в том числе частичный	Возврат прихода
`payout`	Выплата на карту	Расход

Объект fiscalInformation содержит систему налогообложения (taxationSystem) и массив позиций чека (items). Каждая позиция описывает наименование, количество, сумму строки и ставку НДС.

# Аутентификация

Запросы аутентифицируются заголовком x-auth. Формирование значения — в разделе Аутентификация запросов.

Два API — разные поля для типа операции

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

1. Автоматическое формирование чека (этот раздел)
Эндпоинт: POST https://secure.mandarinpay.com/api/transactions
Тип операции задается в payment.action: pay, reversal, refund, payout.
Чек формируется автоматически вместе с платежом, если передан блок fiscalInformation.

2. Самостоятельное формирование чека
Эндпоинт: POST https://api.psp.io/receipts/public/receipts
Тип чека задается полем action (число) или ActionType (строка) — достаточно одного из них.

Тип чека	`action`	`ActionType`
Приход	`1`	`Receipt`
Возврат прихода	`2`	`Refund`
Расход	`3`	`Purchase`
Возврат расхода	`4`	`PurchaseRefund`

Соответствие полей

При самостоятельном формировании используются те же значения, но другие имена полей: taxSystem вместо taxationSystem, name вместо description, price вместо totalPrice.

# Параметры fiscalInformation

Параметр	Обязательность	Описание
`fiscalInformation`	При необходимости	Блок фискальных данных. Передается, если нужен чек
`fiscalInformation.taxationSystem`	Да	Система налогообложения для всего чека. См. справочник
`fiscalInformation.items[]`	Да	Массив товарных позиций
`fiscalInformation.items[].description`	Да	Наименование товара, работы или услуги
`fiscalInformation.items[].quantity`	Да	Количество. Допускаются дробные значения
`fiscalInformation.items[].totalPrice`	Да	Сумма по строке (строка с двумя знаками после запятой, например `"800.00"`)
`fiscalInformation.items[].vat`	Да	Ставка НДС. См. справочник НДС
`fiscalInformation.items[].calculationMethod`	Нет	Способ расчета. По умолчанию `FULL_PAY`. См. справочник
`fiscalInformation.items[].paymentSubject`	Нет	Предмет расчета. По умолчанию `SERVICE`. См. справочник

Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.

# Примеры запросов

# Пример: платеж (`pay`)

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "payment": {
    "action": "pay",
    "orderId": "e36887bbed618ea111",
    "price": "200.00"
  },
  "customerInfo": {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "fiscalInformation": {
    "taxationSystem": "Common",
    "items": [
      {
        "quantity": 1,
        "vat": "Vat20",
        "description": "Доставка",
        "totalPrice": "200.00",
        "calculationMethod": "PREPAY_FULL",
        "paymentSubject": "SERVICE"
      }
    ]
  }
}'

Ответ в случае успешного создания транзакции (200 OK)

{
  "id": "43913ddc000c4d3990fddbd3980c1725",
  "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
  "jsOperationId": "9874694yr87y73e7ey39ed80"
}

# Пример: разблокировка после preauth (`reversal`)

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "payment": {
    "action": "reversal",
    "orderId": "e36887bbed618ea112",
    "price": "200.00"
  },
  "target": {
    "transaction": "43913ddc000c4d3990fddbd3980c1725"
  },
  "fiscalInformation": {
    "taxationSystem": "Common",
    "items": [
      {
        "quantity": 1,
        "vat": "Vat20",
        "description": "Разблокировка средств",
        "totalPrice": "200.00",
        "paymentSubject": "SERVICE"
      }
    ]
  }
}'

# Пример: возврат по проведенному платежу (`refund`)

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "payment": {
    "action": "refund",
    "orderId": "e36887bbed618ea113",
    "price": "200.00"
  },
  "target": {
    "transaction": "43913ddc000c4d3990fddbd3980c1725"
  },
  "fiscalInformation": {
    "taxationSystem": "Common",
    "items": [
      {
        "quantity": 1,
        "vat": "Vat20",
        "description": "Возврат услуги",
        "totalPrice": "200.00",
        "paymentSubject": "SERVICE"
      }
    ]
  }
}'

# Пример: выплата (`payout`)

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "payment": {
    "action": "payout",
    "orderId": "e36887bbed618ea114",
    "price": "200.00"
  },
  "customerInfo": {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target": {
    "card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
  },
  "fiscalInformation": {
    "taxationSystem": "Common",
    "items": [
      {
        "quantity": 1,
        "vat": "Vat20",
        "description": "Выплата",
        "totalPrice": "200.00",
        "paymentSubject": "SERVICE"
      }
    ]
  }
}'

Ответ в случае, если транзакция не создана (400 Bad request)

{
  "error": "Invalid request"
}

# Автоматическое формирование агентского чека

Используйте этот раздел, если вы выступаете посредником: принимаете оплату за товары или услуги другого лица (маркетплейс, агрегатор, платежный агент).

Чек формируется так же, как в обычном автоматическом сценарии, с теми же значениями payment.action (pay, reversal, refund, payout). В каждой позиции items дополнительно передается agentType, а блок shipper — в зависимости от сценария (см. таблицу ниже).

# Когда указывать shipper

Сценарий	`agentType`	`shipper`
Своя касса БИФИТ / АТОЛ, автоматический чек с платежом	`AGENT`	Да — данные поставщика
Касса Mandarin, автоматический чек с платежом	`AGENT`	Нет — поставщик настраивается в Mandarin
Касса Mandarin, самостоятельное формирование	`AGENT`	Да — данные вашей компании

Важно!

При использовании агентской кассы Mandarin:

Автоматический чек (блок fiscalInformation в запросе платежа / выплаты): блок shipper не передается.
Самостоятельное формирование чека (API api.psp.io/receipts/public/receipts): блок shipper обязателен — укажите данные вашей компании как поставщика услуг/товаров.

# Параметры (дополнительно к fiscalInformation)

Параметр	Обязательность	Описание
`items[].agentType`	Условно	Тип агента. Для большинства сценариев — `AGENT`
`items[].shipper`	Условно	Данные поставщика. Обязателен при своей кассе; не передается при автоматическом чеке с кассой Mandarin
`items[].shipper.name`	Да, если есть `shipper`	Наименование организации-поставщика
`items[].shipper.inn`	Да, если есть `shipper`	ИНН поставщика
`items[].shipper.phones[]`	Да, если есть `shipper`	Телефоны поставщика (массив строк)

# Значения agentType

Значение	Описание
`AGENT`	Платежный агент
`BANK_PAYMENT_AGENT`	Банковский платежный агент
`BANK_PAYMENT_SUBAGENT`	Банковский платежный субагент
`PAYMENT_AGENT`	Платежный агент (иной тип)
`PAYMENT_SUBAGENT`	Платежный субагент
`ATTORNEY`	Поверенный
`COMMISSIONER`	Комиссионер

# Аутентификация

Запросы аутентифицируются заголовком x-auth. Формирование значения — в разделе Аутентификация запросов.

# Примеры запросов

# Пример: агентский платеж (`pay`)

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "payment": {
    "action": "pay",
    "orderId": "e36887bbed618ea115",
    "price": "600.00"
  },
  "customerInfo": {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "fiscalInformation": {
    "taxationSystem": "Common",
    "items": [
      {
        "quantity": 1,
        "vat": "None",
        "description": "Оплата",
        "totalPrice": "600.00",
        "calculationMethod": "FULL_PAY",
        "paymentSubject": "SERVICE",
        "agentType": "AGENT",
        "shipper": {
          "name": "ООО Ромашка",
          "inn": "1234567890",
          "phones": ["+79111111111"]
        }
      }
    ]
  }
}'

Ответ в случае успешного создания транзакции (200 OK)

{
  "id": "43913ddc000c4d3990fddbd3980c1725",
  "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
  "jsOperationId": "9874694yr87y73e7ey39ed80"
}

# Самостоятельное формирование чека

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

Важно: самостоятельное формирование не заменяет автоматическую фискализацию в момент оплаты. Используйте его только при обоснованной необходимости и в соответствии с требованиями законодательства о применении ККТ.

Основные сценарии:

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

Чек коррекции — не «запасной» вариант

Чек коррекции нельзя формировать произвольно или вместо своевременно пробитого чека.

Если операция проведена сегодня и чек не был пробит — сформируйте обычный чек, а не коррекцию.
Чек коррекции оформляется при наличии законного основания: исправление ошибки в ранее переданных в ОФД сведениях либо отражение расчета, по которому чек не был выбит в установленный срок.
В запросе обязательно указывается блок correction с типом основания (Self — самостоятельное исправление, Prescription — по предписанию налогового органа), датой корректируемого расчета и при необходимости номером документа-основания.

Неправомерное применение чеков коррекции может повлечь нарушение требований к применению контрольно-кассовой техники. При сомнениях обратитесь к бухгалтеру или в службу поддержки (opens new window) Mandarin.

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

сумму расчета;
ставку НДС;
наименование товара, работы или услуги;
тип чека (например, вместо прихода был пробит расход);
факт расчета, по которому чек не был выбит в день операции.

# Аутентификация

Для POST-запросов (создание чеков): скоуп receipts:public_receipts.write
Для GET-запросов (просмотр статуса и списка чеков): скоуп receipts:public_receipts.read

Оба скоупа необходимо запросить при аутентификации по протоколу OAuth 2.0.

Общая структура запроса:

Все запросы на создание чека отправляются методом POST на эндпоинт:
https://api.psp.io/receipts/public/receipts
Тело запроса содержит обязательные и опциональные параметры, описывающие сам чек, товары/услуги в нем, а также информацию о клиенте и кассире.

# Формирование чека на оплату и возврат

Чек может быть агентский и неагентский (обычный).

# Агентский чек

Когда нужен: когда вы принимаете деньги не за свои товары/услуги, а за чужие (вы — посредник).

Также при использовании кассы Mandarin, где вы являетесь поставщиком услуг/товаров, а Mandarin — агентом (посредником).

Пример: маркетплейс, агрегатор услуг, платежный агент.

В API: передаете agentType и блок shipper (название, ИНН, телефон конечного получателя).

Важно!

При использовании агентской кассы Mandarin:

Автоматический чек (блок fiscalInformation в запросе платежа / выплаты): блок shipper не передается.
Самостоятельное формирование чека (данный раздел): блок shipper обязателен — укажите данные вашей компании как поставщика услуг/товаров.

# Неагентский чек (обычный)

Когда нужен: когда вы продаете свои товары или услуги.

Пример: интернет-магазин, своя доставка, консалтинг и т.д.

В API: передаете тело запроса без agentType и shipper.

# Параметры запроса

Параметр	Обязательность	Описание
`taxSystem`	Да	Система налогообложения. Возможные значения: `Common` (ОСН), `Simplified` (УСН Доходы), `SimplifiedMinusOutlay` (УСН Доходы минус расходы), `UnifiedImputedIncome` (ЕНВД), `UnifiedAgricultural` (ЕСХН), `Patent` (ПСН)
`action`	Условно	Тип чека (указывается одно из значений: `ActionType` либо `action`): • `1` — Приход (оплата) • `2` — Возврат прихода • `3` — Расход • `4` — Возврат расхода Обязателен для возвратов, расходов и коррекций. Для прихода — необязателен.
`ActionType`	Условно	Тип чека (указывается одно из значений: `ActionType` либо `action`): • `Receipt` — Приход (оплата) • `Refund` — Возврат прихода • `Purchase` — Расход • `PurchaseRefund` — Возврат расхода Обязателен для возвратов, расходов и коррекций. Для прихода — необязателен.
`isMandarinAgent`	Нет	Использовать терминал Мандарин для агентской схемы фискализации.
`cashierName`	Нет	Имя кассира.
`cashierInn`	Нет	ИНН кассира.
`customerPhone`	Условно	Номер телефона клиента. Обязателен, если не указан `customerEmail`.
`customerEmail`	Условно	Адрес электронной почты клиента. Обязателен, если не указан `customerPhone`.
`clientId`	Да	Client ID.
`merchantId`	Да	Merchant ID.
`mandarinId`	Да	ID операции в системе Mandarin (например, `TransactionId` или `OperationId`), к которой привязывается чек.

# Параметры элемента товарной позиции (`items`)

Параметр	Обязательность	Описание
`items.calculationMethod`	Да	Метод расчета. Возможные значения: `FULL_PAY`, `PREPAY_FULL`, `PREPAY_PARTIAL`, `AVANS`, `PARTIAL_SETTLEMENT_AND_CREDIT`, `TRANSFER_ON_CREDIT`, `CREDIT_PAYMENT`.
`items.agentType`	Условно	Тип контрагента для агентских чеков. Используйте `AGENT`. Обязателен, если чек агентский.
`items.shipper.name`	Условно	Название компании-поставщика (конечного получателя средств). Обязателен, если указан `agentType`.
`items.shipper.inn`	Условно	ИНН компании-поставщика. Обязателен, если указан `agentType`.
`items.shipper.phones`	Условно	Массив телефонных номеров поставщика в формате строк. Обязателен, если указан `agentType`.
`items.paymentSubject`	Да	Предмет расчета. Возможные значения: `SERVICE` (услуга), `PRODUCT` (товар), `JOB` (работа), `PAYMENT` (платеж), `AGENCY` (агентское вознаграждение) и др. Полный список — в справочнике предметов расчета.
`items.name`	Да	Наименование товара, работы или услуги.
`items.price`	Да	Цена за единицу. Ограничение: 2 знака после запятой (например, `123.45`).
`items.quantity`	Да	Количество. Допускаются дробные числа (например, `0.5`).
`items.vat`	Да	Ставка НДС. Возможные значения: `None` (без НДС), `Vat0` (0%), `vat5` (5%), `vat7` (7%), `Vat10` (10%), `Vat20` (20%), `Vat22` (22%), `vat105` (5/105), `vat107` (7/107).

# Параметры для чека коррекции

Для формирования чека коррекции в запрос необходимо добавить поле action (или ActionType) и блок correction.

Параметр	Обязательность	Описание
`action`	Условно	Тип корректируемой операции (указывается одно из значений: `ActionType` либо `action`): • `1` — Приход (оплата) • `2` — Возврат прихода • `3` — Расход • `4` — Возврат расхода
`ActionType`	Условно	Тип корректируемой операции (указывается одно из значений: `ActionType` либо `action`): • `Receipt` — Приход (оплата) • `Refund` — Возврат прихода • `Purchase` — Расход • `PurchaseRefund` — Возврат расхода
`correction`	Да	Блок данных для чека коррекции. Содержит информацию об основании для коррекции.
`correction.type`	Да	Тип коррекции: • `1` — `Self` (самостоятельная операция) • `2` — `Prescription` (операция по предписанию)
`correction.documentDate`	Да	Дата совершения корректируемого расчета. Формат: `ГГГГ-ММ-ДД` (например, `2026-06-22`).
`correction.documentNumber`	Нет	Номер документа-основания для коррекции. Указывается фискальный признак (ФП) ошибочного чека, если он был сформирован. Если чек не был пробит, поле передается пустым.

# Примеры запросов

# Пример: агентский чек на приход

curl --request POST \
  --url https://api.psp.io/receipts/public/receipts \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --data '{
    "taxSystem": "Common",
    "action": 1,
    "isMandarinAgent": true,
    "cashierName": "Mandarin",
    "customerPhone": "79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
      {
        "calculationMethod": "FULL_PAY",
        "agentType": "AGENT",
        "shipper": {
          "name": "ООО Поставщик",
          "inn": "7724923302",
          "phones": ["+79001234567"]
        },
        "paymentSubject": "SERVICE",
        "name": "Услуга",
        "price": 1000.00,
        "quantity": 1,
        "vat": "Vat20"
      }
    ]
  }'

Ответ в случае успешного создания запроса (200 OK)

{
  "data": {
    "id": 139
  }
}

# Пример: агентский чек на возврат прихода

curl --request POST \
  --url https://api.psp.io/receipts/public/receipts \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --data '{
    "taxSystem": "Common",
    "action": 2,
    "isMandarinAgent": true,
    "cashierName": "Mandarin",
    "customerPhone": "79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
      {
        "calculationMethod": "FULL_PAY",
        "agentType": "AGENT",
        "shipper": {
          "name": "ООО Поставщик",
          "inn": "7724923302",
          "phones": ["+79001234567"]
        },
        "paymentSubject": "SERVICE",
        "name": "Услуга",
        "price": 1000.00,
        "quantity": 1,
        "vat": "Vat20"
      }
    ]
  }'

# Пример: агентский чек коррекции прихода

curl --request POST \
  --url https://api.psp.io/receipts/public/receipts \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --data '{
    "taxSystem": "Common",
    "isMandarinAgent": true,
    "action": 1,
    "cashierName": "Mandarin",
    "customerPhone": "79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
      {
        "calculationMethod": "FULL_PAY",
        "agentType": "AGENT",
        "shipper": {
          "name": "ООО Поставщик",
          "inn": "7724923302",
          "phones": ["+79001234567"]
        },
        "paymentSubject": "SERVICE",
        "name": "Услуга",
        "price": 1000.00,
        "quantity": 1,
        "vat": "Vat20"
      }
    ],
    "correction": {
      "type": 1,
      "documentDate": "2026-06-22",
      "documentNumber": "1234567890"
    }
  }'

# Пример: неагентский чек на приход

curl --request POST \
  --url https://api.psp.io/receipts/public/receipts \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --data '{
    "taxSystem": "Common",
    "action": 1,
    "cashierName": "Иванов И.И.",
    "cashierInn": "1234567890",
    "customerPhone": "79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
      {
        "calculationMethod": "FULL_PAY",
        "paymentSubject": "SERVICE",
        "name": "Оплата услуги",
        "price": 1000.00,
        "quantity": 1,
        "vat": "Vat20"
      }
    ]
  }'

# Пример: неагентский чек на возврат прихода

curl --request POST \
  --url https://api.psp.io/receipts/public/receipts \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --data '{
    "taxSystem": "Common",
    "action": 2,
    "cashierName": "Иванов И.И.",
    "cashierInn": "1234567890",
    "customerPhone": "79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
      {
        "calculationMethod": "FULL_PAY",
        "paymentSubject": "SERVICE",
        "name": "Возврат услуги",
        "price": 1000.00,
        "quantity": 1,
        "vat": "Vat20"
      }
    ]
  }'

# Пример: неагентский чек коррекции прихода

curl --request POST \
  --url https://api.psp.io/receipts/public/receipts \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --data '{
    "taxSystem": "Common",
    "action": 1,
    "cashierName": "Иванов И.И.",
    "cashierInn": "1234567890",
    "customerPhone": "79001234567",
    "customerEmail": "user@example.com",
    "clientId": "1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items": [
      {
        "calculationMethod": "FULL_PAY",
        "paymentSubject": "SERVICE",
        "name": "Оплата услуги",
        "price": 1000.00,
        "quantity": 1,
        "vat": "Vat20"
      }
    ],
    "correction": {
      "type": 1,
      "documentDate": "2026-06-22",
      "documentNumber": "1234567890"
    }
  }'

# Получение статуса чека

Возвращает текущий статус фискализации чека по идентификатору операции в Mandarin.

# Аутентификация

Скоуп: receipts:public_receipts.read
Токен OAuth 2.0 — см. аутентификацию запросов

Точка входа: GET https://api.psp.io/receipts/public/receipts/{mandarinId}/status

# Параметры

Параметр	Обязательность	Описание
`mandarinId`	Да (в URL)	Идентификатор операции в Mandarin (`TransactionId` или `OperationId` из callback-уведомления)

# Возможные значения status

Значение	Описание
`SUCCESS`	Чек успешно сформирован
`FAIL`	Ошибка формирования
`NEW`	Чек в обработке

Запрос

curl --request GET \
  --url https://api.psp.io/receipts/public/receipts/43913ddc000c4d3990fddbd3980c1111/status \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}'

Ответ в случае успеха (200 OK)

{
  "data": {
    "status": "SUCCESS"
  },
  "error": null
}

# Получение списка чеков

Возвращает список чеков с детализацией по позициям. Поддерживаются фильтрация и постраничная навигация.

# Аутентификация

Скоуп: receipts:public_receipts.read
Токен OAuth 2.0 — см. аутентификацию запросов

Точка входа: GET https://api.psp.io/receipts/public/receipts

# Фильтрация

Фильтры передаются в query-параметре filter_by в формате ключ=значение, условия разделяются символом & (в URL кодируется как %26).

Пример: чеки со статусом New, созданные в указанном интервале:

filter_by=mandarin_status=New&created_start_date>2023-09-08T10:53:47.748839Z&created_end_date<2023-09-08T10:55:47.748839Z

# Параметры filter_by

Параметр	Обязательность	Описание
`mandarinId`	Нет	ID операции в Mandarin
`provider_id`	Нет	ID чека у провайдера кассы
`mandarin_status`	Нет	Статус: `New`, `Success`, `Fail`
`created_start_date`	Нет	Начало периода (ISO 8601, например `2023-09-08T10:53:47.748839Z`)
`created_end_date`	Нет	Конец периода (ISO 8601)
`action_type`	Нет	Тип чека: `Receipt` (приход), `Refund` (возврат прихода), `Purchase` (расход), `PurchaseRefund` (возврат расхода)
`limit_to`	Нет	Количество записей на странице. По умолчанию: `20`
`cursor`	Нет	Курсор для пагинации (`prev` / `next` из предыдущего ответа)

# Пагинация

В ответе объект cursor содержит поля next и prev — передайте значение в параметр cursor для получения следующей или предыдущей страницы.

Запрос

curl --request GET \
  --url 'https://api.psp.io/receipts/public/receipts?filter_by=mandarin_status=New%26created_start_date%3E2023-09-08T10:53:47.748839Z%26created_end_date%3C2023-09-08T10:55:47.748839Z' \
  --header 'accept: */*' \
  --header 'authorization: Bearer {{access_token}}'

Ответ в случае успеха (200 OK)

{
  "receipts": [
    {
      "mandarinId": "11913ddc000c4d3990fddbd3980c1111",
      "providerId": "486179",
      "providerType": "Bifit",
      "actionType": "Receipt",
      "status": "SUCCESS",
      "mandarinStatus": "Success",
      "amount": 200.00,
      "customerEmail": "user@example.com",
      "customerPhone": "+79001234567",
      "items": [
        {
          "name": "Комиссия за ИТО при оплате по транзакции 23071572 в пользу Клиента 1234",
          "price": 200.00,
          "quantity": 1.0,
          "vat": "VAT20"
        }
      ],
      "taxationSystem": "Common",
      "clientId": "033861",
      "merchantId": "7429",
      "id": 714010,
      "createdAt": "2023-10-18T18:59:55.641495Z"
    }
  ],
  "cursor": {
    "count": 1,
    "total": 1,
    "next": null,
    "prev": null
  }
}

← Прием платежей Токенизация →

# Mandarin.Kassir

# Начало работы

# БИФИТ Онлайн

# АТОЛ Онлайн

# Агентская касса Mandarin

# Справочники

# Справочник систем налогообложения

# Справочник ставок НДС

# Справочник способов расчета

# Справочник предметов расчета

# Типы чеков и их назначение

# Автоматическое формирование чека

# Поддерживаемые операции

# Аутентификация

# Параметры fiscalInformation

# Примеры запросов

# Пример: платеж (pay)

# Пример: разблокировка после preauth (reversal)

# Пример: возврат по проведенному платежу (refund)

# Пример: выплата (payout)

# Автоматическое формирование агентского чека

# Когда указывать shipper

# Параметры (дополнительно к fiscalInformation)

# Значения agentType

# Аутентификация

# Примеры запросов

# Пример: агентский платеж (pay)

# Самостоятельное формирование чека

# Аутентификация

# Формирование чека на оплату и возврат

# Агентский чек

# Неагентский чек (обычный)

# Параметры запроса

# Параметры элемента товарной позиции (items)

# Параметры для чека коррекции

# Примеры запросов

# Пример: агентский чек на приход

# Пример: агентский чек на возврат прихода

# Пример: агентский чек коррекции прихода

# Пример: неагентский чек на приход

# Пример: неагентский чек на возврат прихода

# Пример: неагентский чек коррекции прихода

# Получение статуса чека

# Аутентификация

# Параметры

# Возможные значения status

# Получение списка чеков

# Аутентификация

# Фильтрация

# Параметры filter_by

# Пагинация

# Пример: платеж (`pay`)

# Пример: разблокировка после preauth (`reversal`)

# Пример: возврат по проведенному платежу (`refund`)

# Пример: выплата (`payout`)

# Пример: агентский платеж (`pay`)

# Параметры элемента товарной позиции (`items`)