Для бизнеса

Описание интерфейса сервиса приема оплаты WebPurse

Содержание

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

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

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

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

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

Помимо регистрации в платежной системе WebPurse для приема платежей продавец должен настроить ряд параметров, регулирующих порядок приема платежей и оповещения продавца о факте проведения платежа.

Настройка параметров выполняется в меню Настройки в списке ваших магазинов.

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

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

Название параметра Формат Описание
Result URL 255 символов URL (на веб-сайте продавца), на который сервис WebPurse посылает HTTP POST-оповещение о совершении платежа с его детальными реквизитами.
URL должен начинаться с префикса "http://" или "https://".
При использовании префикса "http://" или "https://" сервис посылает оповещение по портам 80 и 443 соответственно.
Secret Key 50 символов Строка символов, добавляемая к реквизитам платежа, высылаемым продавцу вместе с оповещением. Эта строка используется для повышения надежности идентификации высылаемого оповещения. Содержание строки известно только сервису WebPurse и продавцу!
Success URL 255 символов URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в случае успешного выполнения платежа в сервисе WebPurse. URL должен иметь префикс "http://" или "https://".
Метод вызова Success URL - Метод (POST или GET), который будет использоваться при переходе на Success URL.
Fail URL 255 символов URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в том случае, если платеж в сервисе WebPurse не был выполнен по каким-то причинам. URL должен иметь префикс "http://" или "https://".
Метод вызова Fail URL - Метод (POST или GET), который будет использоваться при переходе на Fail URL.
Высылать оповещение об ошибке платежа на e-mail - Флаг, оповещающий WebPurse о том, что в случае возникновения ошибки при выполнении платежа необходимо послать оповещение на e-mail продавца.

ФОРМЫ HTML

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

  • Форма запроса платежа — генерируется веб-сайтом продавца для формирования запроса на проведение платежа в сервисе WebPurse и передачи его через веб-браузер покупателя.
  • Форма оповещения о платеже — генерируется сервисом WebPurse для передачи оповещения о платеже на веб-сайт продавца. Оповещение передается без использования веб-браузера покупателя.
  • Форма выполненного платежа — генерируется сервисом WebPurse в случае успешного выполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.
  • Форма невыполненного платежа — генерируется сервисом WebPurse в случае невыполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.

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

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

Action - https://webpurse.net/merchant/

Method - POST

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

Название HTML Field Name Обязательный? Описание
Идентификатор магазина LMI_PAYEE_SHOP Да Цифровой порядковый номер магазина, который добавлен в каталог WebPurse.
Валюта платежа LMI_PAYEE_CURRENCY Да Валюта в которой магазин желает принять платеж. Поддерживаются следующие типы валют: WPZ — эквивалент в долларах США; WPR — эквивалент в рублях РФ; WPU — эквивалент в украинской гривне; WPE — эквивалент в евро.
Сумма платежа LMI_PAYMENT_AMOUNT Да Сумма платежа, которую продавец желает получить от покупателя в валюте указанной в LMI_PAYEE_CURRENCY. Сумма должна быть больше нуля, дробная часть отделяется точкой.
Внутренний номер покупки продавца LMI_PAYMENT_NO Нет В этом поле продавец задает номер покупки в соответствии со своей системой учета. Несмотря на то, что параметр не является обязательным, мы рекомендуем всегда задавать его. Желательно использовать уникальный номер для каждого платежа, что позволит быстро получить относящуюся к нему информацию через другие интерфейсы системы WebPurse.
Номер должен представлять собой целое число не больше 2147483647.
Назначение платежа LMI_PAYMENT_DESC Да* Описание товара или услуги. Формируется продавцом.
Если присутствует, добавляется в назначение платежа в операцию перевода WebPurse. Максимальная длина - 255 символов.
Назначение платежа LMI_PAYMENT_DESC_BASE64 Да* Описание товара или услуги в UTF-8 и далее закодированное алгоритмом Base64. Формируется продавцом. Если присутствует, то результат раскодирования будет подставлен вместо LMI_PAYMENT_DESC. Позволяет не зависеть от кодировки на сайте продавца.

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

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

<html> 
<head>
 ... 
</head> 
<body> 
...
<form method="POST" action="https://webpurse.net/merchant/">  
	<input type="hidden" name="LMI_PAYMENT_AMOUNT" value="10.03" />
	<input type="hidden" name="LMI_PAYMENT_DESC" value="платеж по счету" />
	<input type="hidden" name="LMI_PAYMENT_NO" value="1234" />
	<input type="hidden" name="LMI_PAYEE_SHOP" value="123" />
	<input type="hidden" name="LMI_PAYEE_CURRENCY" value="WPZ" />
</form>
... 
</body>
</html>

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

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

Action - Result URL

Method - POST

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

Название HTML Field Name Описание
Кошелек продавца LMI_PAYEE_PURSE Кошелек продавца, на который покупатель совершил платеж. Формат - 8 цифр.
Сумма платежа LMI_PAYMENT_AMOUNT Сумма, которую заплатил покупатель. Дробная часть отделяется точкой.
Идентификатор магазина LMI_PAYEE_SHOP Цифровой порядковый номер магазина, который добавлен в каталог WebPurse.
Валюта платежа LMI_PAYEE_CURRENCY Валюта в которой магазин желает принять платеж. Поддерживаются следующие типы валют: WPZ — эквивалент в долларах США; WPR — эквивалент в рублях РФ; WPU — эквивалент в украинской гривне; WPE — эквивалент в евро.
Внутренний номер покупки продавца LMI_PAYMENT_NO В этом поле передается номер покупки в соответствии с системой учета продавца, полученный сервисом с веб-сайта продавца.
Внутренний номер платежа в системе WebPurse LMI_SYS_TRANS_NO Номер платежа в системе WebPurse, выполненный в процессе обработки запроса на выполнение платежа сервисом WebPurse. Является уникальным в системе WebPurse.
Кошелек покупателя LMI_PAYER_PURSE Кошелек или номер счета, с которого покупатель совершил платеж.
Платежная система LMI_PAYER_SYS Платежная система с помощью которой покупатель совершил платеж.
Контрольная подпись LMI_HASH Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя.
Алгоритм формирования описан в разделе Контрольная подпись данных о платеже.
Дата и время выполнения платежа LMI_SYS_TRANS_DATE Дата и время реального прохождения платежа в системе WebPurse в формате "DD.MM.YYYY HH:MM:SS".
Примечание к платежу LMI_PAYMENT_DESC Примечание к платежу, передается для контроля продавцом отсутствия искажений в примечании к платежу. Данное поле передается после обработки функцией URLEncode. Так как форма, передаваемая с сайта продавца на платежный сайт системы передается через клиентский браузер, продавец при необходимости (а обменный пункт или финансовый сервис в обязательном порядке) может проверить не только сумму платежа, но и оригинальное примечание к платежу.

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

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

<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="10000000" />
	<input type="hidden" name="LMI_SYS_TRANS_NO" value="123" />
	<input type="hidden" name="LMI_PAYER_PURSE" value="12345678" />
	<input type="hidden" name="LMI_PAYER_SYS" value="WebPurse" />
	<input type="hidden" name="LMI_SYS_TRANS_DATE" value="21.10.2012 16:31:14" />
	<input type="hidden" name="LMI_HASH" value="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" />
	<input type="hidden" name="LMI_PAYEE_SHOP" value="123" />
	<input type="hidden" name="LMI_PAYEE_CURRENCY" value="WPZ" />
</form>
 ... 
</body> 
</html>

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

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

Action - Success URL

Method - POST

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

Название HTML Field Name Описание
Внутренний номер покупки продавца LMI_PAYMENT_NO В этом поле передается номер покупки в соответствии с системой учета продавца, полученный сервисом с веб-сайта продавца.
Внутренний номер платежа в системе WebPurse LMI_SYS_TRANS_NO Номер платежа в системе WebPurse, выполненный в процессе обработки запроса на выполнение платежа сервисом WebPurse Merchant. Является уникальным в системе WebPurse.
Дата и время выполнения платежа LMI_SYS_TRANS_DATE Дата и время реального прохождения платежа в системе WebPurse в формате "DD.MM.YYYY HH:MM:SS".

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

<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_TRANS_NO" value="123" />
	<input type="hidden" name="LMI_SYS_TRANS_DATE" value="21.10.2012 16:31:14" />
</form>
...
</body> 
</html>

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

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

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_TRANS_NO" value="123" />
	<input type="hidden" name="LMI_SYS_TRANS_DATE" value="21.10.2012 16:31:14" />
</form>
...
</body> 
</html>

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

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

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

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

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

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

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

  1. Кошелек продавца (LMI_PAYEE_PURSE);
  2. Сумма платежа (LMI_PAYMENT_AMOUNT);
  3. Внутренний номер покупки продавца (LMI_PAYMENT_NO);
  4. Внутренний номер платежа в системе WebPurse (LMI_SYS_TRANS_NO);
  5. Дата и время выполнения платежа (LMI_SYS_TRANS_DATE);
  6. Secret Key (LMI_SECRET_KEY);

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

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

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

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

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

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

  • Сформируйте строку путем "склеивания" значений параметров, полученных через "Форму оповещения о платеже", в том же порядке, что и при формировании контрольной подписи в сервисе WebPurse. Помните, что при формировании подписи используется Secret Key.
  • Вычислите MD5 полученной строки. Переведите результат в верхний регистр.
  • Сравните полученное значение с значением параметра "LMI_HASH", полученного через "Форму оповещения о платеже". Если сформированная подпись совпадает с полученной через "Форму оповещения о платеже", данные не изменены, и источник данных действительно сервис WebPurse, необходимо вывести строку YES.

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

Для бизнеса / все преимущества

  • 12 способов оплаты, крупнейшая сеть приема платежей;
  • Подключение сайта — мгновенно и бесплатно;
  • Возможность «встроить» способы оплаты на ваш сайт;
  • Низкие комиссии на переводы;
  • Простая техническая реализация;