Протокол приема платежей для магазинов

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

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

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

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

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

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

Ограничение. 

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

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

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

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

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

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

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

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

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

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 .

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

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

Совет. 

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

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

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

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

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

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

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

  1. На запросы Яндекс.Кассы необходимо отвечать в течение 10 секунд.

  2. При отсутствии ответа на запрос Проверка заказа (или при любом ответе, кроме Успешно) Яндекс.Касса сообщает пользователю, что заплатить невозможно.

  3. При длительном многократном отсутствии ответа на запрос Уведомление о переводе или Уведомление об отмене заказа (либо при многократных технических ошибках) Яндекс.Касса будет пытаться доставить уведомление в течение суток. Первый раз — через минуту, а потом еще до пяти раз с интервалом 5-30 минут. После этого платеж будет переведен в окончательный статус, по умолчанию - неуспешный.

  4. Каждому переводу присваивается уникальный номер (invoiceId). Запрос Уведомление о переводе для одного и того же invoiceId может приходить несколько раз (из-за проблем со связью или ошибок в ответе на этот запрос). На повторные уведомления необходимо отвечать успехом (code="0").

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

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

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