Interaction over SSL

An SSL certificate is needed in two cases: for protecting user data (when using Yandex.Checkout), and for authenticating connections with Yandex.Money servers.

1. Certificate for protecting users' personal data

This type of certificate is required when activating Yandex.Checkout for any store with payment notifications over HTTP (the CMS module or HTTP protocol activation methods). Its purpose is to ensure that user data is transmitted in encrypted form. For this purpose, any ready-made domain certificate will work. You can get one for free when activating Yandex.Checkout, or buy one from any official authentication center. A self-signed certificate is also acceptable.

Tip. 

You shouldn't use SSL with SNI (Server Name Identification) support.

2. For authenticating connections with Yandex.Money servers

This type of certificate is required for using Yandex.Money protocols to perform financial transactions within the payment management protocol (MWS): returns, deferred payments, and others. It is also needed for using the protocol for mass disbursements and transfers to wallets. For these purposes, only a special SSL certificate issued by the NBCO Yandex.Money LLC certificate authority (NBCO YM Root) is acceptable.

If you aren't sure whether you need to get a certificate, or which kind to get, ask your Yandex.Money manager.

Getting an SSL certificate for interacting with Yandex.Money servers

To get a certificate, create a certificate request (in *.csr format), fill in the certificate request application form, and email the request and certificate application to your Yandex.Money manager.

Tip. 

To generate a certificate request in *.csr format, use OpenSSL.

1. Creating a private key

Run the command:

openssl genrsa -aes256 -out private.key 2048

Enter the password and confirm. For example:

Enter pass phrase for private.key: 12345
Verifying - Enter pass phrase for private.key: 12345

A private.key file will be created in the directory where the command was run.

Tip. 

This is confidential information. Maintain the secrecy of the private key. The file with the private key is encrypted and password protected.

2. Creating a CSR request for a certificate

Run the command:

openssl req -new -key private.key -out request.csr

Enter the required parameter for the certificate request. Only use Latin characters.

Tip. 

When creating a CSR request in Windows, the command should specify the path to the OpenSSL configuration file. To do this, add -config "{path}" -out to the command. Command example:

req -new -key private.key -config "C:\openssl-WIN32\openssl.cnf" -out request.csr

Example of filling in certificate request parameters

Parameter

Value

Note
Country Name (2 letter code) [AU]: RU Required
State or Province Name (full name): Russia Required
Locality Name (eg, city): []: Moscow Optional
Organization Name (eg, company) [Internet Widgits Pty Ltd]: OOO Predpriyatie Enter the required parameter for the certificate request. Only use Latin characters.
Organizational Unit Name (eg, section) []: Optional
Common Name (eg, YOUR name) []: /business/predpriyatie

Required.

/business/ — Required part of this parameter that shouldn't be changed. It can be followed by any Latin letters without spaces. For example, the name of your company in Latin letters.

Email Address: predpriyatie@yandex.ru

Required

The request.csr file will be created in the directory where the command was run.

3. Getting a digital signature for the certificate request application

You need a digital signature to fill in the certificate request application, as it is contained in the certificate file.

To get a digital signature, run the command:

openssl req -in request.csr -noout -text

The text representation of the digital signature is the part of the response after the string Signature Algorithm: sha1WithRSAEncryption. For example:

Signature Algorithm: sha1WithRSAEncryption
5b:67:42:8c:5a:a7:bc:bf:05:99:77:39:2e:e7:e7:5d:8e:47:
09:e9:5a:46:62:3c:b1:63:2a:de:06:26:54:a4:12:b4:17:b2:
ca:ff:f4:3f:c0:09:ee:7a:88:5b:b9:f5:04:cb:24:bd:5f:bd:
3b:f7:38:54:71:1c:fe:98:17:66:ae:72:2d:8a:31:34:94:30:
58:ad:79:60:e5:ca:24:83:8b:c7:96:11:c6:d9:c9:6e:7a:b0:
83:20:96:96:08:72:38:3e:24:dc:30:35:f7:85:f4:d3:21:62:
13:44:1f:49:2a:d3:c2:73:2d:3b:fc:07:3f:20:8e:d3:c1:c8:
4c:3b:69:a3:24:56:1e:5c:9c:2f:eb:83:97:80:8b:25:5d:6a:
63:80:59:24:c0:1a:b5:ed:9f:fa:b9:6d:38:dc:6b:ff:29:9e:
24:b7:95:07:37:a9:71:90:ad:b7:51:d6:0e:62:82:5d:39:8a:
f2:4a:06:db:5e:2c:ae:4f:c8:76:2b:ee:e9:13:04:e3:72:c8:
6b:26:61:6c:aa:07:c1:3f:3c:b0:92:b0:29:5f:74:14:7c:34:
77:c8:c6:7a:2f:33:55:c5:0f:1d:e0:b7:8a:d9:84:d7:78:fb:
59:22:e0:58:49:97:16:f2:77:58:8b:8a:af:f2:af:43:b1:fa:
27:58:e1:c2
4. Filling in the certificate application

Download the certificate application, fill it in, and print it. Sign it and stamp your seal on it. Scan it.

ParameterDescription
CNMust match the value of the Common Name parameter (i.e. YOUR name). For example, /business/predpriyatie.
Digital signature of the certificate requestThe text representation received during the previous step.
Name of the organization in Latin lettersMust match the value of the Organization Name parameter (i.e. company), such as [Internet Widgits Pty Ltd].
Reason for request

Possible reasons:

  • Initial — for obtaining the first certificate.
  • Planned replacement — to replace a certificate that has expired.
  • Replacement — for replacing a previously issued certificate after a security breach.
  • Adding server — for using a new certificate on additional servers or services.
Contact personContact information for a specialist in case questions arise about the issued certificate.
Email addressAddress to send the issued certificate to.

5. Sending the request and application for a certificate to Yandex.Money

Email the certificate request file (request.csr) and scanned application to your Yandex.Money manager.

The certificate will be issued within 2 business days.

6. Installing the certificate

In response to the request, your manager from Yandex.Money will send a file with the certificate. The certificate is valid for 1 year.

What to do next:

  1. Place the certificate on your server.
  2. Add the path to the certificate in the configurations of the scripts that interact with Yandex.Money.
  3. If verify the end server certificate, download the certification chain (certificates of the NBCO YM Root and NBCO YM Int certificate authorities) and add them to the list of trusted root and intermediate certificate authorities in your system.
Tip. 

If necessary, you can store a "private key"—"certificate" pair in a single encrypted PKCS#12 file. To make a file like this, use the command:

openssl pkcs12 -export -in username.crt -inkey private.key -out username.p12

For more information about installing the certificate, contact the activation manager.

Using SSL certificates

You need to:
  • Use the CA chain to check the authenticity of the Yandex.Money servers, and do not establish a connection if verification was not successful.
  • Use your private key and certificate when establishing connections to Yandex.Money servers.
  • Maintain the confidentiality of the private key.
  • Keep track of the certificate's expiration date.
Tip. 
  • We additionally recommend cross-checking the Yandex.Money server certificates against the list of revoked certificates (Certificate Revocation List, CRL).
  • We recommend that each service that needs to access the Yandex.Money servers get its own certificate. But one certificate can be used for all services.

If the private key is compromised, you must inform the Yandex.Money manager.

If the certificate expires or it will be compromised, you can get a new one.