# Mandarin.Kassir (checks)

# Beginning of work

Mandarin supports the transfer of fiscal information to online cash registers:

BIFIT (opens new window);
EKAM (opens new window);
Atol (opens new window).

To connect, you must perform the following steps:

# Bifit Online

What you need to have before starting integration:

Account on Mandarin (instructions (opens new window));
Account in “BIFIT Kassa” (instructions (opens new window));
Cloud cash register for rent, registered with the Federal Tax Service and the Federal Tax Service (instructions (opens new window))

Steps for integration:

Get a cash register token from “BIFIT Cashier” (instructions (opens new window)).
Transfer the token and your ClientID (opens new window) (CID) to Support Service (opens new window) Mandarin or client manager.
Configure the fiscalInformation object for requests (instructions).

# ECAM

What you need to have before starting integration:

Account on Mandarin (instructions (opens new window));
Account on EKAM.Online (opens new window).

Steps for integration:

Get a cash register token in “EKAM.Online (opens new window)” ([instructions](https://www.ekam.ru/collection/ekvayringi-i-platyozhnye -moduli/product/nastroyka-integratsii-ekam-i-mandarinpay)).
Transfer the token and your ClientID (opens new window) (CID) to Support Service (opens new window) Mandarin or client manager.
Configure the fiscalInformation object for requests (instructions).

# Atol Online

What you need to have before starting integration:

Account on Mandarin (instructions (opens new window));
Account in ATOL Online (registration (opens new window));
Cloud cash register for rent, registered with the Federal Tax Service and OFD (instructions (opens new window))

Steps for integration:

Receive data from the cash register in the “Integrator Settings” file in the ATOL Online account (instructions (opens new window) pp. 75-76).
Submit the file and your ClientID (opens new window) (CID) to Support Service (opens new window) Mandarin or client manager.
Configure the fiscalInformation object for requests (instructions).

# Agent cash desk Mandarin

With Mandarin, you can instantly and at no cost connect an online cash register using an agent fiscalization scheme. In this case, the cash receipt will contain information about the agent (Mandarin LLC, INN 7708816952) and the service provider (your company). The cash receipt will also display all the necessary information: receipt details (number); check amount; date of purchase/sale; transaction type (receipt/expense/return) and other information. To do this, it is necessary to transmit the fiscalInformation block in the request according to instructions, while in the case of using the Mandarin agent cash desk, the shipper block is not specified, information about the final recipient is specified on the Mandarin side.

Important!

When using the Mandarin cash desk, only the Common taxation system (Common) is always specified in the taxationSystem parameter; if other parameters are specified, the check will not be generated.

# Automatic receipt generation

Checks can be created for the following types of transactions:

payment;
payment cancellation;
payment.

Parameter	Required
fiscalInformation	If necessary
fiscalInformation.taxationSystem	Yes
fiscalInformation.items[]	Yes
fiscalInformation.items[].description	Yes
fiscalInformation.items[].quantity	Yes
fiscalInformation.items[].totalPrice	Yes
fiscalInformation.items[].vat	Yes
fiscalInformation.items[].calculationMethod	No
fiscalInformation.items[].paymentSubject	No

The taxationSystem field is specified once and contains the taxation system common to the entire check. Possible values:

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).

The vat field is indicated in each line and contains the VAT rate. Possible values:

None - Without VAT;
Vat0 - VAT at the rate of 0%;
Vat5 - VAT at the rate of 5%;
Vat7 - VAT at the rate of 7%;
Vat10 - VAT at the rate of 10%;
Vat20 - VAT at the rate of 20%;
vat105 - VAT on estimated payment 5/105;
vat107 - VAT on estimated payment 7/107.

The calculationMethod field is optionally specified in each line and contains the calculation method (by default FULL_PAY). Possible values:

PREPAY_FULL - Full prepayment before the transfer of the subject of payment;
PREPAY_PARTIAL - Partial advance payment before 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 payment without payment at the time of its transfer with subsequent payment on credit;
CREDIT_PAYMENT - Payment for the subject of payment after its transfer with payment on credit (loan payment).

The paymentSubject field is optionally specified in each line and contains the payment subject (by default SERVICE). Possible values:

AGENCY - Agency fee;
COMPOUND_SUBJECT - Composite subject of calculation;
EXCISABLE_PRODUCT - Excise goods;
GAMBLING_RATE - Gambling rate;
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 - Another subject of calculation;
PAYMENT - Payment;
PLEDGE – Pledge;
PRODUCT - Product;
PROPERTY_LAW - Property law;
PROVISION_RID - RID representation;
RESORT_FEE - Resort fee;
SERVICE - Service;
TRADE_FEE - Trade fee.

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

Request payment

POST https://secure.mandarinpay.com/api/transactions

{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	},
	"fiscalInformation": {
		"taxationSystem": "Common",
		"items": [{
			"quantity": 10,
			"vat": "Vat20",
			"description": "Product",
			"totalPrice": "800.00",
			"calculationMethod": "AVANS",
			"paymentSubject": "PRODUCT"
		}, {
			"quantity": 1,
			"vat": "Vat20",
			"description": "Delivery",
			"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"
}

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

{
	"error": "Invalid request"  
}

# Automatic generation of agent's check

Checks can be created for the following types of transactions:

payment;
payment cancellation;
payment.

A fiscalInformation object is added to a payment, payment cancellation or disbursement request, which contains an array of strings in the receipt and the selected tax system. Each line includes the name, quantity, line amount and VAT rate. Inside the items object for each item, you can place a shipper object containing information about the final recipient of the funds. In the case of using the Mandarin agent cash register, the shipper object is not specified.

Parameter	Required
fiscalInformation	If necessary
fiscalInformation.taxationSystem	Yes
fiscalInformation.items[]	Yes
fiscalInformation.items[].description	Yes
fiscalInformation.items[].quantity	Yes
fiscalInformation.items[].totalPrice	Yes
fiscalInformation.items[].vat	Yes
fiscalInformation.items[].calculationMethod	No
fiscalInformation.items[].paymentSubject	No
fiscalInformation.items[].agentType	No
fiscalInformation.items[].shipper	If necessary
fiscalInformation.items[].shipper.name	Yes
fiscalInformation.items[].shipper.inn	Yes
fiscalInformation.items[].shipper.phones[]	Yes

The agentType field is optionally specified in each line and contains the counterparty type for agent checks (default AGENT). Possible values:

AGENT;
BANK_PAYMENT_AGENT BANK_PAYMENT_SUBAGENT PAYMENT_AGENT;
PAYMENT_SUBAGENT;
ATTORNEY;
COMMISSIONER.

The shipper object contains the following required fields:

name - the name of the final recipient;
inn - INN of the final recipient;
phones - an array of phone numbers transmitted as strings.

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

Request

POST https://secure.mandarinpay.com/api/transactions

{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [{
			"name": "first parameter to save and show",
			"value": "p1"
		},
		{
			"name": "second parameter to save and show",
			"value": "p2"
		}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	},
	"fiscalInformation": {
		"taxationSystem": "Common",
		"items": [{
				"quantity": 1,
				"vat": "none",
				"description": "Pay",
				"totalPrice": "600.00",
				"calculationMethod": "FULL_PAY",
				"paymentSubject": "SERVICE",
				"agentType": "AGENT",
				"shipper": {
					"name": "ООО Romashka",
					"inn": "1234567890",
					"phones": [
						"+79111111111"
					]
				}
			},
			{
				"quantity": 1,
				"vat": "none",
				"description": "Pay",
				"totalPrice": "400.00",
				"calculationMethod": "FULL_PAY",
				"paymentSubject": "SERVICE",
				"agentType": "AGENT",
				"shipper": {
					"name": "ООО Lutik",
					"inn": "0987654321",
					"phones": [
						"+79222222222"
					]
				}
			}
		]
	}
}

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

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

{
"error": "Invalid request"
}

# Independent receipt generation

With Mandarin, you can generate receipts even after the operation, without linking the fiscal Information block to the request for payment, cancellation of payment or payment.

Authentication of requests:\

Each request must be authenticated using a token (access_token) obtained in accordance with the OAuth 2.0 protocol for applications. For execution, a scope receipts:public_receipts.write is required, which must be requested during authentication.

Parameter	Required	Description
taxSystem	Yes	[Types of taxation systems](./api_fiscal.md#automatic-check generation)
cashierName	No	Cashier name
cashierInn	No	Cashier's Inn
customerPhone	No if customerEmail is specified	Customer number
customerEmail	No if customerPhone	Customer mail
clientId	Yes	Client ID
merchantId	Yes	Merchant Id
mandarinId	Yes	Mandarin Id. Id to identify the check on which the operation was performed, for example TransactionId or OperationId
items.calculationMethod	Yes	Calculation method
items.agentType	No	Agent type, use AGENT
items.shipper.name	Yes, if agentType	Agent name
items.shipper.inn	Yes, if agentType	Agent Inn
items.shipper.phones	Yes, if agentType	Array of agent numbers
items.paymentSubject	Yes	Purchase type, for example SERVICE
items.name	Yes	Product/service name
items.price	Yes	Cost of product/service, limit 2 characters after the decimal point, for example: 123.45
items.quantity	Yes	Number of products, it is acceptable to use fractional numbers, for example 0.5
items.vat	Yes	VAT type

Request

POST https://api.psp.io/receipts/public/receipts

{
     "taxSystem": "Common",
     "cashierName": "Mandarin",
     "cashierInn": "1234567890",
     "customerPhone": "+79001234567",
     "customerEmail": "user@example.com",
     "clientId": "1234",
     "merchantId": "1234",
     "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
     "items": [
         {
             "calculationMethod": "FULL_PAY",
             "paymentSubject": "SERVICE",
             "name": "Commission for ITO when paying for transaction 23071572 in favor of Client 1234",
             "price": 200.00,
             "quantity": 1,
             "vat": "Vat20"
         }
     ]
}

Response if the request was created successfully (200 OK)

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

Example of an agent's check

POST https://api.psp.io/receipts/public/receipts

{
    "taxSystem":"COMMON",
    "cashierName": "Ivanov I.I.", //If there is no cashier, then simply do not indicate cashierName and cashierInn
    "cashierInn":"1234567890",
    "customerPhone":"79999999999", //You can specify either phone or email, if both phone and email are sent, then sending a receipt to email is a priority
    "customerEmail":"test@test.ru",
    "clientId":"1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items":[
       {
          "calculationMethod":"FULL_PAY",
          "agentType": "AGENT", //Information about the agent, if the check is NOT an agent check, then we simply do not send the shipper and agentType
          "shipper":{
             "name":"BIFIT",
             "inn":"7724923302",
             "phones":[
                "+79001234567"
             ]
          },
          "paymentSubject":"SERVICE",
          "name":"Service",
          "price":100,
          "quantity":1,
          "vat": "None"
       }
    ]
}

Example of a non-agency check

POST https://api.psp.io/receipts/public/receipts

{
    "taxSystem":"Common",
    "cashierName": "Ivanov I.I.", //If there is no cashier, then simply do not indicate cashierName and cashierInn
    "cashierInn":"1234567890",
    "customerPhone":"79001234567", //You can specify either phone or email, if both phone and email are sent, then sending to email is a priority
    "customerEmail":"user@example.com",
    "clientId":"1234",
    "merchantId": "1234",
    "mandarinId": "43913ddc000c4d3990fddbd3980c1725",
    "items":[
       {
          "calculationMethod":"FULL_PAY",
          "paymentSubject":"SERVICE",
          "name":"Service",
          "price":100,
          "quantity":1,
          "vat": "None"
       }
    ]
}

# Getting the check status

Authentication of requests:\

Each request must be authenticated using a token (access_token) obtained in accordance with the OAuth 2.0 protocol for applications. For execution, a scope receipts:public_receipts.read is required, which must be requested during authentication.

The method makes it possible to obtain the status of a check using the transaction identifier.

Parameter	Required	Description
mandarinId	Yes	Mandarin Id. Id to identify the receipt for which the operation was performed, for example TransactionId or OperationId

Request

GET https://api.psp.io/receipts/public/receipts/43913ddc000c4d3990fddbd3980c1725/status

Response if the request was created successfully (200 OK)

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

# Getting a list of receipts

Authentication of requests:\

Each request must be authenticated using a token (access_token) obtained in accordance with the OAuth 2.0 protocol for applications. For execution, a scope receipts:public_receipts.read is required, which must be requested during [authentication] (business_api_principles.html#authentication-requests).

The method allows you to get a list of receipts with a detailed description using the specified filters. Filtering is done based on filter_by, where we pass filters to queryParameters. It looks like this, in the request we pass the object filter_by, filters are passed as the value.

Parameter	Required	Description
mandarinId	none	Mandarin Id. Id to identify the receipt for which the operation was performed, for example TransactionID or operationId.
provider_id		Provider Id. ID of the receipt from the provider.
mandarin_status		Standardized check status. `New`, `Success`, `Fail`.
created_start_date		From date. Date of receipt creation in the format 2023-09-08T10:53:47.748839Z.
created_end_date		To date. Date of receipt creation in the format 2023-09-08T10:53:47.748839Z.
action_type		Receipt type. `Receipt`, `Refund`, `Purchase`, `PurchaseRefund`
limit_to		Limit to. By default, 20.
cursor		Cursor. for pagination prev/next

Request

GET https://api.psp.io/receipts/public/receipts?filter_by=mandarin_status=New%26created_start_date>2023-09-08T10:53:47.748839Z%26created_end_date<2023-09-08T10:55:47.748839Z

Response in case of successful request creation (`200 OK')

{
"receipts": [
{
"mandarinId": "11913ddc000c4d3990fddbd3980c1111",
"providerId": "486179",
"providerType": "Bifit",
"actionType": "Receipt",
"updatedAt": "2023-10-18T19:00:08.466157Z",
"status": "SUCCESS",
"mandarinStatus": "Success",
"amount": 200.00,
"customerEmail": "user@example.com",
"customerPhone": "+79001234567",
"items": [
{
"calculationMethod": null,
"paymentSubject": null,
"name": "ITO commission when paying for a transaction 23071572 in favor of the Client 1234",
"price": 200.00,
"quantity": 1.0,
"vat": "VAT20",
"total": 0.0,
"AgentType": null,
"shipperId": null,
"shipper": null,
"reciptid": 714010,
"isMandarinAgent": false,
"id": 741755,
"createdAt": "2023-10-18T18:59:55.641373Z"
}
],
"taxationSystem": "Common",
"clientId": "033861",
"merchantId": "7429",
"isSandbox": true,
"isMandarinAgent": false,
"extra": "{\"Id\": 486179, \"Kkm\": {\"Id\": 50, \"Inn\": \"772351116121\", \" Model\": \"BFR-112FS\", \"Vendor\": \"BIFIT\", \"FdNumber\": \"9999078902002260\", \" FdStatus\": null, \"TaxSystems\": [\"COMMON\", \"SIMPLIFIED\", \"SIMPLIFIED_WITH_EXPENSE\", \"ENVD\", \"COMMON_AGRICULTURAL\", \"PATENT\"], \"BrokerVersion\": \"3.46\", \" FactoryNumber\": \"98065732341002\", \" LastDocumentDate\": 1614173792888, \"RegistrationNumber\": \"0000000017017401\"}, \" Type\": \"RECEIPT\", \"KkmId\": 50, \"status\": \"SUCCESS\", \"Changed\": 1697655597239, \"Created\": 1697655595614, \"Request\": {\"type\": \"SALE\", \"items\": [{\"vat\": \"VAT_20\", \"name\": \"ITO commission when paying for a transaction 23071572 in favor of the Client 1234\", \"price\": 200.0, \"total\": 200.0, \"quantity\": 1.0, \"paymentSubject\": \"SERVICE\", \"calculationMethod\": \"FULL_PAY\"}], \"print\": false, \"total\": 200.0, \"client\": {\"address\": \"user@example.com \"}, \"cashier\": {\"name\": \"Mandarin-test\"}, \"payments\": {\"CARD\": 200.0}, \"taxSystem\": \"COMMON\"}, \"Response\": {\"Raw\": \"--------------------------------\\ n Cash receipt \\n PARISH \\n IP PIVOVAROV ALEXANDER \\n105203Moscow, Pervomayskaya Ni\\pzhn. ul., 46., room. XIII, com. \\n 52 \\n 18:10:23 21:59 \\ n--------------------------------\\ Commission for ITO when paying by TR\\transactions 23071572 in favor of Klien\\pta 1234 \\n1 * 200.00 = 200.00\\PNDs 20% \\SERVICE FULL CALCULATION\\n--------------------------------\\PET = 200.00\\Cashless = 200.00\\pSUMMA VAT 20% = 33.33\\PEL.ADR.BUYER \\n user@example.com\\nЭЛ.АДР.ОТПРАВИТЕЛЯ \\n pivovarov2@bifit.com\\nКАССИР Mandarin-test\\PCHEK 2805\\PSMEN 415\\pSNO OSN\\pINN 772351116121\\pRN KKT 0000000017017401\\pFN 9999078902002260\\pFD 226936\\PfP 2479791443\\n\", \"ShiftNumber\": 415, \"reciptnumber\": 2805}, \"ExecutorId\": 1, \"FiscalSign\": \"2479791443\", \" FiscalTime\": 1697655540000, \"FiscalDrive\": \"9999078902002260\", \" ExecutorType\": \"CONNECTOR\", \"FiscalAmount\": 200.00, \"FiscalDocument\": 226936, \"IdempotencyKey\": \"cd5511ed-3a4c-4618-bf21-5c7908fbb19f\"}",
"extraData": {
"Id": 486179,
"Kkm": {
"Id": 50,
"Inn": "772351116121",
"Model": "BFR-112FS",
"Vendor": "BIFIT",
"FdNumber": "9999078902002260",
"FdStatus": null,
"Taxsystems": [
"COMMON",
"SIMPLIFIED",
"SIMPLIFIED_WITH_EXPENSE",
"ENVD",
"COMMON_AGRICULTURAL",
"PATENT"
],
"BrokerVersion": "3.46",
"FactoryNumber": "98065732341002",
"LastDocumentDate": 1614173792888,
"RegistrationNumber": "0000000017017401"
},
"Type": "RECEIPT",
"KkmId": 50,
"status": "SUCCESS",
"Changed": 1697655597239,
"Created": 1697655595614,
"Request": {
"type": "SALE",
"items": [
{
"vat": "VAT_20",
"name": "ITO commission when paying for a transaction 23071572 in favor of the Client 1234",
"price": 200.0,
"total": 200.0,
"quantity": 1.0,
"paymentSubject": "SERVICE",
"calculationMethod": "FULL_PAY"
}
],
"print": false,
"total": 200.0,
"client": {
"address": "user@example.com"
},
"cashier": {
"name": "Mandarin-test"
},
"payments": {
"CARD": 200.0
},
"taxSystem": "COMMON"
},
"Response": {

← Saving additional information Tokenization →