Interaction format — Protocol for deposits to YooMoney wallets

Interaction format

Forming a request

To active the YooMoney service and send requests, you need a special certificate (for more information, see the Interaction over SSL).

The Counterparty’s system and the YooMoney server interact over the HTTPS protocol. For each operation, the Counterparty sends a separate HTTP request containing a PKCS#7 cryptographic message. YooMoney responds to each request for deposit with a message about the result of the operation included in the PKCS#7 cryptographic message.

The communication channel is also cryptographically secured using the SSL (HTTPS) protocol with client certificate authentication.

Forming a request to the server includes several steps.

Step 1. Request to execute an operation

The request is formed as an XML 1.0 (Fifth Edition) document in UTF‑8 encoding in conformance with the standard.

Server address for calling operations

https://deposit.yoomoney.ru:9094

Step 2. Making the cryptographic message

The prepared document is placed in a PKCS#7 cryptographic message container according to the CMS standard. The cryptographic message container must contain a digital signature (equivalent to a handwritten signature). The cryptographic message container must not contain certificate authority chains. Data compression is not used. Encryption is not used. The cryptographic message must be encoded in PEM format (OpenSSL). The certificate of the Counterparty that is used for preparing the cryptographic message must conform to the X.509 Version 3.

Step 3. Sending the request to the YooMoney server

The counterparty’s system generates a POST request over the HTTP/1.1 Protocol (see HTTP/1.1, HTTP Over TLS, TLS). The cryptographic message can be passed in one of two ways:

The cryptographic message is placed in the body of a POST request with the MIME type: application/pkcs7-mime.
The cryptographic message is passed as a multipart/form-data attachment. MIME-type: application/pkcs7-mime. POST request must have just one 'part' and the cryptographic message must be attached as a file. Such a request can be sent from a standard HTML form for sending a file to the server (file upload, see multipart/form-data).

To authorize requests to the server, YooMoney verifies the digital signature on the cryptographic message.

To avoid repeating deposits accidentally, each operation is assigned a unique number (clientOrderId).

Example of a formed request

POST /webservice/deposition/api/makeDeposition HTTP/1.1
Content-Type: application/pkcs7-mime
Content-Length: 572

-----BEGIN PKCS7-----
MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCA
JIAEDEhlbGxvIFdvcmxkIQAAAAAAADGCAS8wggErAgEBMCowJTEWMBQGA1UECgwN
Qm91bmN5IENhc3RsZTELMAkGA1UEBhMCQVUCAQIwCQYFKw4DAhoFAKBdMBgGCSqG
SIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTEwMDgwNjE1MzE0
M1owIwYJKoZIhvcNAQkEMRYEFC73veYIzlQE6X1fBC+V+J8cIyhxMA0GCSqGSIb3
DQEBAQUABIGAEgIfi0XDEZwbdC8i0I5EPUnFe1PUnBMiRs3heYxdK+oXaG6v3axO
Zr+VNG3tnW1W8M2xWtOcM4PdSTwx98WR1mWN8XDb2Wl9HiG6CGbmE7k4TgcDKhcg
iZmLV+7anBv302qTprTbKY9vChaaVwclSdQBkjPvxhlPnpBM0C9YdYQAAAAAAAA=
-----END PKCS7-----

Receiving the response

The result of request execution is returned by YooMoney in the response to the HTTP request. MIME type: application/pkcs7-mime. Data is placed in a PKCS#7 cryptographic message container. The cryptographic message container contains a digital signature (equivalent to a handwritten signature). The cryptographic message container does not contain certificate authority chains. Data compression is not used. Encryption is not used. The cryptographic message is encoded in PEM format (OpenSSL). The cryptographic message container contains an XML document with the result of request processing.

When receiving the server response, the Counterparty’s system checks the signature on the response to verify that the response was sent by the YooMoney server and its content was not altered by a third party. Note that the response may include additional fields not described in this protocol that do not interfere with compatibility.