HTTP-уведомления о переводах
Это старая версия API. Переходите на API ЮKassa.
 
Безопасность
При подключении по 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-хэширование применяется к тексту, который формируется как последовательность значений ряда параметров запроса, разделенных символом «точка с запятой» (;). Результат хэширования приводится к верхнему регистру.
Проверьте, что в значении
customerNumber
нет пробелов в конце или в начале.
Порядок следования параметров:
action;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;shopId;invoiceId;customerNumber;shopPassword
Пример:
  • Исходная строка:
    checkOrder;87.10;643;1001;13;55;8123294469;s<kY23653f,{9fcnshwq
  • Результат хеширования:
    1B35ABE38AA54F2931B0C58646FD1321
 
Формат запроса 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"
    ).
 
Что почитать еще
Уведомление о проверке заказаУведомление о переводе