Request for order extended status

The request used for getting the status of a registered order is «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:

Name Type Mandatory Description

orderId

AN..64

Yes*

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.

language

A2

No

Language code in accordance with ISO 639-1. If this parameter is not specified, it is considered that the language is Russian. An error message will be returned in this language.

merchantOrderNumber

AN..32

Yes*

Order identifier in the Store system.

* It is necessary to pass either the orderId or merchantOrderNumber parameter in the request. If both parameters are passed, orderId has a higher priority.

Several sets of response parameters exist. The exact sets of parameters to be returned depend on the version of getOrderStatusExtended specified in the merchant settings.

Response parameters for versions 01 and higher:

These parameters will be returned in the response regardless of the version of getOrderStatusExtended.

Name Type Mandatory Description Version of getOrderStatusExtended

orderNumber

AN..32

Yes

Order identifier in the Store system.

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 Response code. All versions.

actionCodeDescription

AN..512

Yes

Description of the response code in the language that is passed in language parameter of the request.

All versions.

errorCode

N3

No

Error code.

All versions.

errorMessage

AN..512

No

Error description in the language passed in the language parameter in the request.

All versions.

amount

N..20

Yes The payment amount in kopecks (or cents). All versions.

currency

N3

No ISO 4217 code of the payment currency. If the code is not specified, the default value is 643 (Russian rubles). All versions.

date

ANS

Yes

Order registration date.

All versions.

orderDescription

AN..512

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.

authDateTime

ANS

No The authorization date and time. 02 and higher.

authRefNum

AN..24

No

Registration number of the payment authorization that has been assigned to it on the payment registration.

02 and higher.

terminalId

AN..10

No

Identifier of the terminal in processing through which the payment was made.

02 and higher.

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.
cardAuthInfo element (the element contains a structure consisting of a list of elements of type secureAuthInfo and attributes maskedPan, expiration, cardholderName and approvalCode) $4:

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

N6

No

The expiration date of the card validity period, in the format YYYYMM. This parameter is to be specified only after the order has been paid

All versions.

cardholderName

A..64

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.
The secureAuthInfo element contains the eci element and the threeDSInfo element, the latter being an object with the cavv and xid parameters):

eci

N..4

No

Electronic Commerce Indicator.

Is specified only after an order has been paid and in case the corresponding permission is present.

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.
BindingInfo element (consists of clientId and bindingId):

clientId

AN..255

No

Identifier of the Customer in the Store system passed on the order registration. This parameter is present only if a Store has the permission to create bindings.

All versions.

bindingId

AN..255

No

Identifier of a binding created on an order payment or used to pay for an order. This parameter is present only if a Store has the permission to create bindings.

.

All versions.
paymentAmountInfo element (comprises approvedAmount, depositedAmount, refundedAmount and paymentState):

approvedAmount

N..12

No

The amount put on hold on the card (is used only for two-phase payments).

03 and higher.

depositedAmount

N..12

No

The amount confirmed for debiting from the card.

03 and higher.

refundedAmount

N..12

No

The refund amount.

03 and higher.

paymentState

A..10

No

Payment status.

03 and higher.
bankInfo element (comprises bankName, bankCountryCode and bankCountryName):

bankName

AN..200

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

Name of the country of the issuing bank passed in the language parameter of the request or in the language of the user who has called the method if the language has not been specified in the request.

03 and higher.
loyaltyInfo/loyaltyInfos element (consists of the element loyaltyName and tags paymentBonus and awardBonus) – tag containing data about the status of bonus points for loyalty programs in the order
loyaltyInfo element (consists of the element loyaltyName and tags paymentBonus and awardBonus) No Tag containing data about the status of bonus points for loyalty programs in the order 04 and higher.
loyaltyInfos element (consists of the element loyaltyName and tags paymentBonus and awardBonus) No Tag containing data about the status of bonus points for loyalty programs in the order Version 15 and higher.

loyaltyName

ANS..512

No

The name of the loyalty program (for Sberbank Spasibo bonuses, these are «sbrf_spasibo» and «sbrf_sbermiles»).

Version 15 and higher.
paymentBonus No Tag with attributes containing data about the status of used points to be debited along with payment for an order 04 and higher.
awardBonus No Tag with attributes containing data about the state of funds used to accrue points along with payment for an order 04 and higher.

paymentBonus element attributes:

Name Type Mandatory Description

approvedAmountBonus

N..20

No

The amount of points to be debited along with payment for the order.

depositedAmountBonus

N..20

No

The confirmed amount in points to be debited at the time of the request.

refundedAmountBonus

N..20

No

Refund amount in points at the time of request.

pcId

ANS..512

No

The identifier of the last performed operation with the amount for the accrual of points in the loyalty processing.

successful

ANS..512

Yes

A feature of the success of the operation, the following values are possible:

  • true (successful);
  • false (unsuccessful).

paymentOperation

ANS..512

Yes

Type of the last transaction performed with the points being debited (PAYMENT, REVERSE, REFUND_PAYMENT)

awardBonus element attributes:

Name Type Mandatory Description

approvedAmountAward

N..20

No

The initial amount for which the bonus points were accrued.

depositedAmountAward

N..20

No

The confirmed order amount for which the bonus points were accrued.

refundedAmountAward

N..20

No

The amount of the order refunded, for which the bonus points were accrued.

pcId

AN..512

No

The identifier of the last performed operation with the amount for the accrual of points in the loyalty processing.

successful

AN..512

Yes

A feature of the success of the operation, the following values are possible:

  • true (successful);
  • false (unsuccessful).

paymentOperation

ANS..512

Yes

The type of the last transaction performed with the amount for the accrual of points (AWARD, REVERSE, REFUND_AWARD).

If the request for registering an order included a cart, then in response to the request for the extended status of the order would include an orderBundle block containing the shopping cart of the order. Description of orderBundle block is given below. (Applicable to getOrderStatusExtended 03 and higher.).

orderBundle parameter:

Name Type Mandatory Description Version of getOrderStatusExtended

orderCreationDate

ANS..21

No

Order creation date in the format YYYY-MM-DDTHH:MM:SS.

03 and higher.

customerDetails

No

Block containing attributes with data about the customer. The description of the attributes is given below.

03 and higher.

cartItems

Yes

Block with the attributes of the items in the cart. The description of the attributes is given below.

03 and higher.

loyalties

No

A block with attributes of bonus programs in which line items from the Shopping cart participate. The description of the attributes is given below.

If the loyalties block parameter is not passed in the request and the amount to be debited in points is calculated not on the merchant's side, then this block will still be returned in response to an extended order status request.

04 and higher.

customerDetails block parameters:

Name Type Mandatory Description Version of getOrderStatusExtended

email

ANS..40

No

Customer's email address.

03 and higher.

phone

NS..12

No Customer's phone number. 03 and higher.

contact

ANS..40

No

Customer's preferred way of communication.

04 and higher.

deliveryInfo

No

Block containing the attributes of the delivery address. The description of the attributes is given below.

04 and higher.

deliveryInfo block parameters:

Name Type Mandatory Description Version of getOrderStatusExtended

deliveryType

ANS..20

No

Delivery method.

04 and higher.

country

A..2

Yes

The two-letter country code for the delivery country.

04 and higher.

city

ANS..40

Yes

Delivery city.

04 and higher.

postAddress

ANS..255

Yes

Delivery address.

04 and higher.

cartItems block parameters:

Name Type Mandatory Description Version of getOrderStatusExtended

items

Yes

An element of the array containing attributes of an item in the cart. The description of the attributes is given below.

03 and higher.

items element attributes:

Name Type Mandatory Description Version of getOrderStatusExtended

positionId

ANS..12

Yes

The identifier of the line item participating in the specified bonus program.

03 and higher.

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

ANS..100

Yes

Name or the description of an item in any format.

03 and higher.

itemDetails

No

Additional block containing the parameters describing a line item. The description of the attributes is given below.

04 and higher.

quantity

Yes

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

03 and higher.

itemAmount

N..18

Yes

The total cost of all instances of one positionId specified in minimum currency units.

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 element attributes:

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.

itemDetails block parameters:

Name Type Mandatory Description Version of getOrderStatusExtended

itemDetailsParams

No

Parameter describing additional information regarding a line item. The description of the attributes is given below.

04 and higher.

itemDetailsParams parameter attributes:

Name Type Mandatory Description Version of getOrderStatusExtended

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

ANS..255

Conditional. Mandatory if itemDetailsParams parameter is present

Name of the parameter describing the details of a line item

04 and higher.

loyalties block parameters:

Name Type Mandatory Description Version of getOrderStatusExtended

loyaltyProgramName

ANS..20

Yes

The conventional name of the bonus program, in which the item is involved, is issued by the payment gateway.

04 and higher.

positionId

ANS..12

Yes

The identifier of the line item participating in the specified bonus program.

04 and higher.

bonusAmountForDebit

N..18

Yes

The total amount of bonuses of all line items for this positionId to debiting, indicated in kopecks.

04 and higher.

bonusAmountForCredit

N..18

No

The total amount of bonuses of all line items for this positionId to accrual, indicated in kopecks.

04 and higher.

Error codes (errorCode field):

Value Description
0 Request processing took place without system errors
1 Expected [orderId] or [orderNumber]
5 Access denied
5 The user must change their password
6 Order not found
7 System error

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="694312ed-9dd1-4178-9009-e1ac1aa5fb92" language=" ">
             <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="24398" orderStatus="2" actionCode="0" actionCodeDescription="Payment processed successfully" amount="30000" currency="643" date="2014-03-06T12:31:29.585+04:00" orderDescription="testCart singlestep" ip="0.0.0.7" errorCode="0" errorMessage="Success">
             <merchantOrderParams name="sbrf_spasibo:amount_bonus" value="300"/>
             <attributes name="mdOrder" value="694312ed-9dd1-4178-9009-e1ac1aa5fb92"/>
             <cardAuthInfo maskedPan="478978**1233" expiration="201512" cardholderName="cardholder name" approvalCode="123456"/>
             <authDateTime>2014-03-06T12:31:29.585+04:00</authDateTime>
             <terminalId>999714</terminalId>
             <authRefNum>111111111111</authRefNum>
             <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="30000" depositedAmount="30000" refundedAmount="0"/>
             <bankInfo bankCountryCode="UNKNOWN" bankCountryName="<Unknown>"/>
             <orderBundle>
                <orderCreationDate>2013-07-12T13:51:00+04:00</orderCreationDate>
                <customerDetails>
                   <email>johnsmith@mail.ru</email>
                   <phone>89851231234</phone>
                   <contact>Mega Tester</contact>
                   <deliveryInfo>
                      <deliveryType>courier</deliveryType>
                      <country>RU</country>
                      <city>Moscow</city>
                      <postAddress> Bld. 2, 50A/8 Zemlyanoy Val St.</postAddress>
                   </deliveryInfo>
                </customerDetails>
                <cartItems>
                   <items positionId="3">
                      <name>Warm Grips</name>
                      <itemDetails>
                         <itemDetailsParams name="brand">Noname</itemDetailsParams>
                      </itemDetails>
                      <quantity measure="units">1.0</quantity>
                      <itemAmount>10000</itemAmount>
                      <itemCurrency>643</itemCurrency>
                      <itemCode>G-16</itemCode>
                   </items>
                   <items positionId="1">
                      <name>Metzeler Enduro 3 Sahara</name>
                      <itemDetails>
                         <itemDetailsParams name="brand">Metzeler</itemDetailsParams>
                         <itemDetailsParams name="radius">17inch</itemDetailsParams>
                      </itemDetails>
                      <quantity measure="units">1.0</quantity>
                      <itemAmount>10000</itemAmount>
                      <itemCurrency>643</itemCurrency>
                      <itemCode>T-M-14</itemCode>
                      <discount>
                         <discountType>discount</discountType>
                         <discountValue>777</discountValue>
                      </discount>
                   </items>
                   <items positionId="2">
                      <name>Universal Mirror Enduro</name>
                      <itemDetails>
                         <itemDetailsParams name="brand">Noname</itemDetailsParams>
                         <itemDetailsParams name="diameter">12mm</itemDetailsParams>
                      </itemDetails>
                      <quantity measure="units">1.0</quantity>
                      <itemAmount>10000</itemAmount>
                      <itemCurrency>643</itemCurrency>
                      <itemCode>NM-15</itemCode>
                   </items>
                </cartItems>
             </orderBundle>
             <loyaltyInfo loyaltyName="sbrf_spasibo">
                <paymentBonus approvedAmountBonus="300" depositedAmountBonus="300" refundedAmountBonus="0" pcId="3139154" successful="true" paymentOperation="PAYMENT"/>
                <awardBonus approvedAmountAward="30000" depositedAmountAward="30000" refundedAmountAward="0" pcId="3139155" successful="true" paymentOperation="AWARD"/>
             </loyaltyInfo>
          </return>
       </ns1:getOrderStatusExtendedResponse>
    </soap:Body>
 </soap:Envelope>

Example response for version getOrderStatusExtended 15 and higher:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getOrderStatusExtendedResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return orderNumber="1254003" orderStatus="2" actionCode="0" actionCodeDescription="" amount="8234100" currency="643" date="2020-03-18T17:56:54.386+03:00" depositedDate="2020-03-18T18:03:50.859+03:00" orderDescription="Test payment" ip="84.53.237.7" errorCode="0" errorMessage="Success">
            <merchantOrderParams name="sbrf_sbermiles:amount_bonus" value="240500"/>
            <merchantOrderParams name="loyaltyId" value="sbrf_spasibo,sbrf_sbermiles"/>
            <merchantOrderParams name="sbrf_spasibo:amount_bonus" value="1525400"/>
            <merchantOrderParams name="sbrf_spasibo:change_rate" value="1"/>
            <merchantOrderParams name="test" value="test"/>
            <merchantOrderParams name="sbrf_sbermiles:change_rate" value="1.2"/>
            <merchantOrderParams name="client_uuid" value="B0201548AD304A55BA59983882C46B83"/>
            <merchantOrderParams name="new_card_payment" value="true"/>
            <merchantOrderParams name="pay-button" value="true"/>
            <transactionAttributes name="merchantIp" value="84.53.237.7"/>
            <attributes name="mdOrder" value="c559e30a-f363-70cf-9e5a-e5e65e205139"/>
            <cardAuthInfo maskedPan="427601**6080" expiration="202412" cardholderName="CARDHOLDER NAME" approvalCode="123456" paymentSystem="VISA"/>
            <authDateTime>2020-03-18T17:57:45.194+03:00</authDateTime>
            <terminalId>123456</terminalId>
            <authRefNum>243686633625</authRefNum>
            <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="8234100" depositedAmount="8234100" refundedAmount="0" feeAmount="0"/>
            <bankInfo bankName="SBERBANK OF RUSSIA" bankCountryCode="RU" bankCountryName="Russia"/>
            <payerData email="kuznecov@liqu.ru" phone="9040326222"/>
            <orderBundle>
               <customerDetails>
                  <email>kuznecov@liqu.ru</email>
                  <phone>9040326222</phone>
               </customerDetails>
               <cartItems>
                  <items positionId="1">
                     <name>Siemens WS12T460OE washing machine</name>
                     <quantity measure="pcs">1.0</quantity>
                     <itemAmount>6587281</itemAmount>
                     <depositedItemAmount>6587281</depositedItemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>78864</itemCode>
                  </items>
                  <items positionId="2">
                     <name>Service – Delivery</name>
                     <quantity measure="pcs">1.0</quantity>
                     <itemAmount>823410</itemAmount>
                     <depositedItemAmount>823410</depositedItemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>0002</itemCode>
                  </items>
                  <items positionId="3">
                     <name>Something – Delivery</name>
                     <quantity measure="pcs">1.0</quantity>
                     <itemAmount>823409</itemAmount>
                     <depositedItemAmount>823409</depositedItemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>0004</itemCode>
                  </items>
               </cartItems>
               <loyalties>
                  <loyalties loyaltyProgramName="sbrf_spasibo" positionId="1">
                     <bonusAmountForDebit>1220320</bonusAmountForDebit>
                     <bonusAmountForCredit>0</bonusAmountForCredit>
                  </loyalties>
                  <loyalties loyaltyProgramName="sbrf_spasibo" positionId="2">
                     <bonusAmountForDebit>152540</bonusAmountForDebit>
                     <bonusAmountForCredit>0</bonusAmountForCredit>
                  </loyalties>
                  <loyalties loyaltyProgramName="sbrf_spasibo" positionId="3">
                     <bonusAmountForDebit>152540</bonusAmountForDebit>
                     <bonusAmountForCredit>0</bonusAmountForCredit>
                  </loyalties>
                  <loyalties loyaltyProgramName="sbrf_sbermiles" positionId="1">
                     <bonusAmountForDebit>192399</bonusAmountForDebit>
                     <bonusAmountForCredit>0</bonusAmountForCredit>
                  </loyalties>
                  <loyalties loyaltyProgramName="sbrf_sbermiles" positionId="2">
                     <bonusAmountForDebit>24050</bonusAmountForDebit>
                     <bonusAmountForCredit>0</bonusAmountForCredit>
                  </loyalties>
                  <loyalties loyaltyProgramName="sbrf_sbermiles" positionId="3">
                     <bonusAmountForDebit>24051</bonusAmountForDebit>
                     <bonusAmountForCredit>0</bonusAmountForCredit>
                  </loyalties>
               </loyalties>
            </orderBundle>
            <loyaltyInfos loyaltyName="sbrf_sbermiles">
               <paymentBonus approvedAmountBonus="240500" depositedAmountBonus="240500" refundedAmountBonus="0" pcId="81924304" successful="true" paymentOperation="PAYMENT"/>
               <awardBonus approvedAmountAward="8234100" depositedAmountAward="8234100" refundedAmountAward="0" pcId="81924386" successful="true" paymentOperation="AWARD"/>
            </loyaltyInfos>
            <loyaltyInfos loyaltyName="sbrf_spasibo">
               <paymentBonus approvedAmountBonus="1525400" depositedAmountBonus="1525400" refundedAmountBonus="0" pcId="81924303" successful="true" paymentOperation="PAYMENT"/>
               <awardBonus approvedAmountAward="8234100" depositedAmountAward="8234100" refundedAmountAward="0" pcId="81924385" successful="true" paymentOperation="AWARD"/>
            </loyaltyInfos>
            <chargeback>false</chargeback>
            <paymentWay>CARD</paymentWay>
         </return>
      </ns1:getOrderStatusExtendedResponse>
   </soap:Body>
</soap:Envelope>