HTTP notifications about payments

Security

If you use the HTTP activation method, you determine which addresses will receive HTTP notifications from Yandex.Checkout.

There are two options to choose from for sending secure communications between a merchant and Yandex.Checkout:

  • MD5 - The basic option, enabled by default.
  • PKCS#7 - A highly secure alternative to MD5.

To find out about enabling PKCS#7, contact a Yandex.Checkout manager.

Restriction. 

For sending Payment cancellation notification (cancelOrder) requests, only the MD5 option is used. Interaction occurs over HTTPS.

Interaction format

Request format using an MD5 checksum

Requests are send over the HTTP 1.1 protocol using the POST method.

Format for passing parameters in the request:

  • Each parameter is passed in {key}={value} format in the body of the POST request.
  • MIME type: application/x-www-form-urlencoded.
  • Encoding: UTF-8.

For this option, Yandex.Checkout adds a parameter with the md5 name to requests. Its value is the MD5 hash of a string constructed from the parameter values of this request, together with the secret word. You enter the secret word when you activate Yandex.Checkout (in the Settings section of your personal dashboard).

Note. 
  • When a request is received, the merchant must verify that the request was sent by Yandex.Checkout and that the data in the request is complete. To do this, the merchant checks the value of the md5 parameter. If the md5 value doesn't match the calculated MD5 hash function from the passed parameters, the request should be declined.

  • We recommend also checking the IP address of the request sender. You can request a list of Yandex.Checkout IP addresses from the manager.

MD5 hashing is applied to a text that is formed as a sequence of values for a set of request parameters separated by semicolons (;). The hash result is converted to uppercase.

Note. 

Make sure the customerNumber value doesn't have any spaces at the beginning or at the end.

Order of parameters:

action;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;shopId;invoiceId;customerNumber;shopPassword

Example:

Source string

Hash result

checkOrder;87.10;643;1001;13;55;8123294469;s<kY23653f,{9fcnshwq

1B35ABE38AA54F2931B0C58646FD1321

PKCS#7 request format

Requests are send over the HTTP 1.1 protocol using the POST method.

Format for passing parameters in the request:

  • MIME type: application/pkcs7-mime.
  • Encoding: UTF-8.
  • Parameters are passed as an XML document conforming to XML 1.0 (Fifth Edition).
  • The generated document is put in a PKCS#7 cryptographic message container.

Features of the cryptographic message container:

  • Contains a digital signature (equivalent to a handwritten signature).
  • Contains the Yandex.Money certificate.
  • Doesn't contain a chain of certificate centers.
  • Encoded in PEM format (OpenSSL).
  • Doesn't use data compression.
  • Doesn't use encryption.
  • The certificate used for preparing the cryptographic message conforms to X.509 Version 3.

Tip. 

Check the signature of the cryptographic message container. If the data in the document and the data in the signature don't match, refuse the request, but save the cryptographic messages to present in case of a dispute.

To get the certificate for verifying the signature of a cryptographic message container, contact the manager or specialist who is activating the store.

Response format

The merchant returns the result of executing the request as an XML document in the body of the response to the HTTP request.

The document is formed according to the XML 1.0 (Fifth Edition) standard:

  • The names of elements and attributes are case-sensitive.
  • MIME type: application/xml.
  • Encoding: UTF-8.

Rules for processing HTTP notifications

  1. Responses to Yandex.Checkout requests must occur within 10 seconds.

  2. If there is no response to the Order verification request (or if the response is anything other than Successful), Yandex.Money informs the user that the payment can't be completed.

  3. If a response is repeatedly not received over a prolonged period for a Payment notification or Payment cancellation notification (or if repeated technical errors occur), Yandex.Checkout will continue trying to deliver the notification over the next 24 hours. The first attempt is after one minute, with up to five subsequent attempts at intervals from 5 to 30 minutes. After this, the payment is switched to the final status, which is "unsuccessful" by default.

  4. Each transfer is assigned a unique number (invoiceId). A Payment notification request may be delivered multiple times for the same invoiceId (due to connection issues or errors in the response to this request). Repeat notifications must be responded to with success (code="0").

List of requests

Request to check payment parameters

Request for notification of successful payment