Order verification (checkOrder) — [Archive] Payment solution protocol for merchants

Order verification (checkOrder)

This is an old version of the API. Switch to the YooMoney API.

This request allows the merchant to check the validity of payment 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).

Specifics

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 or via Mir Pay, 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 YooMoney for Shopping 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.

Request

Method name: checkOrder

Address for receiving request

checkURL — The URL in the merchant’s system. Stored on YooMoney. You can set it during activation.

Request parameters

Parameter	Type	Description
requestDatetime	dateTime	Time when request was formed in YooMoney.
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 YooMoney.
shopArticleId	long	Product ID issued by YooMoney.
invoiceId	long	Unique transaction number in YooMoney.
orderNumber	normalizedString, maximum 64 characters	Order number in 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 YooMoney.
orderSumAmount	CurrencyAmount	The order total sent in the `sum` parameter in the payment form.
orderSumCurrencyPaycash	CurrencyCode	Currency code for the order amount.
orderSumBankPaycash	CurrencyBank	YooMoney processing center code for order total.
shopSumAmount	CurrencyAmount	Total to be paid into merchant’s account (order total minus YooMoney commission).
shopSumCurrencyPaycash	CurrencyCode	Currency code for `shopSumAmount`.
shopSumBankPaycash	CurrencyBank	YooMoney processing center code for `shopSumAmount`.
paymentPayerCode	YMAccount	YooMoney account number used for payment.
paymentType	normalizedString	Payment method for order. Payment method codes
Required parameters for B2B payments (paymentType=2S)
payment_purpose	string	Payment purpose.
vatType	string	Type of VAT. Possible values: `calculated` — taxable, all products have the same rate; `untaxed` — non-taxable; `mixed` — products in the payment are taxed differently.
vatRate	string	VAT rate. Required if `vatType=calculated`. Possible values: `0` — 0% VAT rate; `7` — 7% VAT rate; `10` — 10% VAT rate; `18` — 18% VAT rate; `20` — 20% VAT rate.
vatSum	CurrencyAmount	The VAT amount you sent in the payment form. Shown if `vatType=calculated` or `vatType=mixed`.
Any names other than those listed above	string	Parameters added to the payment form by the merchant.

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).

Request 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 (example):

requestDatetime: 2011-05-04T20:38:00.000+04:00
action: checkOrder
md5: 8256D2A032A35709EAF156270C9EFE2E
shopId: 13
shopArticleId: 456
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 store"/>
</checkOrderRequest>

Response

Response parameters

Parameter	Type	Description
performedDatetime	dateTime	Time in YooMoney 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	YooMoney 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	`md5` parameter does not match result of calculating hash function. Fatal error.
100	Refused to accept transfer	Refusal to accept the transfer with the specified parameters. Fatal error.
200	Request parsing error	Merchant is not able to parse request. Fatal error.

Response examples

Response example for successful processing

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

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