API ЮKassa
Помощь
Подключить ЮKassa
HTTP-уведомления о переводах
Безопасность
При подключении по HTTP-схеме вы определяете адреса, по которым будут приходить HTTP-уведомления от ЮKassa
Для защищенного взаимодействия магазина и ЮKassa можно использовать два варианта:
  • MD5 — базовый вариант, подключен по умолчанию.
  • PKCS#7 — альтернатива md5 с высоким уровнем безопасности.
О подключении PKCS#7 вы можете узнать у менеджера ЮKassa.
Формат взаимодействия
Формат запроса с использованием контрольной суммы MD5
Запросы передаются по протоколу 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
Формат запроса PKCS#7
Запросы передаются по протоколу 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.
Правила обработки HTTP-уведомлений
  1. Для отправки запроса ЮKassa пытается подключиться к вашему серверу в течение 5 секунд.
  2. Если ЮKassa удалось установить соединение и отправить запрос, она ожидает ответ в течение 10 секунд.
  3. Если на запрос Проверка заказа не удалось получить ответ Успешно (в том числе если не удалось подключиться к серверу), ЮKassa сообщает пользователю, что заплатить невозможно.
  4. При длительном многократном отсутствии ответа на запрос Уведомление о переводе или Проверка заказа (либо при многократных технических ошибках) ЮKassa будет пытаться доставить уведомление в течение суток. Первый раз — через минуту, а потом еще до пяти раз с интервалом 5-30 минут. После этого платеж будет переведен в окончательный статус, по умолчанию — неуспешный.
  5. Каждому переводу присваивается уникальный номер (invoiceId). Запрос Уведомление о переводе для одного и того же invoiceId может приходить несколько раз (из-за проблем со связью или ошибок в ответе на этот запрос). На повторные уведомления необходимо отвечать успехом (code="0").
Что почитать еще
Уведомление о проверке заказаУведомление о переводе