Формат взаимодействия
 
Формирование запроса
Для подключения к сервису ЮKassa и отправки запросов необходим специальный сертификат (подробнее о Взаимодействии по SSL).
Система контрагента и сервер ЮKassa взаимодействуют по протоколу HTTPS. Для выполнения каждой операции контрагент передает отдельный HTTP-запрос, содержащий криптопакет формата PKCS#7. На каждый запрос о зачислении ЮKassa отвечают сообщением о результате операции, помещенным в криптопакет PKCS#7.
Также используется криптографическая защита канала связи на базе протокола SSL (HTTPS) с аутентификацией по клиентскому сертификату. Кроме того, ограничивается список IP‑адресов, с которых допустимо присылать запросы на сервер ЮKassa.
Формирование запроса к серверу состоит из нескольких шагов.
 
Шаг 1. Распоряжение на исполнение операции
Распоряжение формируется как документ по стандарту XML 1.0 (Fifth Edition) в кодировке UTF‑8 по соответствующему стандарту.
Адрес сервера для вызова операции
https://payouts.yookassa.ru:9094
 
Шаг 2. Формирование криптопакета
Сформированный документ помещается в криптоконтейнер формата PKCS#7 по стандарту CMS. Криптоконтейнер должен содержать АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не должен содержать цепочки сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет должен быть закодирован в формате PEM (OpenSSL). Сертификат контрагента, который используется при изготовлении криптопакета, должен соответствовать стандарту X.509 Version 3.
 
Шаг 3. Передача запроса на сервер ЮKassa
Система контрагента формирует 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).
Для авторизации запросов сервер ЮKassa проверяет АСП криптопакета.
Чтобы зачисления случайно не повторялись, каждой операции присваивается уникальный номер (
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-----
 
Получение ответа
Результат выполнения запроса возвращается ЮKassa в ответе на HTTP-запрос. MIME-тип:
application/pkcs7-mime
. Данные помещаются в криптоконтейнер формата PKCS#7. Криптоконтейнер содержит АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не содержит цепочки сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет закодирован в формате PEM (OpenSSL). Криптоконтейнер содержит XML-документ с результатом обработки запроса.
При получении ответа сервера система контрагента выполняет проверку подписи ответа, чтобы убедиться, что ответ отправлен сервером ЮKassa и его содержимое не было изменено третьей стороной. Следует учитывать, что в ответе могут быть дополнительные поля, не описанные в данном протоколе, но не нарушающие совместимость.
 
Что почитать еще
HTTP-коды ответаВзаимодействие по SSLЗачисление переводов