HTTP-уведомления о переводах

Attention. Это старая версия API. Переходите на API Яндекс.Кассы.

Безопасность

При подключении по HTTP-схеме вы определяете адреса, по которым будут приходить HTTP-уведомления от Яндекс.Кассы

Для защищенного взаимодействия магазина и Яндекс.Кассы можно использовать два варианта:

  • MD5 — базовый вариант, подключен по умолчанию.
  • PKCS#7 — альтернатива md5 с высоким уровнем безопасности.

О подключении PKCS#7 вы можете узнать у менеджера Кассы.

Restriction.

Для передачи запросов Уведомление об отмене заказа (cancelOrder) используется только вариант с MD5, взаимодействие осуществляется по HTTPS.

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

Формат запроса с использованием контрольной суммы MD5

Запросы передаются по протоколу HTTP 1.1 методом POST.

Формат передачи параметров в запросе:

  • каждый параметр передается в формате {ключ}={значение} в теле POST-запроса;
  • MIME-тип: application/x-www-form-urlencoded;
  • кодировка символов: UTF-8.

В этом варианте Яндекс.Касса добавляет в запросы параметр с именем md5. Его значение — MD5-хэш от строки, собранной из значений параметров этого же запроса вместе с секретным словом. Вы указываете секретное слово при подключении к Кассе — в личном кабинете, в разделе Настройки.

Note.
  • При получении запроса магазину необходимо проверять, что запрос отправлен Яндекс.Кассой и данные в запросе пришли полностью. Для этого магазин проверяет значение параметра md5 . Если значение md5 не совпадает с результатом расчета хэш-функции MD5 от переданных параметров, в обработке запроса нужно отказывать.

  • Рекомендуем дополнительно проверить IP-адрес отправителя запроса. Список IP Яндекс.Кассы вы можете запросить у менеджера.

MD5-хэширование применяется к тексту, который формируется как последовательность значений ряда параметров запроса, разделенных символом «точка с запятой» (;). Результат хэширования приводится к верхнему регистру.

Note.

Проверьте, что в значении customerNumber нет пробелов в конце или в начале.

Порядок следования параметров:

action;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;shopId;invoiceId;customerNumber;shopPassword

Пример:

Исходная строка

Результат хеширования

checkOrder;87.10;643;1001;13;55;8123294469;s<kY23653f,{9fcnshwq

1B35ABE38AA54F2931B0C58646FD1321

Исходная строка

Результат хеширования

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 .

Особенности к риптоконтейнера:

  • содержит АСП (цифровую подпись, аналог собственноручной подписи);
  • содержит конечный сертификат Яндекс.Денег;
  • не содержит цепочки центров сертификации;
  • закодирован в формате PEM (OpenSSL);
  • компрессия данных не используется;
  • шифрование не используется;
  • сертификат, используемый при изготовлении криптопакета, соответствует стандарту X.509 Version 3.

Tip.

Проверяйте подпись криптоконтейнера. Если данные в документе и данные подписи не совпадают, отвечайте на запрос отказом, а сами криптосообщения сохраните, чтобы предъявить в случае разногласий.

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

Формат ответа

Результат выполнения запроса магазин возвращает в виде XML-документа в теле ответа на HTTP-запрос.

Документ формируется по стандарту XML 1.0 (Fifth Edition):

  • имена элементов и атрибутов чувствительны к регистру;
  • MIME-тип: application/xml;
  • кодировка символов: UTF-8.

Правила обработки HTTP-уведомлений

  1. Для отправки запроса Яндекс.Касса пытается подключиться к вашему серверу в течение 5 секунд.
  2. Если Яндекс.Кассе удалось установить соединение и отправить запрос, она ожидает ответ в течение 10 секунд.
  3. Если на запрос Проверка заказа не удалось получить ответ Успешно (в том числе если не удалось подключиться к серверу), Яндекс.Касса сообщает пользователю, что заплатить невозможно.
  4. При длительном многократном отсутствии ответа на запрос Уведомление о переводе или Уведомление об отмене заказа (либо при многократных технических ошибках) Яндекс.Касса будет пытаться доставить уведомление в течение суток. Первый раз — через минуту, а потом еще до пяти раз с интервалом 5-30 минут. После этого платеж будет переведен в окончательный статус, по умолчанию — неуспешный.
  5. Каждому переводу присваивается уникальный номер (invoiceId). Запрос Уведомление о переводе для одного и того же invoiceId может приходить несколько раз (из-за проблем со связью или ошибок в ответе на этот запрос). На повторные уведомления необходимо отвечать успехом (code="0").

Список запросов

Запрос проверки параметров платежа

Запрос уведомления об успешном платеже