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:
|
vatRate | string | VAT rate. Required if vatType=calculated .Possible values:
|
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" />