Инструменты страницы
Request for receipt closure (closeOfdReceipt.do)
The request used for closing the receipt is closeOfdReceipt.do
.
From July 1, 2019, owners of online cash registers must generate receipts for offset and refund of prepayment. The payment gateway allows you to register a second check (closing check) without creating a new order using a request closeOfdReceipt
.
The request must contain either the orderNumber
parameter or mdOrder
parameter.
The content of the closing receipt depends on whether the order cart (orderBundle
) has been passed
The cart was transferred | The shopping cart will be transferred to the OFD in the form in which it was transferred to the gateway in the request to close the receipt. |
---|---|
The cart was not transferred | For a completed order
For a refund Closing a check can only be done if a partial, not full refund has been made for the order.
|
- A closing receipt can be sent multiple times for one order. There is no limit on the amount, that is, the amount indicated in the closing receipt may be less or greater than the order amount.
- An exception is made for orders for which a refund has been made. For orders for which a refund was made, the closing of the check can only be done if the total of all refunds is less than the confirmed order amount (i.e., there was no full refund).
In this document, the following data type conventions are used when describing request and response parameters:
- A<n> – a sequence of Latin letters of length <n>;
- A..<n> – a sequence of Latin letters with a length not exceeding <n>;
- N<n> – a sequence of digits of length <n>;
- N..<n> – a sequence of digits with a length not exceeding <n>;
- AN<n> – a sequence of Latin letters and numbers of fixed length <n>;
- AN.. <n> – a sequence of Latin letters and numbers with a length not exceeding <n>;
- ANS<n> – a sequence of Latin letters, numbers and characters of fixed length <n>
- ANS.. <n> – a sequence of Latin letters, numbers and characters with a length not exceeding <n>;
- UTC – date and time, in this case: the date must be passed without specifying the time zone, Moscow time, for the SOAP protocol, the standard encoding xs: dateTime is used.
Request parameters
The request parameters are given in table below.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
AN..30 | Yes |
Login of the service account of the merchant. If login and password are used for authentication during token registration, then the |
All versions. |
|
AN..30 | Yes |
Merchant's service account password. If login and password are used for authentication during token registration, then the |
All versions. |
|
ANS..36 | Either mdOrder or OrderNumber must be passed |
Order number in the payment gateway. Unique within the payment gateway. |
All versions. |
|
ANS..32 | Either mdOrder or OrderNumber must be passed |
Number (identifier) of the order in the store system. It is unique for every store within the Payment Gateway. If the order number is generated on the Payment Gateway side, this parameter is not mandatory. |
All versions. |
|
N..12 | No |
Payment amount in minimum currency units. |
All versions. |
|
String | No | Currently not used |
All versions. |
|
Data block for transferring additional parameters of the OFD | Yes |
Some parameters of The transfer of this block is possible only when using the following OFDs:
| |
|
Not applicable | Yes |
Block containg the cart of items of the order. The description of the attributes is given below. |
All versions. |
orderBundle
orderBundle
contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..21 | No |
Order creation date in the format YYYY-MM-DDTHH:MM:SS. |
All versions. |
|
Not applicable | No |
Block containing attributes with data about the customer. The description of the attributes is given below. |
All versions. |
|
Not applicable | Yes |
Block with the attributes of the items in the cart. The description of the attributes is given below. |
All versions. |
|
array ANS..19 | No | Given below are the parameters of agent block.. (Go to description.) |
All versions. |
|
array ANS..19 | No |
An array of supplier phone numbers in +N format. |
All versions. |
agent
Name | Type | Mandatory | Description |
---|---|---|---|
|
N..2 | Yes (if the block is present) |
Agent type, the following values are available:
|
|
|
No |
|
|
|
No |
|
|
array ANS..19 | No |
Array of phone numbers of the operator for receiving payments in the + N format. |
|
array ANS..19 | No |
An array of Money Transfer operator phone numbers in +N format. |
|
ANS..64 | No |
Money Transfer operator name. |
|
ANS..256 | No |
Money Transfer operator address. |
|
N10..12 | No |
Money Transfer operator TIN. |
customerDetails
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
customerDetails
contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..40 | See note below. |
Customer's email address, to which the receipt will be sent. Most OFDs support delivery of receipt only to one email address. Some OFDs allow receipt delivery to multiple emails. In this case, the emails should be separated by commas without spaces. Contact your OFD for availability of receipt delivery to multiple emails. It is mandatory to pass one of the two parameters: email or phone. |
All versions. |
|
NS..12 | See note below. |
Customer's phone number. It can be of the following format:
If the number is passed in a separate parameter and in additional parameters, the number specified in this
When using ATOL fiscalization, the |
All versions. |
|
ANS..40 | No |
Customer's preferred way of communication. |
All versions. |
|
|
No |
All versions. |
|
|
ANS..100 | No |
Payer's first name, last name, and patronymic. |
1.05 and later versions. |
|
ANS..100 | No |
The series and number of the payer's passport in the following format: |
1.05 and later versions. |
|
N..12 | No |
Taxpayer identification number. From 10 to 12 digits can be passed. |
1.05 and later versions. |
It is mandatory to pass one of the two parameters: email
or phone
.
deliveryInfo
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
deliveryInfo
contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..20 | No |
Delivery method. |
All versions. |
|
A..2 | Yes |
The two-letter country code for the delivery country. |
All versions. |
|
ANS..40 | Yes |
Delivery city. |
All versions. |
|
ANS..255 | Yes |
Delivery address. |
All versions. |
cartItems
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
cartItems
contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
Not applicable | Yes |
Array of blocks describing line items in the cart. Information about every line item in the cart is passed in a separate block that is included in items. Do not use «‘)«character combination inside this section, or it will cause an error on the gateway side. |
All versions. |
items
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
items« contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..12 | Yes |
Unique identifier of a line item within the order cart. |
All versions. |
Name
TypeANS..100 DescriptionRESTName or the description of an item in any format.
Use REST Online LendingFor Online Lending functionality, it's necessary to specify a description of the line item in accordance with the Yandex.Market catalog, subject to the following requirements:
WSName or the description of an item in any format.
Use WS Online LendingFor online crediting functionality it's necessary to specify a description of the good item in accordance with the Yandex.Market. |
ANS..100 | Yes |
Name or the description of an item in any format.
Use |
All versions. |
|
Not applicable | No |
Additional block containing the parameters describing a line item. The description of the attributes is given below. The field size limit is 1024 bytes. |
All versions. |
|
N..18 | Yes |
Element describing the total of items of one |
All versions. |
|
N..12 | No |
The sum of the cost of all line items of one When calculating itemAmount = itemPrice*quantity parameter, the result is rounded up to the second digit after the decimal point. For example, if the calculation result is 100.255, then final value will be 100.26. |
All versions. |
|
N3 | No |
Currency code of a line item according to ISO 4217. If the parameter is not specified, it is considered to be equal to the order currency. |
All versions. |
|
ANS..100 | Yes |
Number (identifier) of a line item in the store system. |
All versions. |
|
Not applicable | Only for stores with enabled fiscalization settings |
An additional tag with attributes describing the tax. Nested tags are described below. |
All versions. |
|
N..18 | Only for stores with enabled fiscalization settings |
The cost of one line item in minimum currency units. Mandatory for merchants using fiscalization.
|
All versions. |
|
See description. | Only for stores with enabled fiscalization settings |
Block containing the attributes of the item. See description below. |
1.05 and later versions. |
==== itemAttributes ====
itemAttributes contains the
attributes array in which the attributes of a line item must be specified (see example and table below).
<sxh JavaScript>
«itemAttributes»:{«attributes»:[{«name»:«paymentMethod»,»value«:«1»},{«name»:«paymentObject»,»value«:«1»}]}
</sxh>
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
N..2 |
Yes |
Payment type. Possible values:
Values are passed in the following priority (indicated in descending order of priority):
For paymentMethod, the default value is 1 (full prepayment before the transfer of the payment item). |
1.05 and later versions. |
|
N..2 |
Yes |
Type of item being paid for. Possible values:
Values are passed in the following priority (indicated in descending order of priority):
The default value for paymentObject is 1 (item). |
1.05 and later versions. |
|
ANS | yes (if markQuantity is passed) |
Trade item code in text representation. Maximum length – 32 bytes. |
1.05 and later versions. |
|
| No |
Fractional quantity of the labeled item. |
1.2 and later versions. |
|
N..2 | Mandatory if agent_info object is passed. |
Agent type. The following values are available:
|
1.05 and later versions. |
|
|
No |
|
1.05 and later versions. |
|
|
No |
|
1.05 and later versions. |
|
Array ANS..19 | No |
Phone numbers array of the payments operator in +N format. |
1.05 and later versions. |
|
array ANS..19 | No |
An array of Money Transfer operator phone numbers in +N format. |
1.05 and later versions. |
|
ANS..64 | No |
Money Transfer operator name. |
1.05 and later versions. |
|
ANS..256 | No |
Money Transfer operator address. |
1.05 and later versions. |
|
N10..12 | No |
Money Transfer operator TIN. |
1.05 and later versions. |
|
Array ANS..19 | No |
An array of supplier phone numbers in +N format. |
1.05 and later versions. |
|
ANS..256 | No |
Supplier name. |
1.05 and later versions. |
|
N10..12 | No |
Supplier TIN. |
1.05 and later versions. |
==== quantity ====
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
quantity contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
N..18 | Yes |
Quantity of line items in given |
All versions. |
|
ANS..20 | Yes |
The unit of measurement for the quantity of line item instances. |
All versions. |
If the FFD is version 1.2 or later, then the following parameters are passed here:
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
N1 | Yes |
Quantity of line items in given |
1.2 and later versions. |
|
N..3 | Yes |
Unit of measurement for the quantity of the payment subject. In case of FFD version 1.2+, if the 'nomenclature' and 'markQuantity' parameters are passed, the value is always 0. In other cases, it can have some value. |
1.2 and later versions. |
Possible values of measure
Value | Description |
---|---|
0 | Used for payment subjects that can be sold individually or in units (as well as in the event that the payment subject is a product subject to mandatory labeling with an identification tool (which can be known from mark_code being passed)) |
10 | Gram |
11 | Kilogram |
12 | Ton |
20 | Centimeter |
21 | Decimeter |
22 | Meter |
30 | Square centimeter |
31 | Square decimeter |
32 | Square meter |
40 | Milliliter |
41 | Liter |
42 | Cubic meter |
50 | Kilowatt hour |
51 | Gigacalorie |
70 | Day (24h) |
71 | Hour |
72 | Minute |
73 | Second |
80 | Kilobyte |
81 | Megabyte |
82 | Gigabyte |
83 | Terabyte |
255 | Applicable when using other units of measurement |
==== markQuantity ====
Parameters of markQuantity tag:
A parameter included in a tag and indicated as mandatory is only mandatory within that tag. If the tag itself is not mandatory and is not passed, its included parameters should not be passed.
Name | Type | Mandatory | Description |
---|---|---|---|
|
N..12 | yes |
The numerator of the fractional part of the payment subject. |
|
N..12 | yes |
The denominator of the fractional part of the payment subject. |
==== itemDetails ====
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
'itemDetails contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..255 | Yes |
Additional information on a line item. The parameter represents an array of blocks each of which contains information on a certain characteristic of the line item. |
All versions. |
itemDetailsParams
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
'itemDetailsParams contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..255 | Conditional. Mandatory if itemDetailsParams parameter is present. |
Additional information on a line item. |
All versions. |
Name
TypeAN..255 Type2ANS..255 DescriptionRESTName of the parameter describing the details of a line item WSName of the parameter describing the details of a line item |
AN..255 | Conditional. Mandatory if itemDetailsParams parameter is present. |
Name of the parameter describing the details of a line item |
All versions. |
==== tax ====
A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.
tax contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
N..2 | No |
VAT rate. The following values are available:
If the cart and fiscalization data are not included in the request, then the default values specified in the personal account are passed to the Fiscal Data Operator (see User Manual for personal account). |
All versions. |
|
N..18 | No |
Amount of the tax calculated by the merchant. The amount is specified in minimum currency units |
All versions. |
==== additionalOfdParams ====
additionalOfdParams contains the following elements.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
N..2 | Mandatory if agent_info object is passed. |
Agent type. The following values are available:
|
1.05 and later versions. |
|
|
No |
|
1.05 and later versions. |
|
|
No |
|
1.05 and later versions. |
|
Array ANS..19 | No |
Phone numbers array of the payments operator in +N format. |
1.05 and later versions. |
|
ANS..256 | No |
Money Transfer operator address. |
1.05 and later versions. |
|
N10..12 | No |
Money Transfer operator TIN. |
1.05 and later versions. |
|
ANS..64 | No |
Money Transfer operator name. |
1.05 and later versions. |
|
array ANS..19 | No |
An array of Money Transfer operator phone numbers in +N format. |
1.05 and later versions. |
|
Array ANS..19 | No |
An array of supplier phone numbers in +N format. |
1.05 and later versions. |
|
A..256 | No |
Cashier full name |
1.05 and later versions. |
|
ANS..16 | No |
Additional property of the receipt. |
1.05 and later versions. |
|
ANS..24 | No |
Name of the additional property of the user. |
1.05 and later versions. |
|
ANS..24 | No |
Value of the additional property of the user. |
1.05 and later versions. |
|
N..12 | No |
Cashier's INN |
1.2 and later versions. |
|
ANS..256 | No |
Customer address. |
1.2 and later versions. |
|
NS10 | No |
Customer birth date as dd.mm.yyyy |
1.2 and later versions. |
|
N3 | No |
Country numeric code of the county of Customer's citizenship. The country code is specified according to All-Russian World Countries Classifier (OKSM) |
1.2 and later versions. |
|
N2 | No |
Identification document type numeric code (for example, 21 stands for Russian Passport). |
1.2 and later versions. |
|
NS11 | No |
Series and number of the payer's passport: |
1.2 and later versions. |
|
ANS..64 | No |
Customer's email address. Exactly one of the two fields must be passed: |
1.2 and later versions. |
|
NS..19 | No |
Customer's phone number. Must be passed with the country code without spaces and additional characters (except for + character). For example, the number «+371 2 1234567» should be passed as «+37121234567»). Exactly one of the two fields must be passed: |
1.2 and later versions. |
|
N12 | No |
INN of the buyer. |
1.2 and later versions. |
|
ANS..256 | No |
Customer name. |
1.2 and later versions. |
|
|
No |
|
1.2 and later versions. |
|
|
No |
|
1.2 and later versions. |
|
|
No |
|
1.2 and later versions. |
|
|
No |
|
1.2 and later versions. |
|
NS10 | No |
Date of the legislative act of the federal body of executive power that sets forth the requirements for assigning the value of «sectoral attribute». Format: |
1.2 and later versions. |
|
ANS | No |
Identifier of federal body of executive power. Must be one of the values from directory of federal bodies of executive power |
1.2 and later versions. |
|
N..32 | No |
Number of the legislative act of the federal body of executive power that sets forth the requirements for assigning the value of «sectoral attribute». |
1.2 and later versions. |
|
ANS..256 | No |
A set of values defined by the legislative act of the federal body of executive power. |
1.2 and later versions. |
===== Response parameters ===== The response parameters are given in table below.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
A..5 | Yes |
Designates a successful request. The following values are available:
|
All versions. |
|
ANS..3 | No |
Error code. Can be missing if the result has not caused an error. |
All versions. |
|
|
No |
|
All versions. |
===== Error codes =====
Error code | Error text |
---|---|
1 | [mdOrder ] or [orderNumber ] is empty. |
5 | Incorrect amount. |
6 | Order not found. |
6 | mdOrder and orderNumber refer to different orders. |
6 | Prepayment order not found. |
7 |
System error. |
7 | There are no rights to close the OFD receipt for the current order. |
7 | Possibility to send documents to the OFD is disabled. |
7 | It is impossible to close the OFD receipt in the current state of the order. |
7 | The original OFD receipt for the order was not found. |
7 | The merchant's current active OFD system does not match the last receipt's OFD system. |
7 | The type of payment for all items in the cart of the original receipt is different from the type 'Full prepayment'. |
7 | The type of payment for all items in the cart is different from the type 'Full payment'. |
7 | Time exceeded. |
7 | The creation of an OFD receipt must be disabled if the prepayment order's 'mdOrder' is passed as an order parameter. |
7 | No rights to create a partial payment order for the specified prepayment order. |
7 | It is not possible to create a partial payment order for a prepayment order in its current state. |
7 | There are no successful OFD receipts for the prepayment order. |
7 | The merchant's current active OFD system does not match the last receipt's OFD system. |
7 | The calculation method for a prepayment order is different from 'Prepayment'(2) and 'Advance'(3). |
7 | The previous order(s) for the specified prepaid order was not paid. |
7 | No rights to create the OFD receipt manually. |
7 | Unknown OFD system. |
7 | The OFD system from the request does not match the Merchant's active OFD system. |
7 | Merchant with the specified id was not found. |
8 | [orderBundle ] is incorrect. |
8 | [additionalOfdParams ] is incorrect. |
8 | [jsonParams ] is incorrect. |
8 | The total amount is invalid. |
===== Examples ==== ==== Example of a request with a shopping cart ==== <sxh javascript> userName=username-api&password=testPwd&orderBundle={«customerDetails»:{«phone»:»%2B79888888866«,»inn«:«516974792202»,»passport«:«4507 443564»},»cartItems«:{«items»:[{«positionId»:1,»name«:«По-аджарски \»Лодочка\» SMALL«,»quantity«:{«value»:«1»,»measure«:«0»},»itemCode«:«270_235.00»,»itemPrice«:23500,»tax«:{«taxType»:0,»taxSum«:0},»itemAttributes«:{«attributes»:[{«name»:«nomenclature»,»value«:«010463003407001221CMK45BrhN0WLf»},{«name»:«paymentMethod»,»value«:«4»},{«name»:«paymentObject»,»value«:«30»},{«name»:«agent_info.type»,»value«:«7»},{«name»:«agent_info.paying.operation»,»value«:«test operation»},{«name»:«agent_info.paying.phones»,»value«:»%2B79161234123«},{«name»:«agent_info.paymentsOperator.phones»,»value«:»%2B79161234456«},{«name»:«agent_info.MTOperator.phones»,»value«:»%2B79161234789«},{«name»:«agent_info.MTOperator.name»,»value«:«MT operator»},{«name»:«agent_info.MTOperator.address»,»value«:«Moscow»},{«name»:«agent_info.MTOperator.inn»,»value«:«8634330204»},{«name»:«supplier_info.phones»,»value«:»%2B79161234333«},{«name»:«supplier_info.name»,»value«:«Supplier»},{«name»:«supplier_info.inn»,»value«:«287381373424»},{«name»:«excise»,»value«:«10.0»},{«name»:«country_code»,»value«:«810»},{«name»:«declaration_number»,»value«:«12332234533»},{«name»:«userData»,»value«:«user data»},{«name»:«markQuantity.numerator»,»value«:«1»},{«name»:«markQuantity.denominator»,»value«:«2»},{«name»:«sectoralItemProps[0].federalId»,»value«:«001»},{«name»:«sectoralItemProps[0].date»,»value«:«10.10.2021»},{«name»:«sectoralItemProps[0].number»,»value«:«123/4567»},{«name»:«sectoralItemProps[0].value»,»value«:«value1»},{«name»:«sectoralItemProps[1].federalId»,»value«:«003»},{«name»:«sectoralItemProps[1].date»,»value«:«11.10.2021»},{«name»:«sectoralItemProps[1].number»,»value«:«321/4567»},{«name»:«sectoralItemProps[1].value»,»value«:«value2»}]}}]}}&mdOrder=c4626bfb-96f8-7882-80f1-28ce0128092a </sxh> ==== Example of a request without a shopping cart ==== <sxh javascript> password:password; amount:100000; additionalOfdParams:{«additional_check_props»:«test»}; jsonParams:{«email»:«test@test.com»}; userName:atolUser; mdOrder:9766d33c-7c32-7e55-a150-f61e0cc4a648 </sxh> ==== Пример ответа ==== <sxh javascript> { «success»: true } </sxh>