HTTP notifications about payments — [Archive] Payment solution protocol for merchants

HTTP notifications about payments

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

Security

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

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

MD5 — the basic option, enabled by default.
PKCS#7 — a highly secure alternative to MD5.

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

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, YooMoney 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 YooMoney (in the Settings section of your personal dashboard).

Additional recommendations:

When a request is received, the merchant must verify that the request was sent by YooMoney 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 YooMoney 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.

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: checkOrder; 87.10; 643; 1001; 13; 55; 8123294469; skY23653f, {9fcnshwq
Hash result: 39CFB94FBE6EBD9F1D347C4B62EE32B6

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

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

To send a request, YooMoney will make a 5-second attempt to connect to your server.
If YooMoney is unable to connect and send the request, it will be waiting for a response within 10 seconds.
If the Order verification request doesn’t return a successful response (including failure to connect to the server), YooMoney informs the user that the payment can’t be completed.
If a response is repeatedly not received over a prolonged period for a Payment notification or Order verification (or if repeated technical errors occur), YooMoney 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.
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").