При подключении по HTTP-схеме вы определяете адреса, по которым будут приходить HTTP-уведомления от ЮKassa
Для защищенного взаимодействия магазина и ЮKassa можно использовать два варианта:
- MD5 — базовый вариант, подключен по умолчанию.
- PKCS#7 — альтернатива md5 с высоким уровнем безопасности.
О подключении PKCS#7 вы можете узнать у менеджера ЮKassa.
Запросы передаются по протоколу HTTP 1.1 методом POST.
Формат передачи параметров в запросе:
- каждый параметр передается в формате
{ключ}={значение}в теле POST-запроса; - MIME-тип:
application/x-www-form-urlencoded; - кодировка символов: UTF‑8.
В этом варианте ЮKassa добавляет в запросы параметр с именем
md5. Его значение — MD5-хэш от строки, собранной из значений параметров этого же запроса вместе с секретным словом. Вы указываете секретное слово при подключении к ЮKassa — в личном кабинете, в разделе Настройки.Дополнительные рекомендации:
- При получении запроса магазину необходимо проверять, что запрос отправлен ЮKassa и данные в запросе пришли полностью. Для этого магазин проверяет значение параметра
md5. Если значениеmd5не совпадает с результатом расчета хэш-функции MD5 от переданных параметров, в обработке запроса нужно отказывать. - Рекомендуем дополнительно проверить IP-адрес отправителя запроса. Список IP ЮKassa вы можете запросить у менеджера.
MD5-хэширование применяется к тексту, который формируется как последовательность значений ряда параметров запроса, разделенных символом «точка с запятой» (;). Результат хэширования приводится к верхнему регистру.
Порядок следования параметров:
action;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;shopId;invoiceId;customerNumber;shopPassword
Пример:
- Исходная строка:
checkOrder;87.10;643;1001;13;55;8123294469;skY23653f,{9fcnshwq - Результат хеширования:
39CFB94FBE6EBD9F1D347C4B62EE32B6
Запросы передаются по протоколу HTTP 1.1 методом POST.
Формат передачи параметров в запросе:
- MIME-тип:
application/pkcs7-mime; - кодировка символов: UTF‑8;
- параметры передаются в виде XML-документа по стандарту XML 1.0 (Fifth Edition);
- сформированный документ помещается в криптоконтейнер формата PKCS#7.
Особенности криптоконтейнера:
- содержит АСП (цифровую подпись, аналог собственноручной подписи);
- содержит конечный сертификат ЮKassa;
- не содержит цепочки центров сертификации;
- закодирован в формате PEM (OpenSSL);
- компрессия данных не используется;
- шифрование не используется;
- сертификат, используемый при изготовлении криптопакета, соответствует стандарту X.509 Version 3.
Результат выполнения запроса магазин возвращает в виде XML-документа в теле ответа на HTTP-запрос.
Документ формируется по стандарту XML 1.0 (Fifth Edition):
- имена элементов и атрибутов чувствительны к регистру;
- MIME-тип:
application/xml; - кодировка символов: UTF‑8.
- Для отправки запроса ЮKassa пытается подключиться к вашему серверу в течение 5 секунд.
- Если ЮKassa удалось установить соединение и отправить запрос, она ожидает ответ в течение 10 секунд.
- Если на запрос Проверка заказа не удалось получить ответ Успешно (в том числе если не удалось подключиться к серверу), ЮKassa сообщает пользователю, что заплатить невозможно.
- При длительном многократном отсутствии ответа на запрос Уведомление о переводе или Проверка заказа (либо при многократных технических ошибках) ЮKassa будет пытаться доставить уведомление в течение суток. Первый раз — через минуту, а потом еще до пяти раз с интервалом 5-30 минут. После этого платеж будет переведен в окончательный статус, по умолчанию — неуспешный.
- Каждому переводу присваивается уникальный номер (
invoiceId). Запрос Уведомление о переводе для одного и того жеinvoiceIdможет приходить несколько раз (из-за проблем со связью или ошибок в ответе на этот запрос). На повторные уведомления необходимо отвечать успехом (code="0").