Extended order status request (getOrderStatusExtended)

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
`orderId`	ANS36	Yes (see note below)	Identifier of the order in the payment system. It is unique within the system. The identifier is missing if the order registration failed due to an error detailed in errorCode.
`merchantOrderNumber`	ANS..32	Yes (see note below)	Order identifier in the Store system.
`language`	A2	No	Language in the ISO 639-1 encoding. If the language is not specified, the default language defined in the store settings is used.

You must pass either the parameter orderIdor merchantOrderNumber. If both parameters are passed, orderId has a higher priority.

Response parameters

There are three sets of response parameters. The exact sets of parameters to be returned depend on the version of getOrderStatusExtended specified in the merchant settings. These parameters will be returned in the response regardless of the version getOrderStatusExtended.

Name	Type	Mandatory	Description	Version of getOrderStatusExtended
`orderNumber`	ANS..32	Yes	The number (identifier) of the order in the store system is unique for each store within the system – up to 30 characters. If the order number is generated on the Payment Gateway side, this parameter is not mandatory.	All versions.
`orderStatus`	N1	No	The order status in the payment system is defined by the value of this parameter. It is missing if the order has not been found. Below is a list of possible values: 0 – order is registered but unpaid; `1` – the pre-authorized amount is held (for two-phase payments); 2 – full authorization of the order amount was carried out; `3` – authorization is canceled; 4 – a refund operation was performed for the transaction; `5` – authorization has been initiated through the access control server of the issuing bank; 6 – authorization is declined.	All versions.
`actionCode`	N..5	Yes	Processing code Full list of processing response codes and description of these codes is available on a separate page.	All versions.
`actionCodeDescription`	AN..512	Yes	Description of `actionCode` returned by processing. Full list of processing response codes and description of these codes is available on a separate page.	All versions.
`errorCode`	ANS..3	No	Error code. See error codes description below.	All versions.
`errorMessage`	AN..512	No	Error description in the language passed in the `language` parameter in the request.	All versions.
`amount`	N..12	Yes	Payment amount in minimum currency units.	All versions.
`currency`	N3	No	ISO 4217 code of the payment currency. If not specified, default value is used.	All versions.
`date`	ANS	Yes	Date of order registration in Unix-time format (POSIX-time).	All versions.
`depositedDate`	N	No	Date of order payment in Unix-time format (POSIX-time).	All versions.
`orderDescription`	ANS..600	No	Order description passed upon its registration.	All versions.
`ip`	ANS..39	Yes	IP-address of the buyer. IPv6 is supported in all requests (up to 39 characters).	All versions.
`authRefNum`	AN..24	No	Registration number of the payment authorization that has been assigned to it on the payment registration.	All versions.
`refundedDate`	ANS	No	Date and time of the refund.	All versions.
`paymentWay`	AS..14	yes	The way of order completion (a payment with entering card data, a payment using a binding, etc.). Possible values: `CARD` – payment with entering of card details; `CARD_BINDING` - payment by binding; `CARD_MOTO` - payment through call center; `CARD_PRESENT` - payment by cardPresent; `SBRF_SBOL` – payment through Sberbank Online; `UPOP` - payment through China Union Pay; `FILE_BINDING` - payment by file; `SMS_BINDING` - payment by SMS; `P2P` - transfer from card to card; `P2P_BINDING` - transfer by binding; `PAYPAL` – payment from a PayPal account; `MTS` – payment from MTS account; `APPLE_PAY` - Apple Pay; `APPLE_PAY_BINDING` - payment by Apple Pay binding; `ANDROID_PAY` - Android Pay; `ANDROID_PAY_BINDING` - payment by Android Pay binding; `GOOGLE_PAY_CARD` - Google Pay, non-tokenized; `GOOGLE_PAY_CARD_BINDING` - payment by binding with non-tokenized Google Pay card; `GOOGLE_PAY_TOKENIZED` - Google Pay, tokenized; `GOOGLE_PAY_TOKENIZED_BINDING` - payment by binding with tokenized Google Pay card; `SAMSUNG_PAY` - Samsung Pay; `SAMSUNG_PAY_BINDING` - payment by Samsung Pay binding; `IPOS` - iPOS payment; `SBERPAY` – SberPay payment; `SBERID` – SberID payment.	09 and higher.
`avsCode`	A1	No	AVS Response Code – AVS response code (verification of cardholder's registration address and postal code). The possible values are: A – Both address and postal code match; B – Address matches, postal code does not match; C – Postal code matches, address does not match; D – Neither address nor postal code match; E – Verification requested but not available; F – Transaction improperly requests verification.	19 and higher.
The `merchantOrderParams` element is present in a response if an order contains additional parameters of the merchant. Each additional order parameter is contained in a separate `merchantOrderParams` element.
Name `name` Type AN..20 Type2 ANS..255 Type3 A7 Type4 ANS..100 Description REST Name of the additional parameter. REST Online Lending The attribute name, always takes the value of mdOrder. WS Name of the additional parameter. Spasibo Name or the description of an item in any format. Spasibo2 Name of the parameter describing the details of a line item	AN..20	No	Name of the additional parameter.	All versions.
`value`	AN..1024	No	The value of the additional parameter is up to 1024 characters.	All versions.
`cardAuthInfo` element. Contains a structure consisting of a list of `secureAuthInfo` element and the following parameters.
`maskedPan`	N..19	No	Masked number of the card that has been used for the payment. This parameter is to be specified only after the order has been paid.	All versions.
`expiration`	ANS	No	Expiry date of the card in the format YYYYMM.	All versions.
`cardholderName`	A..200	No	Cardholder's name in Latin characters, if available.	All versions.
`approvalCode`	AN6	No	International payment system authorization code. This field has a fixed length (six characters) and can contain digits and Latin letters.	All versions.
`chargeback`	A..5	No	The parameter defines whether the funds have been forcibly returned to the buyer by the bank. The following values are available: `true` – funds were returned; `false` – funds were not returned.	06 and higher.
`paymentSystem`	N..10	yes	The payment system name. Available values: `VISA`; `MASTERCARD`; `AMEX`; `JCB`; `CUP`; `MIR`.	08 and higher.
`product`	AN..255	yes	Additional details on corporate cards. This information is filled in by technical support. If such details are missing, an empty value is returned.	08 and higher.
`productCategory`	string	yes	Additional details about corporate cards. These details are filled in by the technical support service through the administrative console. If such details are missing, an empty value is returned. The possible values are: DEBIT, CREDIT, PREPAID, NON_MASTERCARD, CHARGE, DIFFERED_DEBIT.	17
The `secureAuthInfo` element (the element consists of the `eci` and `threeDSInfo` elements the latter being an object with the `cavv` and `xid` parameters):
`eci`	N..4	No	Electronic Commerce Indicator.	All versions.
`cavv`	ANS..200	No	The value of the cardholder authentication check. Indicated only after payment of the order and in case of respective permission.	All versions.
`xid`	ANS..80	No	Electronic Commerce Indicator of the transaction. The indicator is specified only after an order has been paid and in case the corresponding permission is present.	All versions.
The `bindingInfo` element consists of the following parameters.
`clientId`	ANS..255	No	Identifier of the Customer in the Store system. This parameter is used for the binding functionality. May be present if the store is allowed to create bindings. Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be unsuccessful.	All versions.
`bindingId`	AN..255	No	The identifier of the previously created binding. Can only be used if the merchant has permission to work with bindings. If this parameter is passed in the given request, it means that: 1. The given order can be paid only using a binding; 2. The payer will be redirected to the payment page on which only entering CVC is required.	All versions.
`authDateTime`	ANS	No	Authorization date and time in Unix time (POSIX time).	02 and higher.
`terminalId`	AN..10	No	Identifier of the terminal in processing through which the payment was made.	02 and higher.
The `bankInfo` element contains the following parameters.
`bankName`	ANS..50	No	Name of the issuing bank.	03 and higher.
`bankCountryCode`	AN..7	No	Country codes of the issuing bank.	03 and higher.
`bankCountryName`	AN..160	No	Country of the issuing bank.	03 and higher.
`orderBundle`	Not applicable	Yes	Block containg the cart of items of the order. The description of the attributes is given below. (Go to description.)	03 and higher.

orderBundle

orderBundle contains the following elements.

Name	Type	Mandatory	Description	Version of getOrderStatusExtended
`customerDetails`	Not applicable	No	Block containing attributes with data about the customer. The description of the attributes is given below. (Go to description.)	12 and higher.
`cartItems`	Not applicable	Yes	Block with the attributes of the items in the cart. The description of the attributes is given below. (Go to description.)	03 and higher.

customerDetails

customerDetails contains the following elements.

Name	Type	Mandatory	Description	Version of getOrderStatusExtended
`email`	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.	03 and higher.
`phone`	NS..12	See note below.	Customer's phone number. It can be of the following format: `^((+7\|7\|8)?([0-9]){10})$`. Examples: +79000000000 89000000000 9000000000 79000000000 If the number is passed in a separate parameter and in additional parameters, the number specified in this `phone` parameter will be used. When using ATOL fiscalization, the `phone` parameter should be sent in the following format: The phone number must be passed together with the country code without spaces and additional characters except for the quotation marks (the number «371 2 1234567» must be passed as «+37121234567»). If the phone number belongs to Russia (prefix «+7»), then the value can be passed without a prefix (the number «+79251234567» can be sent as «9251234567»). The maximum string length is 64 characters. One of the fields must be filled in the request: `email` or `phone`.	03 and higher.
`fullName`	ANS..100	No	Payer's first name, last name, and patronymic.	12 and higher
`passport`	ANS..100	No	The series and number of the payer's passport in the following format: `2222888888`.	12 and higher
`inn`	N..12	No	Taxpayer identification number. From 10 to 12 digits can be passed.	12 and higher

cartItems

cartItems contains the following elements.

Name	Type	Mandatory	Description	Version of getOrderStatusExtended
`items`	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: `positionId` – Unique identifier of a product item inside the order cart. A request must contain a separate `items` tag for each line item. The description of the tag parameters is given below. (Go to description.)	03 and higher.

items

items« contains the following elements.



	
	
		 Name   Type   Mandatory    Description   Version of getOrderStatusExtended 
	
	
	
		 






Name



name




Type



ANS..100




Description




REST



Name or the description of an item in any format.







Use 

- to pass \
use \«- to pass »








REST Online Lending



For 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:


 The following words and character sequences are not allowed: file, exec, insert, as, select, or, procedure, limit, order, and, or, by, asc, desc, delete, update, distinct, having, truncate, replace, handler, like, regex, tz_offset, to_timestamp_tz, bfilename, union, sql-command, abort, alter, analyze, begin, audit, checkpoint, close, cluster, comment, commit, copy, create, deallocate, declare, delete, drop, end, execute, explain, fetch, grant, insert, lock, move, noaudit, notify, prepare, reindex, rename, reset, revoke, rollback, savepoint, select, set, show, shutdown, start, truncate, unlisten, update, vacuum

 The following special characters are not allowed: ' & – # % | ; =





WS



Name or the description of an item in any format.







Use 

- to pass \
use \«- to pass »








WS Online Lending



For 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 

- to pass \
use \«- to pass »









 03 and higher. 
	
	
		 





quantity





 





N..18





 Yes   





Element describing the total of items of one positionId and its unit of measurement The description of the attributes is given below.







 (Go to description.) 

 03 and higher. 
	
	
		 





itemAmount





 





N..18





 No   





The sum of the cost of all line items of one positionId in minimum currency units. Passing itemAmount is mandatory only if the itemPrice parameter was not passed. Otherwise passing of itemAmount is not required. If both parameters – itemPrice and itemAmount – are passed. then itemAmount must be equal to itemPrice * quantity, otherwise, the request will result in an error.







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.









 03 and higher. 
	
	
		 





itemCurrency





 





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.





 03 and higher. 
	
	
		 





itemCode





 





ANS..100





 Yes   





Number (identifier) of a line item in the store system.





 03 and higher.

Name	Type	Mandatory	Description	Version of getOrderStatusExtended
Name `name` Type ANS..100 Description REST Name or the description of an item in any format. Use - to pass \ use \«- to pass » REST Online Lending For 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: The following words and character sequences are not allowed: file, exec, insert, as, select, or, procedure, limit, order, and, or, by, asc, desc, delete, update, distinct, having, truncate, replace, handler, like, regex, tz_offset, to_timestamp_tz, bfilename, union, sql-command, abort, alter, analyze, begin, audit, checkpoint, close, cluster, comment, commit, copy, create, deallocate, declare, delete, drop, end, execute, explain, fetch, grant, insert, lock, move, noaudit, notify, prepare, reindex, rename, reset, revoke, rollback, savepoint, select, set, show, shutdown, start, truncate, unlisten, update, vacuum The following special characters are not allowed: ' & – # % \| ; = WS Name or the description of an item in any format. Use - to pass \ use \«- to pass » WS Online Lending For 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 - to pass \ use \«- to pass »	03 and higher.
`quantity`	N..18	Yes	Element describing the total of items of one `positionId` and its unit of measurement The description of the attributes is given below. (Go to description.)	03 and higher.
`itemAmount`	N..18	No	The sum of the cost of all line items of one `positionId` in minimum currency units. Passing `itemAmount` is mandatory only if the `itemPrice` parameter was not passed. Otherwise passing of `itemAmount` is not required. If both parameters – itemPrice and itemAmount – are passed. then itemAmount must be equal to itemPrice * quantity, otherwise, the request will result in an error. 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.	03 and higher.
`itemCurrency`	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.	03 and higher.
`itemCode`	ANS..100	Yes	Number (identifier) of a line item in the store system.	03 and higher.

==== quantity ====quantity'' contains the following elements.

Name	Type	Mandatory	Description	Version of getOrderStatusExtended
`measure`	ANS..20	Yes	The unit of measurement for the quantity of line item instances.	03 and higher.

Error codes

Error code	Error text
0	The request has been processed without system errors.
5	Access denied.
5	The user must change the password.
5	`[orderId]` not specified.
6	Unregistered `orderId`.
7	System error.

Examples

Request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
    <soapenv:Header/>
    <soapenv:Body>
       <mer:getOrderStatusExtended>
          <order orderId="942e8534-ac73-4e3c-96c6-f6cc448018f7" language="en">
             <!--Optional:-->
             <merchantOrderNumber> </merchantOrderNumber>
            </order>
       </mer:getOrderStatusExtended>
    </soapenv:Body>
 </soapenv:Envelope>

Response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getOrderStatusExtendedResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return orderNumber="1499420313736" orderStatus="2" actionCode="0" actionCodeDescription="" amount="10500" currency="643" date="2017-07-07T12:41:11.654+03:00" orderDescription="Description" ip="127.0.0.1" errorCode="0" errorMessage="Successfully">
            <attributes name="mdOrder" value="dc84ffbc-1d04-4748-94dc-75d87e91a745"/>
            <cardAuthInfo maskedPan="555555**5599" expiration="202012" cardholderName="Test" approvalCode="111111"/>
            <authDateTime>2017-07-07T12:41:12.185+03:00</authDateTime>
            <terminalId>12345678</terminalId>
            <authRefNum>111111111111</authRefNum>
            <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="10500" depositedAmount="10500" refundedAmount="0"/>
            <bankInfo bankName="SOME BANK IN USA" bankCountryCode="US" bankCountryName="The United States of America"/>
            <orderBundle>
               <cartItems>
                  <items positionId="1">
                     <name>Universal Mirror Enduro</name>
                     <quantity measure="units">3.0</quantity>
                     <itemAmount>6000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>
                  </items>
                  <items positionId="2">
                     <name>A ticked to Moscow</name>
                     <quantity measure="units">1.0</quantity>
                     <itemAmount>4500</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>GFCCHC</itemCode>
                  </items>
               </cartItems>
            </orderBundle>
         </return>
      </ns1:getOrderStatusExtendedResponse>
   </soap:Body>
</soap:Envelope>

Инструменты страницы

Extended order status request (getOrderStatusExtended)

Request parameters

Response parameters

Name

Type

Type2

Type3

Type4

Description

REST

REST Online Lending

WS

Spasibo

Spasibo2