# Mandarin.Kassir

Mandarin.Kassir is a service for fiscalization of Mandarin operations. It generates fiscal receipts when accepting payments, returns and payments and transmits the data to the online cash register for registration with the Federal Tax Service.

# Getting started

Mandarin transmits fiscal data to cloud-based online cash registers. Providers supported:

Mandarin agent cash desk is also available - connection without your own cash register (see below).

Check generation schemes:

Scheme	When to use
Automatic generation	Block`fiscalInformation`transmitted in a request for payment, refund or disbursement
Self-generation	The receipt is created by a separate request after the operation

# BIFIT Online

What you need before integration

Mandarin account - registration (opens new window);
Account in "BIFIT Kassa" - [instructions](https://kassa.bifit.com/wiki/index.php?title=%D0%98%D0%9D%D0%A1%D0%A2%D0%A0%D0%A3%D0%9A%D0%A6%D0%98%D0%98:%D0%A0%D0%B5%D0%B3%D0 %B8%D1%81%D1%82%D1%80%D0%B0%D1%86%D0%B8%D1%8F_%D0%B2_%D0%9B%D0%B8%D1%8 7%D0%BD%D0%BE%D0%BC_%D0%9A%D0%B0%D0%B1%D0%B8%D0%BD%D0%B5%D1%82%D0%B5);
Cloud cash register for rent, registered with the Federal Tax Service and connected to the OFD - [instructions](https://kassa.bifit.com/wiki/index.php?title=%D0%92%D0%B7%D1%8F%D1%82%D1%8C_%D0%BE%D0%B1%D0%BB%D0%B0 %D1%87%D0%BD%D1%83%D1%8E_%D0%BA%D0%B0%D1%81%D1%81%D1%83_%D0%B2_%D0%B0%D1%80%D0%B5%D0%BD%D0%B4%D1%83&redirect=no).

Connection steps

Get a cash register token from BIFIT Cashier - [instructions](https://kassa.bifit.com/wiki/index.php?title=%D0%9A%D0%B0%D0%BA_%D1%81%D0%BE%D0%B7%D0%B4%D0%B 0%D1%82%D1%8C_%D1%82%D0%BE%D0%BA%D0%B5%D0%BD_%D0%BA%D0%BE%D0%BD%D0%BD%D0%B5%D0%BA%D1%82%D0%BE%D1%80%D0%B0).
Transfer the token and Client ID (opens new window) to support (opens new window) Mandarin or your manager.
Add an objectfiscalInformationto requests - see [Automatic receipt generation](#automatic-receipt generation).

# ATOL Online

What you need before integration

Mandarin account - registration (opens new window);
Account in "ATOL Online" - [registration](https://id.atol.ru/auth/realms/ATOL-ID-External/protocol/openid-connect/registrations?client _id=ao_client&redirect_uri=https%3A%2F%2Fonline.atol.ru%2Flk%2F&state=1aafb5bb-d15e-4667-8921-40ba4e3a46f5 &response_mode=fragment&response_type=code&scope=openid&nonce=65ce5399-7b3c-4ea6-8a11-7cba987456e7&partner _uuid=c2fea33f-c574-4973-8207-5536b72ad4bb&utm_source=mandarin&utm_medium=referral&utm_campaign=documents);
Cloud cash register for rent, registered with the Federal Tax Service and connected to the OFD - instructions (opens new window).

Connection steps

Receive data from the cash register in the “Integrator Settings” file in the ATOL Online account - instructions (opens new window) (pages 75–76).
Submit the file and Client ID (opens new window) to support (opens new window) Mandarin or your manager.
Add an objectfiscalInformationto requests - see [Automatic receipt generation](#automatic-receipt generation).

# Agent's cash desk Mandarin

Connecting an online cash register under an agent scheme without renting your own cash register. The check indicates:

agent - Mandarin LLC, TIN 7708816952;
supplier is your company.

The receipt displays the number, amount, date, type of transaction (receipt / expense / return) and other fiscal details.

To automatically generate a check, sendfiscalInformationaccording to instructions for agent's check. When using the Mandarin checkout blockshipperin the payment request is not transmitted - supplier data is configured on the Mandarin side.

When independently generating a receipt via the APIapi.psp.ioblockshipperrequired: it contains information about your company as a provider of services/products. For more details, see the section [Self-generation of a check](#self-generation of a check).

Important!

When using the Mandarin checkout in the parametertaxationSystemindicate onlyCommon(OSN). Other values will result in a receipt generation error.

# Directories

# Directory of taxation systems

Meaning	Description
`Common`	General (OSN)
`Simplified`	Simplified (STS) “Income”
`SimplifiedMinusOutlay`	Simplified (STS) “Income minus expenses”
`UnifiedImputedIncome`	Unified tax on imputed income (UTII)
`UnifiedAgricultural`	Unified Agricultural Tax (USAT)
`Patent`	Patent (PSN)

# Directory of VAT rates

Meaning	Description
`None`	Without VAT
`Vat0`	VAT at 0%
`vat5`	VAT at 5%
`vat7`	VAT at 7%
`Vat10`	VAT at 10%
`Vat20`	VAT at 20%
`Vat22`	VAT at 22%
`vat105`	VAT at the estimated rate of 5/105
`vat107`	VAT at the estimated rate of 7/107

# Directory of calculation methods

Meaning	Description
`PREPAY_FULL`	Full advance payment before transfer of the subject of payment
`PREPAY_PARTIAL`	Partial advance payment until the transfer of the subject of payment
`AVANS`	Advance
`FULL_PAY`	Full payment, including taking into account the advance payment (prepayment) at the time of transfer of the subject of payment
`PARTIAL_SETTLEMENT_AND_CREDIT`	Partial payment of the subject of payment at the time of its transfer with subsequent payment on credit
`TRANSFER_ON_CREDIT`	Transfer of the subject of settlement without payment at the time of its transfer with subsequent payment on credit
`CREDIT_PAYMENT`	Payment for the subject of settlement after its transfer with payment on credit (loan payment)

# Directory of calculation items

Meaning	Description
`AGENCY`	Agency fees
`COMPOUND_SUBJECT`	Composite subject of calculation
`EXCISABLE_PRODUCT`	Excise goods
`GAMBLING_RATE`	Gambling bet
`GAMBLING_WIN`	Winning a Gambling Game
`INSURANCE_CONTRIBUTIONS`	Insurance premiums
`JOB`	Work
`LOTTERY_TICKET`	Lottery ticket
`LOTTERY_WIN`	Winning the lottery
`NON_OPERATING_INCOME`	Non-operating income
`OTHER_SUBJECT`	Other subject of calculation
`PAYMENT`	Payment
`PLEDGE`	Collateral
`PRODUCT`	Product
`PROPERTY_LAW`	Property law
`PROVISION_RID`	RID Submission
`RESORT_FEE`	Resort fee
`SERVICE`	Service
`TRADE_FEE`	Trade fee

# Types of checks and their purpose

The system supports the following types of fiscal receipts:

Check type	When is formed	Description
Parish	Upon receipt of funds from the buyer	Standard check for payment for goods/services. Generated upon successful payment.
Return of receipt	When returning money to the buyer	A check confirming the return of previously paid funds. Generated when a payment is canceled or returned.
Consumption	When issuing funds (for example, payment to a supplier or withdrawal of funds)	A receipt confirming the expense transaction. Generated during payments.
Expense Return	When returning previously issued funds	A receipt confirming the return of funds from the counterparty. Generated when a payment is cancelled.
Receipt correction check	To correct errors in previously generated receipts	It is generated if an error was made in the original check (the check was not issued initially, the amount, VAT rate, name, etc. are incorrect) and it is necessary to correctly reflect the operation in the fiscal system.
Consumption correction check	To correct errors in previously generated expense receipts	Similar to income adjustment, but for expense transactions.
Receipt return correction check	To correct errors in receipt return checks	Corrects incorrectly issued refunds or if the receipt was not issued for a refund.
Consumption refund correction check	To correct errors in expense return receipts	Corrects an incorrectly completed return of an expense transaction or if the check was not issued for return.

# Automatic check generation

A receipt is generated automatically upon successful completion of the operation, if the request forPOST https://secure.mandarinpay.com/api/transactionsobject passedfiscalInformation.

# Supported Operations

`payment.action`	Operation	Type of fiscal receipt
`pay`	Debiting funds from a card (payment)	Parish
`reversal`	Unblocking funds after two-stage authorization (`preauth`). No money was debited to the card	Return of receipt
`refund`	Refund of funds to the buyer for an already successfully completed write-off operation (`pay`), including partial	Return of receipt
`payout`	Payment to card	Consumption

ObjectfiscalInformationcontains a tax system (taxationSystem) and an array of check positions (items). Each item describes the name, quantity, line amount and VAT rate.

# Authentication

Requests are authenticated by a header x-auth. Formation of the value is in the Request Authentication.

Two APIs - different fields for the operation type

The documentation uses two different APIs. Do not substitute values from one API to another.

1. Automatic check generation (this section)
Endpoint:POST https://secure.mandarinpay.com/api/transactionsThe operation type is specified inpayment.action: pay,reversal,refund,payout.
A check is generated automatically along with the payment if a block is transferredfiscalInformation.

2. Independent receipt generation
Endpoint:POST https://api.psp.io/receipts/public/receiptsThe check type is specified by the fieldaction(number) orActionType(string) - one of them is enough.

Check type	`action`	`ActionType`
Parish	`1`	`Receipt`
Receipt Return	`2`	`Refund`
Consumption	`3`	`Purchase`
Refund of expense	`4`	`PurchaseRefund`

Field matching

When self-generating, the same values are used, but different field names:taxSysteminstead oftaxationSystem,nameinstead ofdescription,priceinstead oftotalPrice.

# FiscalInformation parameters

Parameter	Obligation	Description
`fiscalInformation`	If necessary	Fiscal data block. Passed if a check is needed
`fiscalInformation.taxationSystem`	Yes	Taxation system for the entire check. See directory
`fiscalInformation.items[]`	Yes	Array of product items
`fiscalInformation.items[].description`	Yes	Name of product, work or service
`fiscalInformation.items[].quantity`	Yes	Quantity. Fractional values allowed
`fiscalInformation.items[].totalPrice`	Yes	Sum by line (string with two decimal places, e.g.`"800.00"`)
`fiscalInformation.items[].vat`	Yes	VAT rate. See [VAT directory](#VAT-rates directory)
`fiscalInformation.items[].calculationMethod`	No	Method of calculation. Default`FULL_PAY`. See directory
`fiscalInformation.items[].paymentSubject`	No	Subject of calculation. Default`SERVICE`. See directory

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

# Query examples

# Example: payment (`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"
      }
    ]
  }
}'

Response in case of successful transaction creation (200 OK)

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

# Example: unlock after 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"
      }
    ]
  }
}'

# Example: refund of a completed payment (`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"
      }
    ]
  }
}'

# Example:`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"
      }
    ]
  }
}'

Answer if the transaction is not created (400 Bad request)

{
  "error": "Invalid request"
}

# Automatic generation of agent's check

Use this section if you act as a intermediary: you accept payment for goods or services of another person (marketplace, aggregator, payment agent).

The check is generated in the same way as in the regular automatic script, with the same valuespayment.action(pay,reversal,refund,payout). In every positionitemsadditionally transmittedagentType, and the blockshipper- depending on the scenario (see table below).

# When to specify shipper

Script	`agentType`	`shipper`
Own cash desk BIFIT / ATOL, automatic check with payment	`AGENT`	Yes - supplier details
Mandarin cash register, automatic check with payment	`AGENT`	No - Provider is configured in Mandarin
Mandarin cash register, self-generation	`AGENT`	Yes - details of your company

Important!

When using Mandarin agent cash desk:

Automatic check (blockfiscalInformationin the payment/disbursement request): blockshippernot transmitted.
Independent receipt generation (APIapi.psp.io/receipts/public/receipts): blockshipperrequired - provide information about your company as a provider of services/products.

# Parameters (in addition to fiscalInformation)

Parameter	Obligation	Description
`items[].agentType`	Conditional	Agent type. For most scenarios -`AGENT`
`items[].shipper`	Conditional	Supplier details. Required at your checkout; does not transfer with automatic check with Mandarin cash register
`items[].shipper.name`	Yes, if available`shipper`	Name of supplier organization
`items[].shipper.inn`	Yes, if available`shipper`	Supplier INN
`items[].shipper.phones[]`	Yes, if available`shipper`	Supplier phone numbers (array of strings)

# agentType values

Meaning	Description
`AGENT`	Paying agent
`BANK_PAYMENT_AGENT`	Bank payment agent
`BANK_PAYMENT_SUBAGENT`	Bank payment subagent
`PAYMENT_AGENT`	Paying agent (other type)
`PAYMENT_SUBAGENT`	Payment subagent
`ATTORNEY`	Attorney
`COMMISSIONER`	Commissioner

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

# Authentication

Requests are authenticated by a header x-auth. Formation of the value is in the Request Authentication.

# Query examples

# Example: agent payment (`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"]
        }
      }
    ]
  }
}'

Response in case of successful transaction creation (200 OK)

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

# Independent receipt generation

This functionality allows you to generate a fiscal receipt for an already completed operation - if the automatic generation did not work, was not configured, or business logic requires a separate receipt.

Important: independent formation does not replace automatic fiscalization at the time of payment. Use it only when reasonably necessary and in accordance with the legal requirements for the use of CCP.

Main scenarios:

Ordinary check for a transaction not automatically fiscalized
If the check was not created at the time of payment or disbursement due to technical reasons, it can be generated manually on the day of the transaction - with a regular receipt, expense or return check (depending on the type of transaction).
Correction check
It is applied only if it is no longer possible to correct the situation with a regular check - in particular, if the day of the transaction has passed or erroneous details were recorded in the previously punched check.

Correction check is not a “backup” option

A correction check cannot be generated arbitrarily or instead of a timely punched check.

If the operation was carried out today and the check was not cleared, generate a regular check, not a correction.
A correction check is issued if there is a legal basis: correction of an error in the information previously submitted to the OFD or reflection of a calculation for which the check was not issued within the prescribed period.
The request must indicate a blockcorrectionwith base type (Self- self-correction,Prescription- as prescribed by the tax authority), the date of the adjusted calculation and, if necessary, the number of the basis document.

Illegal use of correction checks may result in violation of the requirements for the use of cash register equipment. If in doubt, contact your accountant or support (opens new window) Mandarin.

A correction check is required if it is necessary to correct the following in a previously generated check or in its absence:

settlement amount;
VAT rate;
name of the product, work or service;
type of receipt (for example, instead of a receipt, an expense was entered);
fact of settlement according to which the check was not issued on the day of the transaction.

# Authentication

For POST requests (creating receipts): scopereceipts:public_receipts.write- For GET requests (viewing status and list of receipts): scopereceipts:public_receipts.read

Both scopes must be requested during OAuth 2.0 authentication.

General request structure:

All requests to create a check are sent using the POST method to the endpoint:https://api.psp.io/receipts/public/receipts- The body of the request contains mandatory and optional parameters describing the receipt itself, the goods/services in it, as well as information about the client and cashier.

# Generating a receipt for payment and return

A check can be agent or non-agency (ordinary).

# Agent's check

When needed: when you accept money not for your goods/services, but for others (you are an intermediary).

Also when using a Mandarin checkout, where you are the provider of services/products and Mandarin is the agent (intermediary).

Example: marketplace, service aggregator, payment agent.

To API: you passagentTypeand blockshipper(name, TIN, telephone number of the final recipient).

Important!

When using Mandarin agent cash desk:

Automatic check (blockfiscalInformationin the payment/disbursement request): blockshippernot transmitted.
Independent receipt generation (this section): blockshipperrequired - provide information about your company as a provider of services/products.

# Non-agency check (regular)

When needed: when you sell your products or services.

Example: online store, own delivery, consulting, etc.

In the API: you pass the request body withoutagentTypeAndshipper.

# Request parameters

Parameter	Obligation	Description
`taxSystem`	Yes	Tax system. Possible values:`Common`(OSN),`Simplified`(USN Income),`SimplifiedMinusOutlay`(USN Income minus expenses),`UnifiedImputedIncome`(UTII),`UnifiedAgricultural`(ESKhN),`Patent`(PSN)
`action`	Conditional	Receipt type (indicate one of the following values:`ActionType`or`action`): •`1`— Arrival (payment) •`2`— Receipt return •`3`— Consumption •`4`— Return of expense Required for returns, expenses and corrections. It is not required to attend.
`ActionType`	Conditional	Receipt type (indicate one of the following values:`ActionType`or`action`): •`Receipt`— Arrival (payment) •`Refund`— Receipt return •`Purchase`— Consumption •`PurchaseRefund`— Return of expense Required for returns, expenses and corrections. It is not required to attend.
`isMandarinAgent`	No	Use the Mandarin terminal for the agent fiscalization scheme.
`cashierName`	No	Cashier's name.
`cashierInn`	No	Cashier's TIN.
`customerPhone`	Conditional	Client's phone number. Required if not specified`customerEmail`.
`customerEmail`	Conditional	Client email address. Required if not specified`customerPhone`.
`clientId`	Yes	Client ID.
`merchantId`	Yes	Merchant ID.
`mandarinId`	Yes	Mandarin transaction ID (for example,`TransactionId`or`OperationId`) to which the check is attached.

# Item item parameters (`items`)

Parameter	Obligation	Description
`items.calculationMethod`	Yes	Calculation method. Possible values:`FULL_PAY`,`PREPAY_FULL`,`PREPAY_PARTIAL`,`AVANS`,`PARTIAL_SETTLEMENT_AND_CREDIT`,`TRANSFER_ON_CREDIT`,`CREDIT_PAYMENT`.
`items.agentType`	Conditional	Counterparty type for agency checks. Use`AGENT`. Mandatory if the check is from an agent.
`items.shipper.name`	Conditional	Name of the supplier company (ultimate recipient of funds). Required if specified`agentType`.
`items.shipper.inn`	Conditional	TIN of the supplier company. Required if specified`agentType`.
`items.shipper.phones`	Conditional	An array of provider phone numbers in string format. Required if specified`agentType`.
`items.paymentSubject`	Yes	Subject of calculation. Possible values:`SERVICE`(service),`PRODUCT`(product),`JOB`(Job),`PAYMENT`(payment),`AGENCY`(agency remuneration), etc. The full list is in the directory of settlement items.
`items.name`	Yes	Name of the product, work or service.
`items.price`	Yes	Unit price. Limit: 2 decimal places (for example,`123.45`).
`items.quantity`	Yes	Quantity. Fractional numbers are allowed (for example,`0.5`).
`items.vat`	Yes	VAT rate. Possible values:`None`(excluding VAT),`Vat0`(0%),`vat5`(5%),`vat7`(7%),`Vat10`(10%),`Vat20`(20%),`Vat22`(22%),`vat105`(5/105),`vat107`(7/107).

# Parameters for correction check

To generate a correction check, you need to add a field to the requestaction(orActionType) and blockcorrection.

Parameter	Obligation	Description
`action`	Conditional	Type of operation being adjusted (one of the values is indicated:`ActionType`or`action`): •`1`— Arrival (payment) •`2`— Receipt return •`3`— Consumption •`4`— Return of expenses
`ActionType`	Conditional	Type of operation being adjusted (one of the values is indicated:`ActionType`or`action`): •`Receipt`— Arrival (payment) •`Refund`— Receipt return •`Purchase`— Consumption •`PurchaseRefund`— Return of expenses
`correction`	Yes	Data block for correction check. Contains information about the basis for the correction.
`correction.type`	Yes	Correction type: •`1`—`Self`(independent operation) •`2`—`Prescription`(prescription surgery)
`correction.documentDate`	Yes	The date the adjusted calculation was made. Format:`ГГГГ-ММ-ДД`(For example,`2026-06-22`).
`correction.documentNumber`	No	Number of the document that serves as the basis for the correction. The fiscal attribute (FP) of the erroneous check is indicated, if it was generated. If the check has not been punched, the field is sent empty.

# Query examples

# Example: agent receipt receipt

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

Response if the request was successfully created (200 OK)

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

# Example: agent check for return of receipt

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

# Example: agent receipt correction check

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

# Example: non-agency check for receipt

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

# Example: non-agency check for return of receipt

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

# Example: non-agency receipt correction check

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

# Getting the check status

Returns the current fiscalization status of a check by transaction ID in Mandarin.

# Authentication

Scope:receipts:public_receipts.read- OAuth 2.0 token - see request authentication

Entry point:GET https://api.psp.io/receipts/public/receipts/{mandarinId}/status

# Options

Parameter	Obligation	Description
`mandarinId`	Yes (in URL)	Operation ID in Mandarin (`TransactionId`or`OperationId`from callback-notifications)

# Possible values for status

Meaning	Description
`SUCCESS`	The check was successfully generated
`FAIL`	Formation error
`NEW`	Check being processed

Request

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

Response if successful (200 OK)

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

# Getting a list of receipts

Returns a list of receipts with item detail. Filtering and page navigation are supported.

# Authentication

Scope:receipts:public_receipts.read- OAuth 2.0 token - see request authentication

Entry point:GET https://api.psp.io/receipts/public/receipts

# Filtration

Filters are passed in the query parameterfilter_byin formatключ=значение, conditions are separated by the symbol&(in URL encoded as%26).

Example: checks with statusNew, created in the specified interval:

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 parameters

Parameter	Obligation	Description
`mandarinId`	No	Transaction ID in Mandarin
`provider_id`	No	Receipt ID from the cash register provider
`mandarin_status`	No	Status:`New`,`Success`,`Fail`
`created_start_date`	No	Start of period (ISO 8601, for example`2023-09-08T10:53:47.748839Z`)
`created_end_date`	No	End of period (ISO 8601)
`action_type`	No	Check type:`Receipt`(coming),`Refund`(receipt return),`Purchase`(consumption),`PurchaseRefund`(expense return)
`limit_to`	No	Number of entries per page. Default:`20`
`cursor`	No	Cursor for pagination (`prev`/`next`from the previous answer)

# Pagination

The response contains an objectcursorcontains fieldsnextAndprev- pass the value to the parametercursorto get the next or previous page.

Request

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

Response if successful (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
  }
}

← Payments Tokenization →

# Mandarin.Kassir

# Getting started

# BIFIT Online

# ATOL Online

# Agent's cash desk Mandarin

# Directories

# Directory of taxation systems

# Directory of VAT rates

# Directory of calculation methods

# Directory of calculation items

# Types of checks and their purpose

# Automatic check generation

# Supported Operations

# Authentication

# FiscalInformation parameters

# Query examples

# Example: payment (pay)

# Example: unlock after preauth (reversal)

# Example: refund of a completed payment (refund)

# Example:payout

# Automatic generation of agent's check

# When to specify shipper

# Parameters (in addition to fiscalInformation)

# agentType values

# Authentication

# Query examples

# Example: agent payment (pay)

# Independent receipt generation

# Authentication

# Generating a receipt for payment and return

# Agent's check

# Non-agency check (regular)

# Request parameters

# Item item parameters (items)

# Parameters for correction check

# Query examples

# Example: agent receipt receipt

# Example: agent check for return of receipt

# Example: agent receipt correction check

# Example: non-agency check for receipt

# Example: non-agency check for return of receipt

# Example: non-agency receipt correction check

# Getting the check status

# Authentication

# Options

# Possible values ​​for status

# Getting a list of receipts

# Authentication

# Filtration

# filter_by parameters

# Pagination

# Example: payment (`pay`)

# Example: unlock after preauth (`reversal`)

# Example: refund of a completed payment (`refund`)

# Example:`payout`

# Example: agent payment (`pay`)

# Item item parameters (`items`)

# Possible values for status