Order verification (checkOrder)

Description

This request allows the merchant to check the validity of transfer parameters before the user pays for the order (see step 5 in the general payment flow). It means that the buyer is prepared to pay, but it doesn't guarantee that payment will be completed successfully, and it isn't the final condition for product delivery. After successful payment, the merchant receives a different request: Notification of payment (paymentAviso).

Note. 
  • The checkOrder request is usually formed before funds are debited from the customer's account. At this stage, the merchant can refuse to accept the payment (if, for example, the product is not in stock).
  • If the merchant reserves the product after checkOrder, they should keep in mind that funds have not been debited yet: the payer may not confirm the payment. You can use the invoice expiration as a measure and un-reserve the product upon expiration.
  • When paying with a bank card, payment is authorized when the checkOrder request is formed. If the store refuses to process the payment after verification, the money is automatically refunded to the card.
  • If the user is paying with something other than a Yandex.Money Wallet, external payment systems may take an additional commission. In this case, if the store refused the payment, the amount of money minus this commission fee is returned to the user.

For more information about using a checkOrder request for various payment methods, see the section Payment process description.

Method name

checkOrder

Address for receiving request

checkURL — The URL in the merchant's system. Stored on Yandex.Checkout. You can set it during activation.

Input parameters

Parameter

Type

Description

requestDatetime

dateTime

Time when request was formed in Yandex.Checkout.

action

normalizedString, maximum 16 characters

Request type. Value: checkOrder

When exchanging data in PKCS#7 format, it is passed as the opening tag of an XML document.

md5

normalizedString, exactly 32 uppercase hexadecimal characters

MD5 hash of the payment form parameters (see the rules for forming it).

Omitted when exchanging data in PKCS#7 format.

shopId

long

The merchant ID issued when activating Yandex.Checkout.

shopArticleId

long

Product ID issued by Yandex.Checkout.

invoiceId

long

Unique transaction number in Yandex.Checkout.

orderNumber

normalizedString, maximum 64 characters

The order number in the merchant's system. Passed only if it was indicated in the payment form.

customerNumber

normalizedString, maximum 64 characters

The customer number used by the merchant. Sent in the payment form.

orderCreatedDatetime

dateTime

Time when order was registered in Yandex.Checkout.

orderSumAmount

CurrencyAmount

The order total sent in the sum parameter in the payment form.

orderSumCurrencyPaycash

CurrencyCode

Currency code for the order amount.

orderSumBankPaycash

CurrencyBank

Yandex.Checkout processing center code for order total.

shopSumAmount

CurrencyAmount

Total to be paid into merchant's account (order total minus Yandex.Checkout commission).

shopSumCurrencyPaycash

CurrencyCode

Currency code for shopSumAmount.

shopSumBankPaycash

CurrencyBank

Yandex.Checkout processing center code for shopSumAmount.

paymentPayerCode

YMAccount

Yandex.Money account number used for payment.

paymentType

normalizedString

Method of paying for the order. Payment method codes

Any names other than those listed above

string

Parameters added to the payment form by the merchant.

Note. 
  • Requests may contain parameters not covered in this document. The merchant should ignore them.
  • The request doesn't have to contain all the parameters. Only parameters that are needed for calculating the MD5 checksum are required (action, orderSumAmount, orderSumCurrencyPaycash, orderSumBankPaycash, shopId, invoiceId, customerNumber).

Response parameters

Parameter

Type

Description

performedDatetime

dateTime

Time in Yandex.Checkout when request was processed.

code

int

Code of the processing result. The table below lists possible values.

shopId

long

Store ID. Matches the value of the shopId parameter in the request.

invoiceId

long

Yandex.Checkout transaction ID. Matches the value of the invoiceId parameter in the request.

orderSumAmount

CurrencyAmount

The amount of the order in the currency defined by the orderSumCurrencyPaycash request parameter.

message

string, maximum of 255 characters

Text explanation if the payment is not accepted.

techMessage

string, maximum of 64 characters

Additional text explanation of the merchant's response.

This is usually used for more detailed information about errors. Optional field.

Request processing result codes

Code

Value

Description

0

Successful

The merchant agreed and is ready to accept the transfer.

1

Authorization error

The md5 parameter does not match the result of calculating the hash function. Fatal error.

100

Refused to accept transfer

Refusal to accept the transfer with the specified parameters. Fatal error.

200

Request parsing error

The merchant is not able to parse the request. Fatal error.

Examples

Request example using an MD5 checksum
POST /path_to_checkOrder HTTP/1.1 
Host: someshop.ru 
Content-Type: application/x-www-form-urlencoded

Request parameters

requestDatetime

2011-05-04T20:38:00.000+04:00

action

checkOrder

md5

8256D2A032A35709EAF156270C9EFE2E

shopId

13

shopArticleId 456

invoiceId

1234567

customerNumber

8123294469

orderCreatedDatetime

2011-05-04T20:38:00.000+04:00

orderSumAmount

87.10

orderSumCurrencyPaycash

643

orderSumBankPaycash

1001

shopSumAmount

86.23

shopSumCurrencyPaycash

643

shopSumBankPaycash

1001

paymentPayerCode

42007148320

paymentType

AC

MyField

Field added by merchant

Request example in PKCS#7 format
POST /path_to_checkOrder HTTP/1.1 
Host: someshop.ru 
Content-Type: application/pkcs7-mime
<checkOrderRequest
        requestDatetime="2011-05-04T20:38:00.000+04:00" 
        invoiceId="1234567"
        shopId="13" 
        shopArticleId="456"
        customerNumber="8123294469"
        orderCreatedDatetime="2011-05-04T20:38:00.000+04:00"
        paymentPayerCode="42007148320"
        orderSumAmount="87.10"
        orderSumCurrencyPaycash="643" 
        orderSumBankPaycash="1001"
        shopSumAmount="86.23"
        shopSumCurrencyPaycash="643" 
        shopSumBankPaycash="1001"
        paymentType="AC">
    <param key="MyField" val="Field added by the store"/>
</checkOrderRequest>
Response example for successful processing
<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00" code="0" invoiceId="1234567" shopId="13"/>
Response example with error

The merchant refused to accept the transfer at the order verification stage:

<checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00" code="100" invoiceId="1234567" shopId="13"
 message="Specified phone number does not exist" techMessage="Invalid phone number"/>