Приложение № 2. Протокол обмена информацией при осуществлении переводов: HTTP- и email-уведомления

 
Эта страница больше не поддерживается. Новый Протокол приема платежей для магазинов.
 
Протокол 3.0.1, редакция от 09.06.2015
 

1. Общие сведения

1.1. Назначение документа
Данный документ описывает взаимодействие ООО НКО ‘Яндекс.Деньги’ (далее — Оператор, Яндекс.Деньги) с информационной системой (далее — ИС) Контрагента, необходимое для уведомления Контрагента о совершенном в его пользу переводе (далее также — платеж) в режиме реального времени.
Оператор обеспечивает прием платежей, осуществляемых различными способами: с банковских карт, из электронных кошельков (в том числе со счетов Яндекс.Денег), наличными через терминалы, со счетов мобильных телефонов. Перечень способов, доступный конкретному Контрагенту, зависит от условий договора и дополнительно контролируется настройками на стороне Оператора.
Упрощенно процесс взаимодействия можно представить в виде нескольких последовательных действий:
1. Передача Оператору данных о заказе и способе его оплаты (осуществляется с помощью браузера плательщика).
2. Уведомление Контрагента о платеже (осуществляется Оператором, возможна отправка HTTP- или email-уведомлений).
3. Формирование реестра принятых в пользу Контрагента переводов (пересылается Оператором по электронной почте).
4. Перечисление денежных средств на банковский счет Контрагента.
5. При необходимости — возврат успешных платежей плательщикам по инициативе Контрагента.
Пп. 1–3 описаны далее по тексту, пп. 4–5 выходят за рамки данного документа. Для работы с возвратами Контрагенту дополнительно потребуется выпустить сертификат и реализовать протокол Merchant Web Services (MWS). Процедура обмена сертификатами и протокол MWS описаны в отдельных документах.
1.2. Подключение Контрагента
Контрагенту доступны две схемы подключения к Яндекс.Деньгам:
  • схема с отправкой уведомлений о платежах в адрес Контрагента посредством вызовов по протоколу HTTP (далее — HTTP-схема, подробное описание взаимодействия представлено в разделе 4 ‘HTTP-уведомления о переводах’);
  • схема с отправкой уведомлений о платежах в адрес Контрагента по электронной почте (далее — email-схема, подробное описание представлено в разделе 5 ‘Email-уведомления о переводах’).
  • Принципиальное различие в том, что email-схема не предполагает обратной связи, а HTTP-схема позволяет Контрагенту производить онлайн-проверку параметров заказа при оплате. Если Контрагенту необходимо в режиме реального времени демонстрировать плательщику у себя на сайте, что товар или услуга уже оплачены, Контрагент должен использовать HTTP-схему подключения к Яндекс.Деньгам. Схемы не могут использоваться одновременно. Количество доступных способов оплаты от выбранной схемы не зависит.
    В зависимости от схемы Контрагент должен сообщить Оператору параметры подключения: URL'ы (адрес электронной почты) для отправки уведомлений, URL'ы для редиректа плательщика после оплаты, адрес электронной почты для отправки реестров принятых переводов и т.д. (подробная информация — в разделе 6.1 ‘Параметры подключения Контрагента’).
    Оператор в ответ предоставляет настройки для доступа к тестовой среде Яндекс.Денег, а после завершения процедуры отладки — настройки для ‘боевого’ взаимодействия. Подключение к MWS производится отдельно.
     

    2. Обобщенное описание взаимодействия

    0. Контрагент размещает на странице оплаты заказа ‘платежную форму’ с данными заказа и указанием способов оплаты (в ряде случаев возможно размещение ‘платежной формы’ на сайте Оператора: https://money.yandex.ru/shops.xml).
    При HTTP-схеме подключенияПри email-схеме подключения
    1-2. Браузер плательщика передает заполненную форму в ИС Оператора.
    3. На основании полученных данных Оператор определяет способ оплаты и отображает для плательщика страницу подтверждения платежа.
    4. Плательщик вводит дополнительные данные (например, реквизиты банковской карты) и подтверждает платеж.
    5. Перед тем как провести платеж, Оператор отправляет в ИС Контрагента запрос ‘Проверка заказа (checkOrder)’.5. Шаг пропускается.
    6. Контрагент подтверждает корректность заказа либо отказывается от проведения платежа.6. Шаг пропускается.
    7-8. Если ИС Контрагента ответила на запрос ‘Проверка заказа’ положительно, то Оператор списывает деньги с плательщика и отображает для него результат проведения платежа.7-8. Оператор списывает деньги с плательщика и отображает для него результат проведения платежа.
    9. На странице результата отображается ссылка ‘Вернуться в магазин’.
    URL, на который будет перенаправлен плательщик, определяется Контрагентом.
    10-11. По факту успешного прохождения платежа Оператор отправляет ИС Контрагента запрос ‘Уведомление о переводе (paymentAviso)’.10. По факту успешного прохождения платежа Оператор отправляет ИС Контрагента email-уведомление о переводе.
    Обратите внимание: взаимодействие Оператора и Контрагента в случае оплаты заказа способом, отличным от платежа из кошелька Яндекс.Денег и оплаты с произвольной банковской карты, имеет ряд особенностей. Описания таких сценариев приведены в разделе 6 «Приложения».
    Раз в сутки Оператор отправляет Контрагенту по электронной почте реестр принятых переводов. Контрагент должен сверять список успешных платежей по данным своей ИС со списком операций из реестра и сообщать Оператору о расхождениях. Формат реестра описан в разделе 6.5 «Реестры принятых переводов».
     

    3. Платежная форма

    Платежная форма размещается Контрагентом на странице оплаты, определяет параметры заказа и способ платежа. Отправка через браузер плательщика платежной формы по стандартному адресу (https://money.yandex.ru/eshop.xml) инициирует на стороне Оператора формирование и обработку распоряжения на перевод.
    Пример платежной формы:
    <!-- Значения всех полей условны и приведены исключительно для примера -->
    <form action="https://money.yandex.ru/eshop.xml" method="post">
     
    <!-- Обязательные поля -->
    <input name="shopId" value="1234" type="hidden"/>
    <input name="scid" value="4321" type="hidden"/>
    <input name="sum" value="100.50" type="hidden">
    <input name="customerNumber" value="abc000" type="hidden"/>
     
    <!-- Необязательные поля -->
    <input name="shopArticleId" value="567890" type="hidden"/>
    <input name="paymentType" value="AC" type="hidden"/>
    <input name="orderNumber" value="abc1111111" type="hidden"/>
    <input name="cps_phone" value="79110000000" type="hidden"/>
    <input name="cps_email" value="user@domain.com" type="hidden"/>
     
    <input type="submit" value="Заплатить"/>
    </form>
    Для передачи данных о заказе и способе его оплаты нужно использовать параметры из таблицы ниже. Все параметры регистрозависимые.
    Таблица 3.1. Параметры платежной формы
    ПараметрТипОписание
    Служебные параметры:
    shopIdxs:long, обязательныйИдентификатор Контрагента, выдается Оператором.
    shopArticleIdxs:long, необязательныйИдентификатор товара, выдается Оператором. Применяется, если Контрагент использует несколько платежных форм для разных товаров.
    scidxs:long, обязательныйНомер витрины Контрагента, выдается Оператором.
    sumCurrencyAmount, обязательныйСтоимость заказа.
    customerNumberxs:normalizedString, до 64 символов, обязательныйИдентификатор плательщика в ИС Контрагента. В качестве идентификатора может использоваться номер договора плательщика, логин плательщика и т. п. Возможна повторная оплата по одному и тому же идентификатору плательщика.
    orderNumberxs:normalizedString, до 64 символов, необязательныйУникальный номер заказа в ИС Контрагента. Уникальность контролируется Оператором в сочетании с параметром shopId. Если платеж с таким номером заказа уже был успешно проведен, то повторные попытки оплаты будут отвергнуты Оператором.
    shopSuccessURLxs:string, до 250 символов, необязательныйURL, на который нужно отправить плательщика в случае успеха перевода. Используется при выборе соответствующей опции подключения Контрагента (см. раздел 6.1 ‘Параметры подключения Контрагента’).
    shopFailURLxs:string, до 250 символов, необязательныйURL, на который нужно отправить плательщика в случае ошибки оплаты. Используется при выборе соответствующей опции подключения Контрагента.
    cps_emailxs:string, до 100 символов, необязательныйАдрес электронной почты плательщика. Если он передан, то соответствующее поле на странице подтверждения платежа будет предзаполнено (шаг 3 на схеме выше).
    cps_phonexs:string, до 15 символов, только цифры, необязательныйНомер мобильного телефона плательщика. Если он передан, то соответствующее поле на странице подтверждения платежа будет предзаполнено (шаг 3 на схеме выше). Номер телефона используется при оплате наличными через терминалы.
    paymentTypexs:normalizedString, до 5 символов, необязательныйСпособ оплаты. Например:
  • PC — оплата из кошелька в Яндекс.Деньгах;
  • AC — оплата с произвольной банковской карты.

  • Полный список значений см. в таблице 6.6.1.
    Обратите внимание:
  • отсутствие paymentType интерпретируется как оплата из кошелька в Яндекс.Деньгах;
  • если в платежной форме указан способ оплаты, который не разрешен для Контрагента, плательщик не сможет совершить платеж.
  • Параметры, добавляемые Контрагентом:
    Любые названия, отличные от перечисленных вышеxs:string Параметры, добавленные Контрагентом в платежную форму, будут сохранены и переданы ИС Контрагента в запросах ‘Проверка заказа’ и ‘Уведомление о переводе’.
    Суммарная длина всех добавленных Контрагентом параметров не должна превышать 4096 символов.
    Обратите внимание: в email-уведомлениях произвольные параметры Контрагента не передаются. Для передачи дополнительных данных о платеже Контрагент может воспользоваться стандартными параметрами, перечисленными ниже.
    Служебные параметры, используемые в email-уведомлениях о переводе:
    custNamexs:string, необязательныйФИО плательщика.
    custAddrxs:string, необязательныйАдрес доставки товара или адрес проживания плательщика.
    custEMailxs:string, необязательныйАдрес электронной почты плательщика, только для отправки в email-уведомлениях.
    orderDetailsxs:string, необязательныйДетали заказа: список приобретенных товаров, их количество, назначение платежа и т. п.
     

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

    4.1. Формат взаимодействия
    При подключении по HTTP-схеме Контрагент определяет адрес, по которому он будет принимать HTTP-уведомления от Оператора.
    Данные от Оператора передаются в ИС Контрагента посредством вызова по протоколу HTTP/1.1, методом POST. Параметры сообщения упаковываются как набор параметров POST-запроса в виде пар ‘имя=значение’. MIME-тип: application/x-www-form-urlencoded, кодировка символов — UTF-8.
    Параметр ‘md5’ запроса содержит значение хэш-функции от свертки параметров сообщения совместно с секретным словом, указанным Контрагентом при подключении. Контрагенту следует проверять значение параметра ‘md5’ (алгоритм приведен в разделе 4.4 ‘Правила обработки HTTP-уведомлений Контрагентом’) и отказывать в обработке запроса при неуспехе проверки. Успех проверки хэша удостоверяет:
  • факт того, что запрос отправлен Оператором;
  • факт целостности данных запроса.
  • Дополнительно рекомендуется проверять IP-адреса, с которых ИС Контрагента принимает запросы (список IP Оператора можно получить при подключении).
    При взаимодействии ИС Оператора и Контрагента для защиты информации о платежах обязательно соблюдение одного из условий ниже:
    1. передача информации происходит по защищенному каналу (Контрагент использует протокол HTTPS для приема сообщений от Оператора);
    2. сообщения Оператора шифруются перед отправкой(*).
    * Требуется подключение Контрагента по схеме XML/PKCS#7. В этом случае сообщения передаются Оператором в виде XML-документа, вложенного в криптоконтейнер PKCS#7. Данные подписываются SSL-сертификатом Оператора. Для получения подробной информации о схеме подключения XML/PKCS#7 обратитесь к своему менеджеру.
    Результат выполнения запроса Оператора должен быть возвращен Контрагентом в виде XML-документа в теле ответа на HTTP-запрос. Документ формируется согласно стандарту XML 1.0 (Fifth Edition), опубликованному по адресу: http://www.w3.org/TR/xml/. Имена элементов и атрибутов чувствительны к регистру. MIME-тип: application/xml, кодировка символов — UTF-8.
    4.2. Проверка заказа (checkOrder)
    Запрос проверки корректности параметров заказа. Этот шаг позволяет исключить ошибки, которые могли возникнуть при прохождении платежной формы через браузер плательщика.
    В случае успешного ответа Контрагента Оператор предлагает плательщику оплатить заказ и при успехе отправляет Контрагенту ‘Уведомление о переводе’.
    Обратите внимание:
    1. Формирование запроса ‘Проверка заказа’ чаще всего происходит до списания денег со счета плательщика. На этом шаге Контрагент может отказаться от приема перевода.
    2. При оплате с банковской карты авторизация средств по карте производится до формирования запроса ‘Проверка заказа’. В случае отказа Контрагента деньги будут автоматически возращены на карту.
    3. При оплате способами, отличными от платежа из кошелька в Яндекс.Деньгах, внешние системы могут брать дополнительную комиссию. Тогда при отказе Контрагента от приема перевода средства возвращаются плательщику за вычетом такой комиссии.
    4.2.1. Формат запроса Оператора
    Таблица 4.2.1.1. Параметры запроса операции checkOrder
    ПараметрТипОписание
    requestDatetimexs:dateTimeМомент формирования запроса в ИС Оператора.
    actionxs:normalizedString, до 16 символовТип запроса. Значение: ‘checkOrder’ (без кавычек).
    md5xs:normalizedString, ровно 32 шестнадцатеричных символа, в верхнем регистреMD5-хэш параметров платежной формы, правила формирования описаны в разделе 4.4 ‘Правила обработки HTTP-уведомлений Контрагентом’.
    shopIdxs:longИдентификатор Контрагента, присваиваемый Оператором.
    shopArticleIdxs:longИдентификатор товара, присваиваемый Оператором.
    invoiceIdxs:longУникальный номер транзакции в ИС Оператора.
    orderNumberxs:normalizedString, до 64 символовНомер заказа в ИС Контрагента. Передается, только если был указан в платежной форме.
    customerNumberxs:normalizedString, до 64 символовИдентификатор плательщика (присланный в платежной форме) на стороне Контрагента: номер договора, мобильного телефона и т.п.
    orderCreatedDatetimexs:dateTimeМомент регистрации заказа в ИС Оператора.
    orderSumAmountCurrencyAmountСтоимость заказа. Может отличаться от суммы платежа, если пользователь платил в валюте, которая отличается от указанной в платежной форме. В этом случае Оператор берет на себя все конвертации.
    orderSumCurrencyPaycashCurrencyCodeКод валюты для суммы заказа.
    orderSumBankPaycashCurrencyBankКод процессингового центра Оператора для суммы заказа.
    shopSumAmountCurrencyAmountСумма к выплате Контрагенту на р/с (стоимость заказа минус комиссия Оператора).
    shopSumCurrencyPaycashCurrencyCodeКод валюты для shopSumAmount.
    shopSumBankPaycashCurrencyBankКод процессингового центра Оператора для shopSumAmount.
    paymentPayerCodeYMAccountНомер счета в ИС Оператора, с которого производится оплата.
    paymentTypexs:normalizedStringСпособ оплаты заказа. Список значений приведен в таблице 6.6.1.
    Любые названия, отличные от перечисленных вышеxs:stringПараметры, добавленные Контрагентом в платежную форму.
    Обратите внимание: запросы Оператора могут содержать параметры, не описанные в этом документе. Контрагенту следует их игнорировать.
    Пример параметров запроса checkOrder:
    requestDatetime2011-05-04T20:38:00.000+04:00
    actioncheckOrder
    md58256D2A032A35709EAF156270C9EFE2E
    shopId13
    shopArticleId456
    invoiceId1234567
    customerNumber8123294469
    orderCreatedDatetime2011-05-04T20:38:00.000+04:00
    orderSumAmount87.10
    orderSumCurrencyPaycash643
    orderSumBankPaycash1001
    shopSumAmount86.23
    shopSumCurrencyPaycash643
    shopSumBankPaycash1001
    paymentPayerCode42007148320
    paymentTypeAC
    MyFieldДобавленное Контрагентом поле
    4.2.2. Формат ответа Контрагента
    Таблица 4.2.2.1. Параметры ответа операции checkOrder
    ПараметрТипОписание
    performedDatetimexs:dateTimeМомент обработки запроса по часам ИС Контрагента.
    codexs:intКод результата обработки. Список допустимых значений приведен в таблице ниже.
    shopIdxs:longИдентификатор Контрагента. Должен дублировать поле shopId запроса.
    invoiceIdxs:longИдентификатор транзакции в ИС Оператора. Должен дублировать поле invoiceId запроса.
    orderSumAmountCurrencyAmountСтоимость заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash.
    messagexs:string, до 255 символовТекстовое пояснение в случае отказа принять платеж.
    techMessagexs:string, до 64 символовДополнительное текстовое пояснение ответа Контрагента. Как правило, используется как дополнительная информация об ошибках. Необязательное поле.
    Таблица 4.2.2.2. Коды результата обработки запроса checkOrder
    КодЗначениеОписание ситуации
    0УспешноКонтрагент дал согласие и готов принять перевод.
    1Ошибка авторизацииНесовпадение значения параметра md5 с результатом расчета хэш-функции. Оператор считает ошибку окончательной и не будет осуществлять перевод.
    100Отказ в приеме переводаОтказ в приеме перевода с заданными параметрами. Оператор считает ошибку окончательной и не будет осуществлять перевод.
    200Ошибка разбора запросаИС Контрагента не в состоянии разобрать запрос. Оператор считает ошибку окончательной и не будет осуществлять перевод.
    Пример ответа на checkOrder при успехе обработки:
    <?xml version="1.0" encoding="UTF-8"?>
    <checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00"
    code="0" invoiceId="1234567"
    shopId="13"/>
    Пример ответа на checkOrder при ошибке, ИС отказала в приеме перевода на этапе проверки корректности заказа:
    <?xml version="1.0" encoding="UTF-8"?>
    <checkOrderResponse performedDatetime="2011-05-04T20:38:01.000+04:00"
    code="100" invoiceId="1234567"
    shopId="13"
    message="Указанный номер телефона не существует"
    techMessage="Неверный номер телефона"/>
    4.3. Уведомление о переводе (paymentAviso)
    Уведомление Контрагента о принятом переводе. Этот запрос обозначает факт успешного перевода денежных средств плательщика в адрес Контрагента и обязанность Контрагента выдать товар плательщику.
    Обратите внимание: на этом шаге Контрагент не может отказаться от приема перевода.
    4.3.1. Формат запроса Оператора
    Параметры запроса ‘Уведомление о переводе’ совпадают с параметрами для запроса ‘Проверка заказа’ (см. описание в разделе 4.2.1). Специфичные для операции paymentAviso параметры приведены в таблице ниже:
     
    Таблица 4.3.1.1. Параметры запроса операции paymentAviso
    ПараметрТипОписание
    actionxs:normalizedString, до 16 символовТип запроса, значение: paymentAviso.
    paymentDatetimexs:dateTimeМомент регистрации оплаты заказа в ИС Оператора.
    cps_user_country_codexs:string, 2 символаДвухбуквенный код страны плательщика в соответствии с ISO 3166-1 alpha-2.
    Обратите внимание:
  • Код страны плательщика (cps_user_country_code) определяется из данных, которые Оператор получает из технических источников, соответствующих выбранному способу оплаты. Плательщик такие данные не подтверждает. Оператор не несет ответственности за их достоверность.
  • Запросы Оператора могут содержать параметры, не описанные в данном документе. Контрагенту следует их игнорировать.
  • Пример параметров запроса paymentAviso:
    requestDatetime2011-05-04T20:38:00.000+04:00
    actionpaymentAviso
    md545125C95A20A7F25B63D58EA304AFED2
    shopId13
    shopArticleId456
    invoiceId1234567
    customerNumber8123294469
    orderCreatedDatetime2011-05-04T20:38:00.000+04:00
    orderSumAmount87.10
    orderSumCurrencyPaycash643
    orderSumBankPaycash1001
    shopSumAmount86.23
    shopSumCurrencyPaycash643
    shopSumBankPaycash1001
    paymentDatetime2011-05-04T20:38:10.000+04:00
    paymentPayerCode42007148320
    paymentTypeAC
    cps_user_country_codeRU
    MyFieldДобавленное Контрагентом поле
    4.3.2. Формат ответа Контрагента
    Параметры ответа Контрагента на запрос ‘Уведомление о переводе’ совпадают с параметрами для операции ‘Проверка заказа’ (см. описание в разделе 4.2.2).
    Возможные коды результата обработки запроса ‘Уведомление о переводе’ приведены в таблице ниже:
    Таблица 4.3.2.1. Коды результата обработки запроса paymentAviso
    КодЗначениеОписание ситуации
    0УспешноУспешно — даже если Оператор прислал данный запрос повторно.
    1Ошибка авторизацииЗначение параметра md5 не совпадает с результатом расчета хэш-функции. Оператор не будет повторять запрос и пометит заказ как ‘Уведомление Контрагенту не доставлено’.
    200Ошибка разбора запросаИС Контрагента не в состоянии разобрать запрос. Оператор не будет повторять запрос и пометит заказ как ‘Уведомление Контрагенту не доставлено’.
    Пример ответа на paymentAviso при успехе обработки:
    <?xml version="1.0" encoding="UTF-8"?>
    <paymentAvisoResponse
    performedDatetime ="2011-05-04T20:38:11.000+04:00"
    code="0" invoiceId="1234567"
    shopId="13"/>
    4.4. Правила обработки HTTP-уведомлений Контрагентом
    1. Контрагенту следует проверять значение параметра md5 для проверки целостности и подлинности запросов. Если значение md5 не совпадает с результатом расчета хэш-функции MD5, нужно отказывать в обработке запроса.
    MD5-хэширование применяется к тексту, формируемому как последовательность значений ряда параметров запроса, разделенных символом ‘точка с запятой’ — ‘;’. Порядок следования параметров следующий:
    action;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;shopId;invoiceId;customerNumber;shopPassword
    Пример:
    Исходная строка (без переносов)Результат хеширования
    checkOrder;87.10;643;1001;13;55;8123294469;s<kY23653f,{9fcnshwq1B35ABE38AA54F2931B0C58646FD1321
    2. ИС Контрагента должна отвечать на запросы Оператора в течение 10 секунд.
    3. При отсутствии ответа от Контрагента на запрос ‘Проверка заказа’ или при любом ответе кроме ‘Успешно’ Оператор сообщит плательщику о невозможности заплатить.
    4. При длительном многократном отсутствии ответа Контрагента на запросы ‘Уведомление о переводе’ (либо при многократных технических ошибках) ИС Оператора будет повторять попытки доставки уведомления в течение суток: первый раз — через минуту, потом еще до пяти раз с интервалом 5–30 минут. После этого платеж будет переведен в окончательный статус. Успешный или неуспешный — зависит от параметров подключения Контрагента (подробная информация приведена в разделе 6.1 ‘Параметры подключения Контрагента’).
    5. Оператор присваивает каждому переводу уникальный номер (invoiceId). Контрагент должен быть готов к тому, что запрос ‘Уведомление о переводе’ для одного и того же invoiceId может приходить неоднократно (из-за проблем со связью или ошибок в ответе ИС Контрагента на этот запрос). На повторные уведомления ИС Контрагента должна отвечать успехом (code="0").
     

    5. Email-уведомления о переводах

    При подключении по email-схеме Контрагент определяет адрес электронной почты, на который он будет принимать email-уведомления от Оператора.
    Уведомления отправляются в теле электронного сообщения (email) и подписываются сертификатом Оператора (S/MIME подпись).
    Оператор формирует отдельное уведомление по итогам каждого успешного платежа в пользу Контрагента. Формат уведомления представлен ниже:
    Таблица 5.1. Поля email-уведомления о переводе
    ПолеЗначение
    Извещение №Номер email-уведомления о переводе в адрес Контрагента.
    ПолучательЮридическое наименование Контрагента, указанное при подключении.
    Время переводаДата и время перевода в формате ‘dd.mm.yyyy hh:mm:ss’, по часам ИС Оператора.
    СуммаСумма перевода. Разделитель дробной части — точка, всегда ровно два знака после запятой, разделитель тысяч отсутствует.
    Номер транзакцииУникальный номер транзакции в ИС Оператора.
    Идентификатор плательщикаИдентификатор плательщика в ИС Контрагента. Значение параметра customerNumber платежной формы (здесь и ниже см. раздел 3 ‘Платежная форма’).
    Номер у контрагентаУникальный номер заказа в ИС Контрагента. Значение параметра orderNumber платежной формы. Если поле не заполнено, подставляется значение из ‘Номер транзакции’.
    ФИОФИО плательщика. Значение параметра custName платежной формы.
    Адрес доставкиАдрес доставки товара или адрес проживания плательщика. Значение параметра custAddr платежной формы.
    EmailАдрес электронной почты плательщика. Значение параметра custEMail платежной формы.
    Содержание заказаДетали заказа: список приобретенных товаров, их количество, назначение платежа и т.п. Значение параметра orderDetails платежной формы.
    Обратите внимание: некоторые поля могут прийти с пустыми значениями, если соответствующий параметр не был включен Контрагентом в платежную форму или не был заполнен плательщиком.
    Образец email-уведомления:
    Subject: Yandex.Dengi payment for Наименование_Контрагента #87
     
    Извещение № 87
     
    Получатель: ООО ‘Наименование_Контрагента’
     
    Время перевода: 18.01.2008 16:32:37
    Сумма: 12.00 RUB
    Номер транзакции: 1099511628638
    Идентификатор плательщика: 4637937
    Номер у Контрагента: 1099511628638
     
    Заполнено плательщиком в платежной форме Контрагента:
     
    ФИО: Иванов Иван Иванович
    Адрес доставки: г. Москва, ул. Московская 3-45
    Email: ivanovii@domain.com
    Содержание заказа: какое-то описание заказа
     

    6. Приложения

    6.1. Параметры подключения Контрагента
    Для подключения к ИС Оператора Контрагент должен сообщить следующие настройки (пп. 3-6 требуются только при HTTP-схеме подключения, п. 9 — только при email-схеме):
     
    Таблица 6.1.1. Параметры подключения Контрагента
    ПараметрЗначениеКомментарий
    1. Наименование КонтрагентаОт 3 до 128 символовНазвание магазина Контрагента, которое плательщик должен видеть в процессе платежа.
    2. Адрес сайта Контрагента  
    3. checkURL
  • Для тестирования
  • Для продакшн

  • * до 200 символов
    URL, по которому ИС Контрагента будет доступна для запросов Оператора ‘Проверка заказа’. Для взаимодействия необходимо использовать протокол HTTPS.
    4. paymentAvisoURL
  • Для тестирования
  • Для продакшн

  • * до 200 символов
    URL, по которому ИС Контрагента будет доступна для запросов Оператора ‘Уведомление о переводе’. Для взаимодействия необходимо использовать протокол HTTPS.
    5. Секретное слово КонтрагентаРекомендуется использовать случайно сгенерированный набор символов длиной не более 20 символов.Необходимо для формирования md5 хэша, передаваемого в запросах ‘Проверка заказа’ и ‘Уведомление о переводе’ в адрес Контрагента.
    6. Учет переводов при недоставке уведомления о переводе
  • 6.1 Считать неуспешным
  • 6.2 Считать успешным
  • Настройка определяет взаимное поведение Контрагента и Оператора при невозможности доставки ‘Уведомления о переводе’ (длительное многократное отсутствие ответа Контрагента на запросы Оператора либо многократные технические ошибки ИС Контрагента).
    Описание вариантов см. в таблице 6.1.2 ниже.
    7. Порядок перенаправления плательщика после завершения перевода 7.1 На статические адреса товара Контрагента:
    articleIdsuccessURL(*)
     failURL(*)
    articleIdsuccessURL(*)
     failURL(*)
    * до 200 символов; адреса для тестирования и для продакшн
     
    7.2 На адреса, передаваемые Контрагентом в платежной форме
    Настройка определяет порядок перенаправления плательщика на сайт Контрагента после завершения оплаты. Переход происходит со страницы результата платежа — по клику на ссылку ‘Вернуться в магазин’.
    Описание вариантов перенаправления см. в таблице 6.1.3 ниже.
    8. Email для реестров Адрес электронной почты для отправки реестров переводов, принятых Оператором в пользу Контрагента.
    9. Email для уведомлений о переводах Адрес электронной почты для отправки уведомлений.
    Таблица 6.1.2. Варианты учета переводов при недоставке ‘Уведомления о переводе’
    ВариантКомментарий
    ‘Считать неуспешным’ (по умолчанию)Оператор прекращает попытки доставки уведомления, помечает перевод как недоставленный Контрагенту и не помещает его в реестр принятых переводов. Сумма неуспешного перевода будет автоматически возвращена плательщику. Контрагент может обнаружить ‘потерянные уведомления’ путем сверки с использованием сервиса Merchant Web Services (MWS).
    ‘Считать успешным’Оператор прекращает попытки доставки уведомления и помечает перевод как успешный. Перевод будет включен в реестр принятых переводов согласно времени последней попытки доставки ‘Уведомления о переводе’. Контрагент может обнаружить «потерянные уведомления» путем сверки с реестром или с использованием сервиса MWS (*).
    * Для доступа к просмотру списка операций через веб-интерфейс MWS Контрагенту потребуется выпустить только сертификат, программировать ничего не нужно.
    Реализация протокола MWS требуется, если Контрагенту нужен функционал возвратов. За документацией обратитесь к своему менеджеру.
     
    Таблица 6.1.3. Варианты перенаправления плательщика после завершения перевода
    ВариантКомментарий
    ‘На статические адреса товара Контрагента’ (по умолчанию)Для перехода используются фиксированные адреса, определенные в следующих настройках (отдельно по каждому товару):
  • successURL
  • failURL
  • ‘На адреса, передаваемые Контрагентом в платежной форме’Для перехода используются адреса, которые Контрагент должен передавать в параметрах платежной формы (отдельно по каждому платежу):
  • shopSuccessURL
  • shopFailURL
  • Обратите внимание:
    1. При редиректе к URL'у для перехода добавляются ‘?action=PaymentSuccess’ (‘?action=PaymentFail’), а также все параметры запроса от Оператора к ИС Контрагента (параметры платежной формы). Переход осуществляется при помощи метода GET (исключение — неуспех оплаты из кошелька в Яндекс.Деньгах, в этом случае переход осуществляется методом POST).
    2. При неопределенном статусе платежа редирект производится на главную страницу сайта Контрагента (URL, указанный при подключении: ‘2. Адрес сайта Контрагента’), дополнительные параметры к URL'у при этом не подклеиваются.
    3. Если Контрагент собирается отображать персональную информацию, предназначенную для конкретного плательщика, то он должен авторизовать такого плательщика собственными средствами, Это могут быть стандартная авторизация на сайте Контрагента (через cookies и т. п.) или через сессионные ключи Контрагента, помещенные им в платежную форму.
    4. При оплате наличными через терминалы и при платеже со счета мобильного телефона редирект осуществляется на главную страницу сайта Контрагента, дополнительные параметры к URL'у не подклеиваются.
    5. При оплате из кошелька в системе WebMoney редирект плательщика на сайт Контрагента производится напрямую из системы WebMoney. При этом WebMoney могут подклеивать к URL'у для перехода свои собственные дополнительные параметры.
    6. При оплате через Сбербанк: оплата по SMS или Сбербанк Онлайн и через Альфа-Клик, Промсвязьбанк и QIWI Wallet редирект плательщика на сайт Контрагента не выполняется.
    6.2. Особенности взаимодействия при оплате наличными через терминалы
    Взаимодействие Оператора и Контрагента в случае оплаты заказа наличными через терминалы имеет ряд особенностей по сравнению с базовым сценарием (описан в разделе 2 ‘Обобщенное описание взаимодействия’). Эти особенности необходимо учитывать:
    3-4. После получения параметров платежной формы и определения способа платежа у плательщика дополнительно запрашиваются телефон и адрес электронной почты.
    ‘Если Контрагент передал среди параметров платежной формы телефон плательщика (cps_phone) и/или email (cps_email), форма подтверждения платежа будет предзаполнена этими данными.’
    5. Плательщику выдается специальный код и инструкция по оплате через терминалы и кассы. Этот же код, а также сумма к оплате, высылаются Оператором в SMS на указанный телефон.
    При клике по ссылке ‘Вернуться в магазин’, размещенной на странице выдачи кода, плательщик перенаправляется на адрес Контрагента, указанный при подключении (‘2. Адрес сайта Контрагента’). Параметры (shop)successURL, (shop)failURL в данной ситуации не используются.
    6. Полученный на шаге 5 код плательщик может указать в качестве назначения платежа в любом терминале или банкомате, где принимаются деньги для пополнения кошельков в Яндекс.Деньгах.
    Обратите внимание: если терминал имеет техническую возможность сообщить Оператору о внесении денег в режиме реального времени, на этом шаге будет выполнен дополнительный запрос «Проверка заказа» (checkOrder). Тогда в случае, если Контрагент откажется от приема перевода, деньги от плательщика не будут приняты терминалом.
    7-11. После получения от терминальной сети информации о том, что плательщик внес деньги, Оператор выполняет последовательные запросы ‘Проверка заказа’ (checkOrder) и ‘Уведомление о переводе’ (paymentAviso).
    Обратите внимание:
  • если Контрагент откажется принимать перевод, Оператор самостоятельно вернет деньги плательщику;
  • если плательщик внесет в терминал сумму, которая больше стоимости заказа, сдача будет автоматически перечислена на счет указанного при платеже мобильного телефона;
  • если плательщик внесет в терминал сумму, которая меньше стоимости заказа, Оператор пришлет ему SMS с информацией о недостающей сумме. Для проведения платежа плательщик должен будет довнести недостающую сумму.
  • 11. После ответа от ИС Контрагента на ‘Уведомление о переводе’ Оператор отправляет на указанный плательщиком адрес электронной почты сообщение о результате проведения платежа.
    6.3. Особенности взаимодействия при оплате через внешние платежные системы
    Взаимодействие Оператора и Контрагента в случае оплаты заказа через Сбербанк: оплата по SMS или Сбербанк Онлайн, Альфа-Клик, Промсвязьбанк, MasterPass, QIWI Wallet, а также из кошелька в системе WebMoney (далее — внешняя платежная система, ВПС) имеет ряд особенностей по сравнению с базовым сценарием (описан в разделе 2 «Обобщенное описание взаимодействия»). Эти особенности необходимо учитывать:
    3-4. После получения параметров платежной формы и определения способа платежа у плательщика на странице Оператора дополнительно запрашиваются данные для оплаты через ВПС (опционально).
    Обратите внимание: при оплате из кошелька в системе WebMoney ввод дополнительных данных не производится, и плательщик визуально сразу же перенаправляется на сторону WebMoney.
    5-7. Оператор сообщает ВПС сумму к оплате и опциональный набор сведений о товаре и плательщике.
    8. Оператор перенаправляет плательщика на сторону ВПС для проведения оплаты.
    9-11. Дальнейшие отображение сведений о товаре, способ подтверждения оплаты, информирование плательщика о результате операции, а также возможность перенаправления плательщика на сайт Контрагента после завершения оплаты определяются особенностями функционирования конкретной ВПС.
    12-17. После получения от ВПС информации об успешном списании средств с плательщика Оператор выполняет последовательные запросы «Проверка заказа» (checkOrder) и «Уведомление о переводе» (paymentAviso).
    Обратите внимание: при оплате через MasterPass в запросах Оператора и в реестре принятых переводов будет указан тип платежа AC (оплата с произвольной банковской карты).
    6.4. Особенности взаимодействия при оплате через мобильный терминал
    Прием платежей с банковских карт через мобильный терминал (mPOS) осуществляется с помощью специального ридера, подключенного к смартфону с установленным приложением «2can for Yandex.Money».
    Уведомление Контрагента о таком платеже дополнительно содержит информацию о назначении платежа, введенном в соответствующее поле приложения. При подключении Контрагента по HTTP-схеме данные передаются в параметре orderDetails запросов «Проверка заказа» (checkOrder) и «Уведомление о переводе» (paymentAviso). При подключении по email-схеме — в поле «Содержание заказа» email-уведомлений.
    6.5. Реестры принятых переводов
    Раз в сутки Оператор формирует реестр принятых в пользу Контрагента переводов. Реестр отправляется в теле электронного сообщения на email (*), указанный Контрагентом при подключении (‘8. Email для реестров’). Реестр подписывается сертификатом Оператора (S/MIME подпись). В реестре содержатся все переводы за указанную в реестре дату.
    * Также возможна отправка реестров по (s)ftp. За подробной информацией обратитесь к своему менеджеру.
    Тема (subject) электронного сообщения формируется по следующему шаблону (нумерация сквозная):
    РЕЕСТР ПЛАТЕЖЕЙ В <Наименование_Контрагента>. № <номер>
    Тело электронного сообщения формируется как:
    РЕЕСТР ПЛАТЕЖЕЙ В <Наименование Контрагента>. № <номер>
    Дата платежей: <dd.mm.yyyy>
     
    Номер транзакции; Идентификатор клиента; Сумма платежа; Валюта платежа; Сумма за вычетом комиссии; Время платежа; Номер кошелька плательщика; Краткое описание; Тип платежа
     
    <Данные платежей>
     
    Сумма принятых платежей <Тип операции>:<общая сумма принятых переводов данного типа за сутки>
    Сумма принятых платежей за вычетом комиссии типа <Тип операции>: <сумма принятых переводов данного типа за вычетом комиссии Оператора>
    Число платежей типа <Тип операции>: <количество переводов данного типа>
     
    Сумма принятых платежей:<общая сумма принятых переводов за сутки>
    Сумма принятых платежей за вычетом комиссии: <сумма принятых переводов за вычетом комиссии Оператора>
    Число платежей: <количество переводов>
     
    Кому: <Наименование Контрагента>
     
    (По договору <номер договора между Контрагентом и Оператором>)
    Описание полей с данными платежей приведено в таблице ниже.
     
    Таблица 6.5.1. Поля стандартного реестра принятых переводов
    ПолеЗначение
    Номер транзакцииУникальный номер транзакции в ИС Оператора (string, до 32 символов). Значение параметра invoiceId уведомлений Оператора.
    Идентификатор клиентаИдентификатор плательщика в ИС Контрагента (string, до 64 символов). Значение параметра customerNumber платежной формы.
    Сумма платежаСумма транзакции. Разделитель дробной части — точка, всегда ровно два знака после запятой, разделитель тысяч отсутствует.
    Валюта платежаТрехбуквенный код валюты (RUB — Рубль РФ).
    Сумма за вычетом комиссииСумма к выплате Контрагенту на р/с. Разделитель дробной части — точка, всегда ровно два знака после запятой, разделитель тысяч отсутствует.
    Время платежаМомент доставки ‘Уведомления о переводе’ Контрагенту (при работе по email-схеме — момент регистрации оплаты заказа в ИС Оператора). Дата и время в формате ‘dd.mm.yyyy hh:mm:ss’, по часам Оператора.
    Номер кошелька плательщикаНомер счета в ИС Оператора, с которого произведена оплата.
    Краткое описаниеТекстовое наименование оплаченного товара в ИС Оператора.
    Тип платежаСпособ, которым был совершен платеж. Значения соответствуют значениям параметра paymentType (см. таблицу 6.6.1). Необязательное поле.
     
    Образец реестра:
    Subject: РЕЕСТР ПЛАТЕЖЕЙ В Наименование_Контрагента. № 3355
     
    РЕЕСТР ПЛАТЕЖЕЙ В ООО ‘Наименование_Контрагента’. № 3355
    Дата платежей: 14.03.2014
     
    Номер транзакции; Идентификатор клиента; Сумма платежа; Валюта платежа; Сумма за вычетом комиссии; Время платежа; Номер кошелька плательщика; Краткое описание; Тип платежа
     
    549755819524; 4956; 10.00; RUB; 9.50; 18.12.2007 17:46:58; 410038366898; оплата услуг Интернет Магазин; GP
    549755819525; 4957; 15.00; RUB; 14.25; 18.12.2007 17:47:32; 410038366898; оплата услуг Интернет Магазин; PC
     
    Сумма принятых платежей типа PC: 15.00 RUB
    Сумма принятых платежей за вычетом комиссии типа PC: 14.25 RUB
    Число платежей типа PC: 1
     
    Сумма принятых платежей типа GP: 10.00 RUB
    Сумма принятых платежей за вычетом комиссии типа GP: 9.50 RUB
    Число платежей типа GP: 1
     
    Сумма принятых платежей: 25.00 RUB
    Сумма принятых платежей за вычетом комиссии: 23.75 RUB
    Число платежей: 2
     
    Кому: ООО ‘Наименование_Контрагента’
     
    (По договору 111.1111.11)
    6.6. Способы оплаты
    Таблица 6.6.1. Значения параметра paymentType
    ЗначениеПояснение
    PCОплата из кошелька в Яндекс.Деньгах.
    ACОплата с произвольной банковской карты.
    MCПлатеж со счета мобильного телефона.
    GPОплата наличными через кассы и терминалы.
    WMОплата из кошелька в системе WebMoney.
    SBОплата через Сбербанк: оплата по SMS или Сбербанк Онлайн.
    MPОплата через мобильный терминал (mPOS).
    ABОплата через Альфа-Клик.
    MAОплата через MasterPass.
    PBОплата через Промсвязьбанк.
    QWОплата через QIWI Wallet.
     

    6.7. Типы данных

    Таблица 6.7.1. Определения типов данных протокола
    ТипОписание
    xs:int32-bit целое знаковое число. Int32, определенный в стандарте: http://www.w3.org/TR/xmlschema-2/#int
    xs:long64-bit целое знаковое число. Int64, определенный в стандарте: http://www.w3.org/TR/xmlschema-2/#long
    xs:decimalДесятичное число с фиксированной точкой, определенное в стандарте: http://www.w3.org/TR/xmlschema-2/#decimal
    xs:booleanЛогическое значение (true/false), определено в стандарте: http://www.w3.org/TR/xmlschema-2/#boolean
    xs:stringТекстовая строка, определенная в стандарте: http://www.w3.org/TR/xmlschema-2/#string
    xs:normalizedStringТекстовая строка, определенная в стандарте: http://www.w3.org/TR/xmlschema-2/#normalizedString
    xs:dateTimeВременная метка в формате согласно рекомендациям:
    Формат определяется как:
    YYYY-MM-DDThh:mm:ss.fZZZZZ
    Расшифровка формата
    YYYYгод, точно 4 цифры
    MMмесяц, точно 2 цифры (01=январь и т. д.)
    DDдень месяца, точно 2 цифры (от 01 до 31)
    Tлатинский символ ‘T’, должен быть в верхнем регистре
    hhчасы, точно 2 цифры (24-часовой формат, от 00 до 23)
    mmминуты, точно 2 цифры (от 00 до 59)
    ssсекунды, точно 2 цифры (от 00 до 59)
    fдробная часть секунды (от 1 до 6 цифр),
    может отсутствовать, в этом случае следует опускать и разделитель ‘.’
    ZZZZZОписатель временной зоны, может принимать значения:
    Z — UTC, символ ‘Z’ должен быть в верхнем регистре.
    +hh:mm или -hh:mm — смещение относительно UTC (GMT) (показывает, что указано локальное время, которое на данное число часов и минут опережает или отстает от UTC).

    Обязательно должны присутствовать все указанные элементы, допустимо опускать только дробную часть секунд (в этом случае следует опускать и разделитель ‘.’). Если нужно задать только дату, то время всё равно следует указать как 00:00:00.
    Примеры:
    2011-07-24T19:00:00+04:00 — 19 часов 00 минут 24 июля 2011 года, часовой пояс — UTC + 4 часа.
    2004-07-24T15:00:00Z — тот же момент времени в каноническом представлении.
    2004-07-24T15:00:00.666Z — тот же момент времени плюс 666 миллисекунд.
    YMAccountНомер виртуального счета в ИС Оператора, строка десятичных цифр длиной от 11 до 33 символов.
    < xs:simpleType name="YMAccount">
    < xs:restriction base="xs:normalizedString">
    < xs:minLength value="11"/>
    <xs:maxLength value="33"/>
    < xs:pattern value="[0-9]+"/>
    </xs:restriction>
    < /xs:simpleType>
    CurrencyAmount Сумма. Положительное десятичное число с фиксированной точкой, после точки — две цифры.
    <xs:simpleType name="CurrencyAmount">
    <xs:restriction base="xs:decimal">
    <xs:minExclusive value="0"/>
    <xs:maxInclusive value="9999999999999"/>
    <xs:fractionDigits value="2"/>
    </xs:restriction>
    </xs:simpleType>
    CurrencyCodeКод валюты. Возможные значения:
    • 643 — рубль Российской Федерации;
    • 10643 — тестовая валюта (демо-рублики демо-системы ‘Яндекс.Деньги’).
    <xs:simpleType name="CurrencyCode">
    <xs:restriction base="xs:int">
    </xs:restriction>
    </xs:simpleType>
    CurrencyBankКод процессингового центра Оператора. Возможные значения:
    • 1001 — ЭкомБанк;
    • 1003 — ДемоБанк.
    <xs:simpleType name="CurrencyBank">
    <xs:restriction base="xs:int">
    </xs:restriction>
    </xs:simpleType>
     
     
    Дата публикации: 9 июня 2015 года