Описание интерфейса сервиса Web Merchant Interface

Содержание

• Основные термины
• Описание Web Merchant Interface
  • Параметры приема платежей
  • Алгоритм выполнения платежа
  • Формы HTML
    • Форма запроса платежа
    • Форма предварительного запроса
    • Форма оповещения о платеже
    • Форма выполненного платежа
    • Форма невыполненного платежа
  • Проверка информации о платеже
    • Проверка источника данных
    • Проверка целостности данных
    • Контрольная подпись данных о платеже
    • Проверка контрольной подписи
    • Проверка суммы платежа
    • Проверка кошелька продавца
    • Проверка режима платежа
    • XML-интерфейс выяснения состояния платежа по LMI_PAYMENT_NO
• Тестирование сервиса Web Merchant Interface
• Примеры использования интерфейса

Основные термины

Продавцом считается участник WebMoney Transfer, принимающий на свой WM-кошелек оплату от других участников системы с помощью сервиса Web Merchant Interface. Предполагается, что продавец принимает оплату за товары или услуги, предоставляемые им через Интернет, и следовательно, имеет собственный веб-сайт.

Покупателем считается участник WebMoney Transfer, желающий оплачивать услуги или товары, предлагаемые продавцом через Интернет.

Описание интерфейса Web Merchant Interface

ПАРАМЕТРЫ ПРИЕМА ПЛАТЕЖЕЙ

Помимо регистрации в WebMoney Transfer для приема платежей через сервис Web Merchant Interface продавец должен настроить ряд параметров, регулирующих порядок приема платежей и оповещения продавца о факте проведения платежа.

Настройка параметров выполняется на странице Настройки сайта сервиса — merchant.webmoney.ru.

Для каждого кошелька, на который продавец принимает платежи, в сервисе хранится свой набор значений.

Полный перечень параметров и их назначение приведено ниже:

Алгоритм выполнения платежа

Алгоритм выполнения платежа представлен на рисунке ниже.

ФОРМЫ HTML

Для передачи информации между веб-сайтом продавца и сервисом Web Merchant Interface используютcя пять основных HTML-формы:

• Форма запроса платежа – генерируется веб-сайтом продавца для формирования запроса на проведение платежа в сервисе Web Merchant Interface и передачи его через веб-браузер покупателя.
• Форма предварительного запроса – генерируется сервисом Web Merchant Interface для передачи параметров предварительного запроса на выполнение платежа на веб-сайт продавца, если установлен флаг Передавать параметры в предварительном запросе. Если флаг не установлен – не используется (запрос выполняется без параметров). Запрос передается без использования веб-браузера покупателя.
• Форма оповещения о платеже – генерируется сервисом Web Merchant Interface для передачи оповещения о платеже на веб-сайт продавца. Оповещение передается без использования веб-браузера покупателя.
• Форма выполненного платежа – генерируется сервисом Web Merchant Interface в случае успешного выполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.
• Форма невыполненного платежа – генерируется сервисом Web Merchant Interface в случае невыполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.

Форма запроса платежа

Эта форма передает запрос с веб-сайта продавца в сервис Web Merchant Interface через веб-браузер покупателя. Она должна иметь следующие атрибуты и поля:

Action – https://merchant.webmoney.ru/lmi/payment.asp

Method – POST

Fields – поля, передаваемые в форме, описаны в таблице ниже:

* – Только один из параметров LMI_PAYMENT_DESC или LMI_PAYMENT_DESC_BASE64 должен присутствовать обязательно!

В поле Action формы у продавца всегда есть возможность спозиционировать покупателя сразу же на какой то определнный способ (вариант) оплаты. Это очень удобно, когда продавец полноценно реализует подключение магазина со всеми возможными опциями. Для этого служит параметр at в URL запроса, например, если произвести передачу платежной формы по URL https://merchant.webmoney.ru/lmi/payment.asp?at=authtype_8, то клиент будет сразу же спозиционирован на оплату с Webmoney кошелька, а если at=authtype_3, то с WebMoney карты. Если данный параметр не указан, то клиенту автоматически выбирается способ, который он выбрал и использовал при предыдущей оплате. Все доступные способы позицинирования перечислены ниже:

• authtype_2 Keeper Light
• authtype_3 WebMoney-карта (настоятельно рекомендуем, если на сайте продавца платеж скретч ВМ-картой вынесен в отдельный пункт, сразу спросить у клиента номер ВМ-карты и передать его в параметре LMI_PAYMER_PINNUMBERINSIDE , в этом случае позиционирование будет не нужно и покупатель сразу попадет на нужную страницу, минуя этап выбора способа платежа и ввода номера ВМ-карты )
• authtype_4 Keeper Mobile
• authtype_5 E-Num
• authtype_6 Чек Paymer (настоятельно рекомендуем, если на сайте продавца платеж чеком Пеймер вынесен в отдельный пункт, сразу спросить у клиента номер чека и передать его в параметре LMI_PAYMER_PINNUMBERINSIDE , в этом случае позиционирование будет не нужно и покупатель сразу попадет на нужную страницу, минуя этап выбора способа платежа и ввода номера чека Пеймер )
• authtype_7 Терминалы оплаты
• authtype_8 Keeper Classic
• authtype_9 Keeper Mini
• authtype_10 WM-нота (настоятельно рекомендуем, если на сайте продавца платеж ВМ-нотой вынесен в отдельный пункт, сразу спросить у клиента номер чека и передать его в параметре LMI_WMNOTE_PINNUMBERINSIDE, в этом случае позиционирование будет не нужно и покупатель сразу попадет на нужную страницу, минуя этап выбора способа платежа и ввода номера чека ВМ-ноты )
• authtype_11 Почта РФ (только для WMR-кошельков)
• authtype_12 Keeper для соц.сетей
• authtype_13 WebMoney чек
• authtype_14 Денежный перевод через распрастраненные системы денежных переводов (только для WMR-кошельков)
• authtype_16 кредитные карты российских банков, опция только для WMR-кошельков (настоятельно рекомендуем, если на сайте продавца платеж через банковские карты вынесен в отдельный пункт (иконку, способ и т.п. ), передать в параметре LMI_ALLOW_SDP = 4, в этом случае позиционирование будет не нужно и покупатель сразу попадет на нужную страницу оплаты банковской картой, минуя этап выбора способа платежа )
• authtype_17 быстрый платеж с указанием мобильного телефона (если продавцу известен номер мобильного телефона клиента в международном формате, то он может передать его в параметре LMI_FAST_PHONENUMBER и в этом случае покупателю не нужно будет вводить его у нас на сайте при проведении быстрого платежа)
• authtype_18 Интернет банкинги Альфа-Клик, Банк Русский стандарт, ВТБ24, опция только для WMR-кошельков (настоятельно рекомендуем, если на сайте продавца платеж через Интернет банкинги каждого банка вынесен в отдельный пункт (иконку, способ и т.п. ), передать номер выбранного банка в параметре LMI_ALLOW_SDP, в этом случае позиционирование будет не нужно и покупатель сразу попадет на нужную страницу, минуя этап выбора способа платежа, выбора банка и т.п. )
• authtype_19 оплата бонусными “СПАСИБО” от Сбербанка, опция только для WMR-кошельков.

Пример 1. Фрагмент “Формы запроса платежа” без замены URL

 
<html> 
<head>
 ... 
</head> 
<body> ...
<form method="POST" action="https://merchant.webmoney.ru/lmi/payment.asp">  
  <input type="hidden" name="LMI_PAYMENT_AMOUNT" value="12.08">
  <input type="hidden" name="LMI_PAYMENT_DESC" value="платеж по счету">
  <input type="hidden" name="LMI_PAYMENT_NO" value="1234">
  <input type="hidden" name="LMI_PAYEE_PURSE" value="Z145179295679">
  <input type="hidden" name="LMI_SIM_MODE" value="0">
  <input type="hidden" name="FIELD_1" value="VALUE_1">
  <input type="hidden" name="FIELD_2" value="VALUE_2">
  ... 
  <input type="hidden" name="FIELD_N" value="VALUE_N"> 
  ... 
</form>
... 
</body>
</html>

Пример 2. Фрагмент “Формы запроса платежа” с заменой URL

<html>
<head>
 ... 
</head> 
<body> 
... 
<form method="POST" action="https://merchant.webmoney.ru/lmi/payment.asp">
  <input type="hidden" name="LMI_PAYMENT_AMOUNT" value="12.08">
  <input type="hidden" name="LMI_PAYMENT_DESC" value="платеж по счету">
  <input type="hidden" name="LMI_PAYMENT_NO" value="1234">
  <input type="hidden" name="LMI_PAYEE_PURSE" value="Z145179295679">
  <input type="hidden" name="LMI_SIM_MODE" value="0">
  <input type="hidden" name="LMI_RESULT_URL" value="http://www.shop.com/result.asp">
  <input type="hidden" name="LMI_SUCCESS_URL" value="http://www.shop.com/success.html">
  <input type="hidden" name="LMI_SUCCESS_METHOD" value="2">
  <input type="hidden" name="LMI_FAIL_URL" value="http://www.shop.com/fail.html">
  <input type="hidden" name="LMI_FAIL_METHOD" value="2">
  <input type="hidden" name="FIELD_1" value="VALUE_1">
  <input type="hidden" name="FIELD_2" value="VALUE_2">
  ...
  <input type="hidden" name="FIELD_N" value="VALUE_N">
  ... 
</form>
 .. 
</body> 
</html>

Обратите внимание на ОБРАЗЦОВУЮ реализацию формы запроса платежа в магазине Плати.ру , в котором реализованы все возможности выбора способов платежа и прямого позиционирования клиента на нужный способ с уже имеющимися данными.

Форма предварительного запроса

Эта форма передает продавцу параметры выполняемого платежа непосредственно перед его выполнением. Она имеет следующие атрибуты и поля:

Action – Result URL

Method – POST

Fields – поля, передаваемые в форме, описаны в таблице ниже:

Если флаг передачи параметров установлен, веб-сайт продавца должен вернуть сторку “YES” в ответе для того, чтобы сервис Web Merchant Interface смог продолжить выполнение платежа. Если веб-сайт продавца вернет что-либо другое – платеж выполнен не будет а ответ будет показан покупателю в сообщении об ошибке.

Пример. Фрагмент “Формы предварительного запроса”

<html> 
<head>
 ... 
</head> 
<body>
 ...
<form method="POST" action="<Result URL>">
  <input type="hidden" name="LMI_PREREQUEST" value="1">
  <input type="hidden" name="LMI_PAYMENT_AMOUNT" value="1.0">
  <input type="hidden" name="LMI_PAYMENT_NO" value="1">
  <input type="hidden" name="LMI_PAYEE_PURSE" value="R222211112222">
  <input type="hidden" name="LMI_MODE" value="1">
  <input type="hidden" name="LMI_PAYER_WM" value="111122221111">
  <input type="hidden" name="LMI_PAYER_PURSE" value="R111122221111">
  <input type="hidden" name="FIELD_1" value="VALUE_1">
  <input type="hidden" name="FIELD_2" value="VALUE_2">
  ... 
</form>
 .. 
</body> 
</html>

Форма оповещения о платеже

Эта форма передает продавцу реквизиты выполненного платежа в момент его совершения. Она имеет следующие атрибуты и поля:

Action – Result URL

Method – POST

Fields – поля, передаваемые в форме, описаны в таблице ниже:

Внимание!
Продавец обязательно должен предусмотреть проверку информации, присланной в “Форме оповещения о платеже” в соответствии с рекомендациями раздела Алгоритм формирования и проверки контрольной подписи.

Пример. Фрагмент “Формы оповещения о платеже”

<html> 
<head> 
 ... 
</head> 
<body>
 ... 
<form method="POST" action="<Result URL>">
  <input type="hidden" name="LMI_PAYMENT_AMOUNT" value="1.0">
  <input type="hidden" name="LMI_PAYMENT_NO" value="1">
  <input type="hidden" name="LMI_PAYEE_PURSE" value="R397656178472">
  <input type="hidden" name="LMI_MODE" value="1">
  <input type="hidden" name="LMI_SYS_INVS_NO" value="281">
  <input type="hidden" name="LMI_SYS_TRANS_NO" value="558">
  <input type="hidden" name="LMI_PAYER_PURSE" value="R397656178472">
  <input type="hidden" name="LMI_PAYER_WM" value="809399319852">
  <input type="hidden" name="LMI_SYS_TRANS_DATE" value="20020314 14:01:14">
  <input type="hidden" name="LMI_HASH" value="114128B8AEFD8CAA76D3CF75B9AEBC17">
  <input type="hidden" name="FIELD_1" value="VALUE_1">
  <input type="hidden" name="FIELD_2" value="VALUE_2">
  ... 
</form>
 .. 
</body> 
</html>

Форма выполненного платежа

Эта форма передает реквизиты выполненного платежа на веб-сайт продавца после успешного выполнения операции. Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL “GET” или “POST”. Форма имеет следующие атрибуты и поля:

Action – Success URL

Method – POST

Fields – поля, передаваемые в форме, описаны в таблице ниже:

Пример. Фрагмент “Формы выполненного платежа”

<html> 
<head>
 ... 
</head> 
<body> 
... 
<form method="<метод вызова Success URL>" action="<Success URL>">
  <input type="hidden" name="LMI_PAYMENT_NO" value="1">
  <input type="hidden" name="LMI_SYS_INVS_NO" value="281">
  <input type="hidden" name="LMI_SYS_TRANS_NO" value="558">
  <input type="hidden" name="LMI_SYS_TRANS_DATE" value="20020314 14:01:14">
  <input type="hidden" name="FIELD_1" value="VALUE_1">
  <input type="hidden" name="FIELD_2" value="VALUE_2">
  ... 
</form>
 .. 
</body> 
</html>

Форма невыполненного платежа

Эта форма передает реквизиты невыполненного платежа на веб-сайт продавца. Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL “GET” или “POST”. Она имеет следующие атрибуты и поля:

Action – Fail URL

Method – метод вызова Fail URL

Fields – поля, передаваемые в форме – такие же как и для выполненного платежа.

Пример. Фрагмент “Формы невыполненного платежа”

<html> 
<head> 
... 
</head> 
<body> 
... 
<form method="<метод вызова Fail URL>" action="<Fail URL>">
  <input type="hidden" name="LMI_PAYMENT_NO" value="1">
  <input type="hidden" name="LMI_SYS_INVS_NO" value>
  <input type="hidden" name="LMI_SYS_TRANS_NO" value>
  <input type="hidden" name="LMI_SYS_TRANS_DATE" value>
  <input type="hidden" name="FIELD_1" value="VALUE_1">
  <input type="hidden" name="FIELD_2" value="VALUE_2">
  ... 
</form>
.. 
</body> 
</html>

ПРОВЕРКА ИНФОРМАЦИИ О ПЛАТЕЖЕ

При выполнении платежа Web Merchant Interface высылает оповещение о платеже через “Форму оповещения о платеже” на Result URL, указанный продавцом.

Мы рекомендуем вам проверить данные, полученные через “Форму оповещения о платеже”:

1. Проверить, действительно ли данные переданы от сервиса Web Merchant Interface (Проверка источника данных)
2. Проверить, не исказились ли данные в процессе передачи (Проверка целостности данных)
3. Проверить сумму платежа
4. Проверить кошелек продавца
5. Проверить режим проведения платежа (тестовый или реальный)

Кроме того рекомендуется проверять параметры входящей транзакции с использованием XML-интерфейса системы X3 или X18 или на странице проверка транзакции сайта сервиса Merchant WebMoney Transfer.

Проверка источника данных

Как указывалось выше, значение параметра “Secret Key” должно быть известно только сервису Web Merchant Interface и продавцу. Исходя из этого, Secret Key может использоваться для аутентификации источника, приславшего данные о платеже. Продавец, может провести аутентификацию несколькими методами в зависимости от того, обеспечивает Result URL секретность или нет:

• Result URL обеспечивает секретность и не переопределяется
  В этом случае продавец может производить аутентификацию источника данных двумя способами:
  1. Если продавец не желает проверять контрольную подпись, он должен установить флаг “Высылать Secret Key на Result URL”. В этом случае Merchant WebMoney Transfer будет высылать Secret Key на веб-сервер продавца в поле “LMI_SECRET_KEY” в форме оповещения о платеже. Продавец должен проверять его каждый раз, когда получает оповещение о выполнении платежа.
  2. Второй путь – это проверка контрольной подписи. Контрольная подпись формируется сервисом Web Merchant Interface с учетом значения параметра “Secret Key” и передается в поле “LMI_HASH”.
     Проверка подписи является более трудоемким методом, но он не требует передачи Secret Key через интернет.
• Result URL не обеспечивает секретность или переопределяется
  В этом случае сервис Web Merchant Interface не высылает Secret Key независимо от установленного флага “Высылать Secret Key на Result URL”. Поэтому для аутентификации источника оповещения о платеже продавец должен проверять контрольную подпись.

В любом случае следует проверять IP-адрес с которого поступил запрос.
Диапазон адресов которые использует сервис можно узнать на странице IP адреса WM

Проверка целостности данных

Высылая оповещение о проведение платежа, сервис Web Merchant Interface передает реквизиты платежа и контрольную подпись, позволяющую проверять неизменность передаваемых данных. Продавец может выполнить проверку целостности несколькими методами в зависимости от того обеспечивает Result URL секретность или нет:

• Result URL обеспечивает секретность и не переопределяется
  В этом случае продавец может не проверять контрольную подпись, так как используемый протокол SSL обеспечивает безопасность и целостность передаваемых данных.
• Result URL не обеспечивает секретность или переопределяется
  В этом случае сервис Web Merchant Interface рекомендует проверять целостность данных, используя контрольную подпись.

Контрольная подпись данных о платеже

Контрольная подпись данных о платеже позволяет продавцу проверять как источник данных, так и целостность данных, переданных на Result URL через “Форму оповещения о платеже”.

При формировании контрольной подписи сервис Web Merchant Interface “склеивает” значения полей, передаваемых “Формой оповещения о платеже”, в одну строку в следующем порядке:

1. Кошелек продавца (LMI_PAYEE_PURSE);
2. Сумма платежа (LMI_PAYMENT_AMOUNT);
3. Внутренний номер покупки продавца (LMI_PAYMENT_NO);
4. Флаг тестового режима (LMI_MODE);
5. Внутренний номер счета в системе WebMoney Transfer (LMI_SYS_INVS_NO);
6. Внутренний номер платежа в системе WebMoney Transfer (LMI_SYS_TRANS_NO);
7. Дата и время выполнения платежа (LMI_SYS_TRANS_DATE);
8. Secret Key (LMI_SECRET_KEY);
9. Кошелек покупателя (LMI_PAYER_PURSE);
10. WMId покупателя (LMI_PAYER_WM).

Алгоритм формирования контрольной подписи определяется настройками, установленными продавцом (MD5 или SIGN).

В случае использования MD5 формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5) разработанным Ron Rivest из MIT Laboratory for Computer Science и RSA Data Security, Inc. Алгоритм был опубликован в интернете в апреле 1992 года (RFC 1321).
Все символы в результате преобразуются в верхний регистр. При использовании SIGN формируется последовательность из 132 шестнадцатеричных цифр в соответствии с алгоритмом формирования аналога собственноручной подписи системы WebMoney Transfer (c использованием модуля WMSignerX).

Проверка контрольной подписи

Проверка контрольной подписи может выполняться как в “ручном” режиме на соответствующих страницах сайта Merchant.WebMoney.ru (MD5, SIGN), так и в “автоматическом” режиме на сайте продавца по следующему алгоритму:

1. MD5
   • Сформируйте строку путем “склеивания” значений параметров, полученных через “Форму оповещения о платеже”, в том же порядке, что и при формировании контрольной подписи в сервисе Web Merchant Interface (см. выше). Помните, что при формировании подписи используется Secret Key.
   • Вычислите MD5 полученной строки. Переведите результат в верхний регистр.
   • Сравните полученное значение с значением параметра “LMI_HASH”, полученного через “Форму оповещения о платеже”. Если сформированная подпись совпадает с полученной через “Форму оповещения о платеже”, данные не изменены, и источник данных действительно сервис Web Merchant Interface.
2. SIGN
   • Сформируйте строку путем “склеивания” значений параметров, полученных через “Форму оповещения о платеже”, в том же порядке, что и при формировании контрольной подписи в сервисе Web Merchant Interface (см. выше). Помните, что при формировании подписи используется Secret Key.
   • Выполните проверку цифровой подписи, используя Интерфейс X7. Идентификация и аутентификация клиента-владельца WM Keeper Classic на стороннем сайте. При этом в качестве передаваемых параметров укажите:
     • TesterWMID – идентификатор кипера продавца;
     • ClientWMID – идентификатор кипера сервиса Web Merchant Interface; формирующего цифровую подпись оповещения о выполнении платежа. Его WMID: 967909998006;
     • AccessMarker – строка, полученная на первом этапе путем “склеивания” значений параметров “Формы оповещения о платеже”;
     • ClientSignStr – контрольная подпись, сформированная сервисом Web Merchant Interface и переданная на веб-сайт продавца через “Форму оповещения о платеже” в параметре “LMI_HASH”;
     • SignStr – цифровая подпись запроса.

Если проверка дала положительный результат, данные не были изменены, и источник данных действительно сервис Web Merchant Interface.

Проверка суммы платежа

Несмотря на то, что покупатель не может изменить сумму платежа, продавцу рекомендуется контролировать информацию о сумме платежа, передаваемую через параметр “LMI_PAYMENT_AMOUNT”.

Проверка кошелька продавца

Несмотря на то, что покупатель не может изменить кошелек, на который совершается платеж, продавцу рекомендуется контролировать информацию о кошельке, которая передается через параметр “LMI_PAYEE_PURSE”, особенно при использовании нескольких кошельков при работе с Web Merchant Interface.

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

Web Merchant Interface позволяет проводить платежи в тестовом режиме для проверки работы веб-сайта продавца. Режим обработки платежа в сервисе определяется установкой параметра “Тестовый/Рабочий режимы”. Дополнительно информация о текущем режиме передается в параметре “LMI_MODE” (1 – тестовый режим, 0 – реальный режим).

В тестовом режиме реальный платеж не проводится, но сервис посылает данные, имитируя выполнение платежа.

XML-интерфейс выяснения состояния платежа по LMI_PAYMENT_NO

Для быстрого и безопасного выяснения состояния платежа (синхронизации или акутализации базы покупок сервиса, магазина, службы и т.п. с реальными завершенными операциями по WM-кошельку) Вы можете использовать XML-интерфейс X18, который по номеру LMI_PAYMENT_NO позволяет получить и информацию о платеже и его детали.

Тестирование сервиса Web Merchant Interface

Параметр “Тестовый/Рабочий режимы” позволяет продавцам тестировать интеграцию своего веб-сайта с сервисом Web Merchant Interface без выполнения реальных платежей. Если параметр установлен в режим “тест”, сервис будет генерировать только тестовые платежи.

Параметр “Тестовый/Рабочий режимы” должен быть установлен в режим “тест” до тех пор, пока продавец не будет уверен в том, что его веб-сайт, интегрированный с сервисом Merchant WebMoney Transfer, работает правильно!

Примеры использования интерфейса

• Пример использования интерфейса на языке PHP.

См. также:
Проверка транзакции, выполненной через сервис Merchant WebMoney Transfer
Прием платежей через терминалы оплаты, банкоматы, почту
Прием платежей чеками Paymer WM-картами и WM-нотами
Прием платежей через WM Keeper Mobile
Прием платежей с банковских карт российских банков
Web Merchant Interface - Прием платежей через Интернет-банк
Прием платежей через системы денежных переводов
Web Merchant Interface - Прием платежей бонусными «Спасибо» от Сбербанка
Быстрый способ настроить прием WebMoney на сайте продавца
Merchant WebMoney Transfer
Click&Buy Merchant Interface
Пример оплаты товаров и услуг через сервис Merchant WebMoney Transfer

Категория: Сервисы системы, Прием платежей

This article in other languages: English