Приложение № 2. Протокол обмена информацией при осуществлении переводов: HTTP- и email-уведомления
Эта страница больше не поддерживается. Новый Протокол приема платежей для магазинов.
Протокол 3.0.1, редакция от 09.06.2015
1. Общие сведения
1.1. Назначение документа
Данный документ описывает взаимодействие ООО НКО ЮMoney
(далее — Оператор, ЮMoney) с информационной системой (далее — ИС) Контрагента, необходимое для уведомления Контрагента о совершенном в его пользу переводе (далее также — платеж) в режиме реального времени.
Оператор обеспечивает прием платежей, осуществляемых различными способами: с банковских карт, из электронных кошельков (в том числе со счетов ЮMoney), наличными через терминалы, со счетов мобильных телефонов. Перечень способов, доступный конкретному Контрагенту, зависит от условий договора и дополнительно контролируется настройками на стороне Оператора.
Упрощенно процесс взаимодействия можно представить в виде нескольких последовательных действий:
1. Передача Оператору данных о заказе и способе его оплаты (осуществляется с помощью браузера плательщика).
2. Уведомление Контрагента о платеже (осуществляется Оператором, возможна отправка HTTP- или email-уведомлений).
3. Формирование реестра принятых в пользу Контрагента переводов (пересылается Оператором по электронной почте).
4. Перечисление денежных средств на банковский счет Контрагента.
5. При необходимости — возврат успешных платежей плательщикам по инициативе Контрагента.
Пп. 1–3 описаны далее по тексту, пп. 4–5 выходят за рамки данного документа. Для работы с возвратами Контрагенту дополнительно потребуется выпустить сертификат и реализовать протокол Merchant Web Services (MWS). Процедура обмена сертификатами и протокол MWS описаны в отдельных документах.
1.2. Подключение Контрагента
Контрагенту доступны две схемы подключения к ЮMoney:
HTTP-уведомления о переводах);
Email-уведомления о переводах).
Принципиальное различие в том, что email-схема не предполагает обратной связи, а HTTP-схема позволяет Контрагенту производить онлайн-проверку параметров заказа при оплате. Если Контрагенту необходимо в режиме реального времени демонстрировать плательщику у себя на сайте, что товар или услуга уже оплачены, Контрагент должен использовать HTTP-схему подключения к ЮMoney. Схемы не могут использоваться одновременно. Количество доступных способов оплаты от выбранной схемы не зависит.
В зависимости от схемы Контрагент должен сообщить Оператору параметры подключения: URL'ы (адрес электронной почты) для отправки уведомлений, URL'ы для редиректа плательщика после оплаты, адрес электронной почты для отправки реестров принятых переводов и т.д. (подробная информация — в разделе 6.1 Параметры подключения Контрагента
).
Оператор в ответ предоставляет настройки для доступа к тестовой среде ЮMoney, а после завершения процедуры отладки — настройки для боевого
взаимодействия. Подключение к MWS производится отдельно.
2. Обобщенное описание взаимодействия
0. Контрагент размещает на странице оплаты заказа платежную форму
с данными заказа и указанием способов оплаты (в ряде случаев возможно размещение платежной формы
на сайте Оператора: https://yoomoney.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-уведомление о переводе. |
Обратите внимание: взаимодействие Оператора и Контрагента в случае оплаты заказа способом, отличным от платежа из кошелька ЮMoney и оплаты с произвольной банковской карты, имеет ряд особенностей. Описания таких сценариев приведены в разделе 6 «Приложения».
Раз в сутки Оператор отправляет Контрагенту по электронной почте реестр принятых переводов. Контрагент должен сверять список успешных платежей по данным своей ИС со списком операций из реестра и сообщать Оператору о расхождениях. Формат реестра описан в разделе 6.5 «Реестры принятых переводов».
3. Платежная форма
Платежная форма размещается Контрагентом на странице оплаты, определяет параметры заказа и способ платежа. Отправка через браузер плательщика платежной формы по стандартному адресу (https://yoomoney.ru/eshop.xml) инициирует на стороне Оператора формирование и обработку распоряжения на перевод.
Пример платежной формы:
| |
Для передачи данных о заказе и способе его оплаты нужно использовать параметры из таблицы ниже. Все параметры регистрозависимые.
Таблица 3.1. Параметры платежной формы
| Параметр | Тип | Описание |
| Служебные параметры: | ||
| shopId | xs:long, обязательный | Идентификатор Контрагента, выдается Оператором. |
| shopArticleId | xs:long, необязательный | Идентификатор товара, выдается Оператором. Применяется, если Контрагент использует несколько платежных форм для разных товаров. |
| scid | xs:long, обязательный | Номер витрины Контрагента, выдается Оператором. |
| sum | CurrencyAmount, обязательный | Стоимость заказа. |
| customerNumber | xs:normalizedString, до 64 символов, обязательный | Идентификатор плательщика в ИС Контрагента. В качестве идентификатора может использоваться номер договора плательщика, логин плательщика и т. п. Возможна повторная оплата по одному и тому же идентификатору плательщика. |
| orderNumber | xs:normalizedString, до 64 символов, необязательный | Уникальный номер заказа в ИС Контрагента. Уникальность контролируется Оператором в сочетании с параметром shopId. Если платеж с таким номером заказа уже был успешно проведен, то повторные попытки оплаты будут отвергнуты Оператором. |
| shopSuccessURL | xs:string, до 250 символов, необязательный | URL, на который нужно отправить плательщика в случае успеха перевода. Используется при выборе соответствующей опции подключения Контрагента (см. раздел 6.1 Параметры подключения Контрагента). |
| shopFailURL | xs:string, до 250 символов, необязательный | URL, на который нужно отправить плательщика в случае ошибки оплаты. Используется при выборе соответствующей опции подключения Контрагента. |
| cps_email | xs:string, до 100 символов, необязательный | Адрес электронной почты плательщика. Если он передан, то соответствующее поле на странице подтверждения платежа будет предзаполнено (шаг 3 на схеме выше). |
| cps_phone | xs:string, до 15 символов, только цифры, необязательный | Номер мобильного телефона плательщика. Если он передан, то соответствующее поле на странице подтверждения платежа будет предзаполнено (шаг 3 на схеме выше). Номер телефона используется при оплате наличными через терминалы. |
| paymentType | xs:normalizedString, до 5 символов, необязательный | Способ оплаты. Например: Полный список значений см. в таблице 6.6.1. Обратите внимание: |
| Параметры, добавляемые Контрагентом: | ||
| Любые названия, отличные от перечисленных выше | xs:string | Параметры, добавленные Контрагентом в платежную форму, будут сохранены и переданы ИС Контрагента в запросах Проверка заказаи Уведомление о переводе. Суммарная длина всех добавленных Контрагентом параметров не должна превышать 4096 символов. Обратите внимание: в email-уведомлениях произвольные параметры Контрагента не передаются. Для передачи дополнительных данных о платеже Контрагент может воспользоваться стандартными параметрами, перечисленными ниже. |
| Служебные параметры, используемые в email-уведомлениях о переводе: | ||
| custName | xs:string, необязательный | ФИО плательщика. |
| custAddr | xs:string, необязательный | Адрес доставки товара или адрес проживания плательщика. |
| custEMail | xs:string, необязательный | Адрес электронной почты плательщика, только для отправки в email-уведомлениях. |
| orderDetails | xs: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-уведомлений Контрагентом
) и отказывать в обработке запроса при неуспехе проверки. Успех проверки хэша удостоверяет:
При взаимодействии ИС Оператора и Контрагента для защиты информации о платежах обязательно соблюдение одного из условий ниже:
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. При оплате способами, отличными от платежа из кошелька ЮMoney, внешние системы могут брать дополнительную комиссию. Тогда при отказе Контрагента от приема перевода средства возвращаются плательщику за вычетом такой комиссии.
4.2.1. Формат запроса Оператора
Таблица 4.2.1.1. Параметры запроса операции checkOrder
| Параметр | Тип | Описание |
| requestDatetime | xs:dateTime | Момент формирования запроса в ИС Оператора. |
| action | xs:normalizedString, до 16 символов | Тип запроса. Значение: checkOrder(без кавычек). |
| md5 | xs:normalizedString, ровно 32 шестнадцатеричных символа, в верхнем регистре | MD5-хэш параметров платежной формы, правила формирования описаны в разделе 4.4 Правила обработки HTTP-уведомлений Контрагентом. |
| shopId | xs:long | Идентификатор Контрагента, присваиваемый Оператором. |
| shopArticleId | xs:long | Идентификатор товара, присваиваемый Оператором. |
| invoiceId | xs:long | Уникальный номер транзакции в ИС Оператора. |
| orderNumber | xs:normalizedString, до 64 символов | Номер заказа в ИС Контрагента. Передается, только если был указан в платежной форме. |
| customerNumber | xs:normalizedString, до 64 символов | Идентификатор плательщика (присланный в платежной форме) на стороне Контрагента: номер договора, мобильного телефона и т.п. |
| orderCreatedDatetime | xs:dateTime | Момент регистрации заказа в ИС Оператора. |
| orderSumAmount | CurrencyAmount | Стоимость заказа. Может отличаться от суммы платежа, если пользователь платил в валюте, которая отличается от указанной в платежной форме. В этом случае Оператор берет на себя все конвертации. |
| orderSumCurrencyPaycash | CurrencyCode | Код валюты для суммы заказа. |
| orderSumBankPaycash | CurrencyBank | Код процессингового центра Оператора для суммы заказа. |
| shopSumAmount | CurrencyAmount | Сумма к выплате Контрагенту на р/с (стоимость заказа минус комиссия Оператора). |
| shopSumCurrencyPaycash | CurrencyCode | Код валюты для shopSumAmount. |
| shopSumBankPaycash | CurrencyBank | Код процессингового центра Оператора для shopSumAmount. |
| paymentPayerCode | YMAccount | Номер счета в ИС Оператора, с которого производится оплата. |
| paymentType | xs:normalizedString | Способ оплаты заказа. Список значений приведен в таблице 6.6.1. |
| Любые названия, отличные от перечисленных выше | xs:string | Параметры, добавленные Контрагентом в платежную форму. |
Обратите внимание: запросы Оператора могут содержать параметры, не описанные в этом документе. Контрагенту следует их игнорировать.
Пример параметров запроса checkOrder:
| requestDatetime | 2011-05-04T20:38:00.000+04:00 |
| action | checkOrder |
| md5 | 8256D2A032A35709EAF156270C9EFE2E |
| shopId | 13 |
| shopArticleId | 456 |
| invoiceId | 1234567 |
| customerNumber | 8123294469 |
| orderCreatedDatetime | 2011-05-04T20:38:00.000+04:00 |
| orderSumAmount | 87.10 |
| orderSumCurrencyPaycash | 643 |
| orderSumBankPaycash | 1001 |
| shopSumAmount | 86.23 |
| shopSumCurrencyPaycash | 643 |
| shopSumBankPaycash | 1001 |
| paymentPayerCode | 42007148320 |
| paymentType | AC |
| MyField | Добавленное Контрагентом поле |
4.2.2. Формат ответа Контрагента
Таблица 4.2.2.1. Параметры ответа операции checkOrder
| Параметр | Тип | Описание |
| performedDatetime | xs:dateTime | Момент обработки запроса по часам ИС Контрагента. |
| code | xs:int | Код результата обработки. Список допустимых значений приведен в таблице ниже. |
| shopId | xs:long | Идентификатор Контрагента. Должен дублировать поле shopId запроса. |
| invoiceId | xs:long | Идентификатор транзакции в ИС Оператора. Должен дублировать поле invoiceId запроса. |
| orderSumAmount | CurrencyAmount | Стоимость заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash. |
| message | xs:string, до 255 символов | Текстовое пояснение в случае отказа принять платеж. |
| techMessage | xs:string, до 64 символов | Дополнительное текстовое пояснение ответа Контрагента. Как правило, используется как дополнительная информация об ошибках. Необязательное поле. |
Таблица 4.2.2.2. Коды результата обработки запроса checkOrder
| Код | Значение | Описание ситуации |
| 0 | Успешно | Контрагент дал согласие и готов принять перевод. |
| 1 | Ошибка авторизации | Несовпадение значения параметра md5 с результатом расчета хэш-функции. Оператор считает ошибку окончательной и не будет осуществлять перевод. |
| 100 | Отказ в приеме перевода | Отказ в приеме перевода с заданными параметрами. Оператор считает ошибку окончательной и не будет осуществлять перевод. |
| 200 | Ошибка разбора запроса | ИС Контрагента не в состоянии разобрать запрос. Оператор считает ошибку окончательной и не будет осуществлять перевод. |
Пример ответа на checkOrder при успехе обработки:
| shopId="13"/> |
Пример ответа на checkOrder при ошибке, ИС отказала в приеме перевода на этапе проверки корректности заказа:
| shopId="13" message="Указанный номер телефона не существует" techMessage="Неверный номер телефона"/> |
4.3. Уведомление о переводе (paymentAviso)
Уведомление Контрагента о принятом переводе. Этот запрос обозначает факт успешного перевода денежных средств плательщика в адрес Контрагента и обязанность Контрагента выдать товар плательщику.
Обратите внимание: на этом шаге Контрагент не может отказаться от приема перевода.
4.3.1. Формат запроса Оператора
Параметры запроса Уведомление о переводе
совпадают с параметрами для запроса Проверка заказа
(см. описание в разделе 4.2.1). Специфичные для операции paymentAviso параметры приведены в таблице ниже:
Таблица 4.3.1.1. Параметры запроса операции paymentAviso
| Параметр | Тип | Описание |
| action | xs:normalizedString, до 16 символов | Тип запроса, значение: paymentAviso. |
| paymentDatetime | xs:dateTime | Момент регистрации оплаты заказа в ИС Оператора. |
| cps_user_country_code | xs:string, 2 символа | Двухбуквенный код страны плательщика в соответствии с ISO 3166-1 alpha-2. |
Обратите внимание:
Код страны плательщика (cps_user_country_code) определяется из данных, которые Оператор получает из технических источников, соответствующих выбранному способу оплаты. Плательщик такие данные не подтверждает. Оператор не несет ответственности за их достоверность.
Запросы Оператора могут содержать параметры, не описанные в данном документе. Контрагенту следует их игнорировать.
Пример параметров запроса paymentAviso:
| requestDatetime | 2011-05-04T20:38:00.000+04:00 |
| action | paymentAviso |
| md5 | 45125C95A20A7F25B63D58EA304AFED2 |
| shopId | 13 |
| shopArticleId | 456 |
| invoiceId | 1234567 |
| customerNumber | 8123294469 |
| orderCreatedDatetime | 2011-05-04T20:38:00.000+04:00 |
| orderSumAmount | 87.10 |
| orderSumCurrencyPaycash | 643 |
| orderSumBankPaycash | 1001 |
| shopSumAmount | 86.23 |
| shopSumCurrencyPaycash | 643 |
| shopSumBankPaycash | 1001 |
| paymentDatetime | 2011-05-04T20:38:10.000+04:00 |
| paymentPayerCode | 42007148320 |
| paymentType | AC |
| cps_user_country_code | RU |
| MyField | Добавленное Контрагентом поле |
4.3.2. Формат ответа Контрагента
Параметры ответа Контрагента на запрос Уведомление о переводе
совпадают с параметрами для операции Проверка заказа
(см. описание в разделе 4.2.2).
Возможные коды результата обработки запроса Уведомление о переводе
приведены в таблице ниже:
Таблица 4.3.2.1. Коды результата обработки запроса paymentAviso
| Код | Значение | Описание ситуации |
| 0 | Успешно | Успешно — даже если Оператор прислал данный запрос повторно. |
| 1 | Ошибка авторизации | Значение параметра md5 не совпадает с результатом расчета хэш-функции. Оператор не будет повторять запрос и пометит заказ как Уведомление Контрагенту не доставлено. |
| 200 | Ошибка разбора запроса | ИС Контрагента не в состоянии разобрать запрос. Оператор не будет повторять запрос и пометит заказ как Уведомление Контрагенту не доставлено. |
Пример ответа на paymentAviso при успехе обработки:
| 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| 1B35ABE38AA54F2931B0C58646FD1321 | |
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 платежной формы. |
| Адрес электронной почты плательщика. Значение параметра 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.2 ниже. | |||||||||||||
| 7. Порядок перенаправления плательщика после завершения перевода | 7.1 На статические адреса товара Контрагента:
7.2 На адреса, передаваемые Контрагентом в платежной форме | Настройка определяет порядок перенаправления плательщика на сайт Контрагента после завершения оплаты. Переход происходит со страницы результата платежа — по клику на ссылку Вернуться в магазин. Описание вариантов перенаправления см. в таблице 6.1.3 ниже. | ||||||||||||
| 8. Email для реестров | Адрес электронной почты для отправки реестров переводов, принятых Оператором в пользу Контрагента. | |||||||||||||
| 9. Email для уведомлений о переводах | Адрес электронной почты для отправки уведомлений. |
Таблица 6.1.2. Варианты учета переводов при недоставке Уведомления о переводе
| Вариант | Комментарий |
Считать неуспешным(по умолчанию) | Оператор прекращает попытки доставки уведомления, помечает перевод как недоставленный Контрагенту и не помещает его в реестр принятых переводов. Сумма неуспешного перевода будет автоматически возвращена плательщику. Контрагент может обнаружить потерянные уведомленияпутем сверки с использованием сервиса Merchant Web Services (MWS). |
Считать успешным | Оператор прекращает попытки доставки уведомления и помечает перевод как успешный. Перевод будет включен в реестр принятых переводов согласно времени последней попытки доставки Уведомления о переводе. Контрагент может обнаружить «потерянные уведомления» путем сверки с реестром или с использованием сервиса MWS (*). |
* Для доступа к просмотру списка операций через веб-интерфейс MWS Контрагенту потребуется выпустить только сертификат, программировать ничего не нужно.
Реализация протокола MWS требуется, если Контрагенту нужен функционал возвратов. За документацией обратитесь к своему менеджеру.
Таблица 6.1.3. Варианты перенаправления плательщика после завершения перевода
| Вариант | Комментарий |
На статические адреса товара Контрагента(по умолчанию) | Для перехода используются фиксированные адреса, определенные в следующих настройках (отдельно по каждому товару): |
На адреса, передаваемые Контрагентом в платежной форме | Для перехода используются адреса, которые Контрагент должен передавать в параметрах платежной формы (отдельно по каждому платежу): |
Обратите внимание:
1. При редиректе к URL'у для перехода добавляются ?action=PaymentSuccess
(?action=PaymentFail
), а также все параметры запроса от Оператора к ИС Контрагента (параметры платежной формы). Переход осуществляется при помощи метода GET (исключение — неуспех оплаты из кошелька ЮMoney, в этом случае переход осуществляется методом 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 код плательщик может указать в качестве назначения платежа в любом терминале или банкомате, где принимаются деньги для пополнения кошельков в ЮMoney.
Обратите внимание: если терминал имеет техническую возможность сообщить Оператору о внесении денег в режиме реального времени, на этом шаге будет выполнен дополнительный запрос «Проверка заказа» (checkOrder). Тогда в случае, если Контрагент откажется от приема перевода, деньги от плательщика не будут приняты терминалом.
7-11. После получения от терминальной сети информации о том, что плательщик внес деньги, Оператор выполняет последовательные запросы Проверка заказа
(checkOrder) и Уведомление о переводе
(paymentAviso).
Обратите внимание:
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 YooMoney».
Уведомление Контрагента о таком платеже дополнительно содержит информацию о назначении платежа, введенном в соответствующее поле приложения. При подключении Контрагента по HTTP-схеме данные передаются в параметре orderDetails запросов «Проверка заказа» (checkOrder) и «Уведомление о переводе» (paymentAviso). При подключении по email-схеме — в поле «Содержание заказа» email-уведомлений.
6.5. Реестры принятых переводов
Раз в сутки Оператор формирует реестр принятых в пользу Контрагента переводов. Реестр отправляется в теле электронного сообщения на email (*), указанный Контрагентом при подключении (8. Email для реестров
). Реестр подписывается сертификатом Оператора (S/MIME подпись). В реестре содержатся все переводы за указанную в реестре дату.
* Также возможна отправка реестров по (s)ftp. За подробной информацией обратитесь к своему менеджеру.
Тема (subject) электронного сообщения формируется по следующему шаблону (нумерация сквозная):
| РЕЕСТР ПЛАТЕЖЕЙ В <Наименование_Контрагента>. № <номер> |
Тело электронного сообщения формируется как:
| РЕЕСТР ПЛАТЕЖЕЙ В <Наименование Контрагента>. № <номер> Дата платежей: Номер транзакции; Идентификатор клиента; Сумма платежа; Валюта платежа; Сумма за вычетом комиссии; Время платежа; Номер кошелька плательщика; Краткое описание; Тип платежа <Данные платежей> Сумма принятых платежей <Тип операции>:<общая сумма принятых переводов данного типа за сутки> Сумма принятых платежей за вычетом комиссии типа <Тип операции>: <сумма принятых переводов данного типа за вычетом комиссии Оператора> Число платежей типа <Тип операции>: <количество переводов данного типа> Сумма принятых платежей:<общая сумма принятых переводов за сутки> Сумма принятых платежей за вычетом комиссии: <сумма принятых переводов за вычетом комиссии Оператора> Число платежей: <количество переводов> Кому: <Наименование Контрагента> (По договору <номер договора между Контрагентом и Оператором>) |
Описание полей с данными платежей приведено в таблице ниже.
Таблица 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 | Оплата из кошелька ЮMoney. |
| AC | Оплата с произвольной банковской карты. |
| MC | Платеж со счета мобильного телефона. |
| GP | Оплата наличными через кассы и терминалы. |
| WM | Оплата из кошелька в системе WebMoney. |
| SB | Оплата через Сбербанк: оплата по SMS или Сбербанк Онлайн. |
| MP | Оплата через мобильный терминал (mPOS). |
| AB | Оплата через Альфа-Клик. |
| MA | Оплата через MasterPass. |
| PB | Оплата через Промсвязьбанк. |
| QW | Оплата через QIWI Wallet. |
6.7. Типы данных
Таблица 6.7.1. Определения типов данных протокола
| Тип | Описание | ||||||||||||||||||
| xs:int | 32-bit целое знаковое число. Int32, определенный в стандарте: http://www.w3.org/TR/xmlschema-2/#int | ||||||||||||||||||
| xs:long | 64-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 Расшифровка формата
Обязательно должны присутствовать все указанные элементы, допустимо опускать только дробную часть секунд (в этом случае следует опускать и разделитель .). Если нужно задать только дату, то время всё равно следует указать как 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 символов.
| ||||||||||||||||||
| CurrencyAmount | Сумма. Положительное десятичное число с фиксированной точкой, после точки — две цифры.
| ||||||||||||||||||
| CurrencyCode | Код валюты. Возможные значения:
| ||||||||||||||||||
| CurrencyBank | Код процессингового центра Оператора. Возможные значения:
|
Дата публикации: 9 июня 2015 года