Инструменты страницы
Request for receipt closure (closeOfdReceipt)
The request used for closing the receipt is closeOfdReceipt
.
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 |
---|---|---|---|---|
|
ANS..36 | Either mdOrder or merchantOrderNumber must be passed |
Order number in the payment gateway. Unique within the payment gateway. |
All versions. |
|
ANS..32 | Either mdOrder or merchantOrderNumber must be passed |
Order identifier in the Store system. |
All versions. |
|
N..12 | No |
Payment amount in minimum currency units. |
All versions. |
|
See column with the description. | 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
customerDetails
contains the following elements.
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.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..40 | See note below. |
Customer's email address. You can specify several comma separated (without spaces) email addresses – in this case the receipt will be delivered to all specified addresses. |
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
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. |
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
cartItems
contains the following elements.
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.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
Not applicable | Yes |
Tag containing the parameters with the data about one item from the cart .
Item number is specified as an attribute of the tag:
A request must contain a separate |
All versions. |
items
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 price of one line item of one
|
All versions. |
|
See description. | Only for stores with enabled fiscalization settings |
Tag that serves to pass a set of attributes of the line item. Attributes must be specified as follows.
<attributes name="attribute_name_1">attribute_value_1</attributes> <attributes name="attribute_name_2">attribute_value_2</attributes> 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 ====
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 ==== 'itemDetails contains the following elements.
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.
Name | Type | Mandatory | Description | FFD version |
---|---|---|---|---|
|
ANS..255 | Yes |
Parameter describing additional information regarding a line item. The description of the attributes is given below. |
All versions. |
itemDetailsParams
'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 |
ANS..255 | Conditional. Mandatory if itemDetailsParams parameter is present. |
Name of the parameter describing the details of a line item |
All versions. |
==== tax ====
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. |
All versions. |
|
|
No |
|
All versions. |
===== Error codes =====
Error code | Error text |
---|---|
0 |
The request has been processed without system errors. |
1 |
An order with this number has already been processed. |
1 |
Wrong order number. |
3 |
Unknown currency. |
4 |
Order number is empty |
4 |
Merchant name cannot be empty. |
4 |
The amount is missing. |
4 |
Empty return URL |
4 |
Password cannot be empty. |
5 |
Access denied. |
5 |
The user is inactive. |
7 |
System error. |
8 |
|
8 |
Additional parameter |
8 |
|
===== Examples ==== ==== Example of a request with a shopping cart ==== <sxh xml> <soapenv:Envelope xmlns:soapenv=«http://schemas.xmlsoap.org/soap/envelope/» xmlns:mer=«http://engine.paymentgate.ru/webservices/merchant»> <soapenv:Header> <soapenv:Body> <mer:closeOfdReceipt> <request mdOrder=«09fddf4a-fd30-76ca-ad2e-36f50128092a» amount=«23500»/> <orderBundle> <customerDetails> <phone>+79123456789</phone> <inn>516974792202</inn> <passport>4507 443564</passport> </customerDetails> <!– Contents of the cart –> <cartItems> <!– Zero or more repetitions: –> <items positionId=«1»> <name>«SMALL»</name> <quantity measure=«0»>1</quantity> <itemCode>270_235.00</itemCode> <itemPrice>23500</itemPrice> <tax> <taxType>0</taxType> <taxSum>0</taxSum> </tax> <itemAttributes> <attributes name=«nomenclature»>010463003407001221CMK45BrhN0WLf</attributes> <attributes name=«paymentMethod»>1</attributes> <attributes name=«paymentObject»>30</attributes> <attributes name=«agent_info.type»>7</attributes> <attributes name=«agent_info.paying.operation»>testoperation</attributes> <attributes name=«agent_info.paying.phones»>+79123456789</attributes> <attributes name=«agent_info.paymentsOperator.phones»>+79123456789</attributes> <attributes name=«agent_info.MTOperator.phones»>+79123456789</attributes> <attributes name=«agent_info.MTOperator.name»>MT operator</attributes> <attributes name=«agent_info.MTOperator.address»>Moscow</attributes> <attributes name=«agent_info.MTOperator.inn»>8634330204</attributes> <attributes name=«supplier_info.phones»>+79123456789</attributes> <attributes name=«supplier_info.name»>Supplier</attributes> <attributes name=«supplier_info.inn»>287381373424</attributes> <attributes name=«excise»>10.0</attributes> <attributes name=«country_code»>810</attributes> <attributes name=«declaration_number»>12332234533</attributes> <attributes name=«userData»>user data</attributes> <attributes name=«markQuantity.numerator»>1</attributes> <attributes name=«markQuantity.denominator»>2</attributes> <attributes name=«sectoralItemProps[0].federalId»>001</attributes> <attributes name=«sectoralItemProps[0].date»>10.10.2021</attributes> <attributes name=«sectoralItemProps[0].number»>123/4567</attributes> <attributes name=«sectoralItemProps[0].value»>value1</attributes> <attributes name=«sectoralItemProps[1].federalId»>003</attributes> <attributes name=«sectoralItemProps[1].date»>10.10.2021</attributes> <attributes name=«sectoralItemProps[1].number»>321/4567</attributes> <attributes name=«sectoralItemProps[1].value»>value2</attributes> </itemAttributes> </items> </cartItems> </orderBundle> </mer:closeOfdReceipt> </soapenv:Body> </soapenv:Envelope> </sxh> ==== Example of a request without a shopping cart ==== <sxh xml> <soapenv:Envelope xmlns:soapenv=«http://schemas.xmlsoap.org/soap/envelope/» xmlns:mer=«http://engine.paymentgate.ru/webservices/merchant»> <soapenv:Header/> <soapenv:Body> <mer:closeOfdReceipt> <order merchantOrderNumber=«78ds901234567890» description=» « amount=«15000» currency=» « language=» « pageView=«DESKTOP» sessionTimeoutSecs=» « bindingId=» « expirationDate=«2014-09-08T14:14:14»> <params name=«param1» value=«valueParam1»/> <params name=«param2» value=«valueParam2»/> <orderId>666</orderId> </order> </mer:closeOfdReceipt> </soapenv:Body> </soapenv:Envelope> </sxh> ==== Пример ответа ==== <sxh xml> <soap:Envelope xmlns:soap=«http://schemas.xmlsoap.org/soap/envelope/»> <soap:Body> <ns1:closeOfdReceiptResponse xmlns:ns1=«http://engine.paymentgate.ru/webservices/merchant»> <return> <success>true</success> </return> </ns1:closeOfdReceiptResponse> </soap:Body> </soap:Envelope> </sxh>