Формат взаимодействия

Формирование запроса

Для подключения к сервису Яндекс.Денег и отправки запросов необходим специальный сертификат (подробнее о Процедуре обмена сертификатами).

Система контрагента и сервер Яндекс.Денег взаимодействуют по протоколу HTTPS. Для выполнения каждой операции контрагент передает отдельный HTTP-запрос, содержащий криптопакет формата PKCS#7. На каждый запрос о зачислении Яндекс.Деньги отвечают сообщением о результате операции, помещенным в криптопакет PKCS#7.

Также используется криптографическая защита канала связи на базе протокола SSL (HTTPS) с аутентификацией по клиентскому сертификату. Кроме того, ограничивается список IP-адресов, с которых допустимо присылать запросы на сервер Яндекс.Денег.

Формирование запроса к серверу состоит из нескольких шагов.

Шаг 1. Распоряжение на исполнение операции

Распоряжение формируется как документ по стандарту XML 1.0 (Fifth Edition) в кодировке UTF-8 по соответствующему стандарту.

Адрес сервера для вызова операции

Тестовый сервер: https://bo-demo02.yamoney.ru:9094/

Реальный сервер: https://calypso.yamoney.ru:9094/

Шаг 2. Формирование криптопакета

Сформированный документ помещается в криптоконтейнер формата PKCS#7 по стандарту CMS. Криптоконтейнер должен содержать АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не должен содержать цепочки сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет должен быть закодирован в формате PEM (OpenSSL). Сертификат контрагента, который используется при изготовлении криптопакета, должен соответствовать стандарту X.509 Version 3.

Шаг 3. Передача запроса на сервер Яндекс.Денег

Система контрагента формирует POST-запрос по протоколу HTTP/1.1 (см. HTTP/1.1, HTTP Over TLS, TLS). Криптопакет можно передавать одним из двух способов:

  • Криптопакет помещается в тело POST-запроса, MIME-тип: application/pkcs7-mime.
  • Криптопакет передается как multipart/form-data вложение. MIME-тип: application/pkcs7-mime. POST-запрос должен иметь только один 'part', криптопакет должен быть вложен как файл. Такой запрос может быть отправлен из стандартной HTML-формы для отправки файла на сервер (file upload, см. multipart/form-data).

Для авторизации запросов сервер Яндекс.Денег проверяет АСП криптопакета.

Note.

Чтобы зачисления случайно не повторялись, каждой операции присваивается уникальный номер (clientOrderId).

Пример сформированного запроса
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-----

Получение ответа

Результат выполнения запроса возвращается Яндекс.Деньгами в ответе на HTTP-запрос. MIME-тип: application/pkcs7-mime. Данные помещаются в криптоконтейнер формата PKCS#7. Криптоконтейнер содержит АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не содержит цепочки сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет закодирован в формате PEM (OpenSSL). Криптоконтейнер содержит XML-документ с результатом обработки запроса.

При получении ответа сервера система контрагента выполняет проверку подписи ответа, чтобы убедиться, что ответ отправлен сервером Яндекс.Денег и его содержимое не было изменено третьей стороной. Следует учитывать, что в ответе могут быть дополнительные поля, не описанные в данном протоколе, но не нарушающие совместимость.

Смотрите также

HTTP-коды ответа