реклама здесь

обратная связь

о WebMoney / Материалы / XML-интерфейсы. Часть 6. X21

XML-интерфейсы. Часть 6. X21

© Никита Сенченко, 19.06.2012

моя оценка:

[средняя: 4]

Предыдущие статьи о XML-интерфейсах WebMoney:

XML-интерфейсы WebMoney. Часть 1. WMSigner.

XML-интерфейсы WebMoney. Часть 2. X2, X6, X8, X11

XML-интерфейсы WebMoney. Часть 3. X1, X3, X4, X9, X14, X16

XML-интерфейсы WebMoney. Часть 4. X19.

XML-интерфейсы WebMoney. Часть 5. X20.

Здесь лежит библиотека XOWM с PHP-функциями, которые реализуют работу с XML-интерфейсами WebMoney.

Введение

X21 - это новый XML-интерфейс WebMoney. Предназначен он для получения доверенности от клиента или покупателя на списание денег с его кошелька. Доверенность подтверждается с помощью SMS или USSD.

Вообще говоря, доверенности - это мощнейший инструмент в системе WebMoney. Он позволяет одному юзеру дать другому юзеру право списывать средства с его кошелька без дополнительного разрешения. Обычно получатель доверенности - это торговец, а доверитель - это его клиент, который планирует регулярно оплачивать услуги торговца.

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

Через веб доверенность можно выдать здесь. Доверитель указывает свой кошелек, который он "отдает в жертву", WMID того, кому дается доверенность, а также лимиты. Лимиты бывают такие: суточный, дневной, недельный и месячный. Сумму, превышающую хотя бы один из лимитов, - торговец списать не сможет.

С Вашего сайта отправить клиента на страницу, где тот сможет выдать Вам доверенность, можно по такой ссылке: https://security.webmoney.ru/asp/settrust.asp?masterwmid=ВАШ_WMID&trans=1&url=http://СТРАНИЦА/ВАШЕГО/САЙТА. При этом поле "Кому дается доверенность" будет уже заполнено ВАШИМ WMID, а после выдачи доверенности юзера автоматически отправят обратно на http://СТРАНИЦА/ВАШЕГО/САЙТА

Однако, такой способ получения доверенности не очень удобен для мобильных приложений, игр, программ и других мест, где клиента отправлять в браузер невозможно или не желательно. Как раз для таких случаев и придумали Х21. В нем выдача доверенности подтверждается с помощью мобильника - по SMS или USSD.

Списание с доверенного кошелька можно совершить ТОЛЬКО с помощью XML-интерфейса X2, сделать это с помощью Кипера или как-то еще - не получится. Поэтому X21 активирован только для тех, у кого подключен X2 (персональный аттестат обязателен).

Как работает Х21

В этом интерфейсе используется цифровая подпись, которая генерируется с помощью ключей (файл kwm) Вашего Keeper Classic и модуля WMSigner. Поэтому сначала Вам нужно разобраться с тем, как его установить на сервер и как использовать.

X21 работает 2-фазно. Иными словами, он совмещает в себе 2 запроса, которые нужно отправлять последовательно, при этом второй без первого существовать не может.

Отправляя 1-й запрос, Вы "просите" доверителя установить для Вас доверенность. WebMoney шлет на телефон доверителя SMS или USSD. Если было заказано подтверждение по SMS, то клиент должен передать Вам (в программе, приложении, на сайте) полученный SMS-код.

Во 2-м запросе Вы проверяете, подтвердил ли доверитель выдачу доверенности (если было заказано подтверждение по USSD и проходило без Вашего участия), либо скармливаете интерфейсу SMS-код, полученный от доверителя (если было заказано подтверждение по SMS).

Рассмотрим это детальнее.

1-й запрос

Как мы уже знаем, отправляя 1-й запрос интерфейсу X21, мы инициируем получение доверенности от своего клиента.

Запрос отправляется на URL https://merchant.webmoney.ru/conf/xml/XMLTrustRequest.asp методом POST.

Состав запроса:


<merchant.request>
    <wmid></wmid>
    <lmi_payee_purse></lmi_payee_purse>
    <lmi_day_limit></lmi_day_limit> 
    <lmi_week_limit></lmi_week_limit> 
    <lmi_month_limit></lmi_month_limit> 
    <lmi_clientnumber></lmi_clientnumber>     
    <lmi_clientnumber_type></lmi_clientnumber_type>     
    <lmi_sms_type></lmi_sms_type>     
    <sign></sign> 
    <lang></lang>
</merchant.request>

wmid - Ваш WMID (он же - WMID, на который Вы хотите получить доверенность от своего клиента).

lmi_payee_purse - Ваш кошелек (в рамках wmid). Его роль заключается только в том, чтобы указать, на переводы в какой валюте Вы хотите получить доверенность. Например, если здесь будет указан Ваш Z-кошелек, то доверителя попросят установить доверенность от его Z-кошелька на списание WMZ.

lmi_day_limit - лимит списания с кошелька за день.

lmi_week_limit - лимит списания с кошелька за неделю.

lmi_month_limit - лимит списания с кошелька за месяц.

lmi_clientnumber - идентификатор Вашего доверителя: номер телефона (без знака "+"), либо email, либо WMID, либо номер одного из его кошельков.

lmi_clientnumber_type - указатель, что именно было передано в lmi_clientnumber (0 - телефон; 1 - WMID; 2 - email; 4 - кошелек).

lmi_sms_type - желаемый способ подтверждения (1 - SMS; 2 - USSD).

sign - цифровая подпись запроса. Цифровая подпись должна быть получена из текстовой строки, образованной в результате склеивания значений wmid + lmi_payee_purse + lmi_clientnumber + lmi_clientnumber_type + lmi_sms_type.

lang - язык, на котором будет отправлено SMS\USSD и на котором будет сформировано описание ответа userdesc ("ru-RU" - русский, "en-EN" - английский).

Зачем нужен lmi_clientnumber? Задача состоит в том, чтобы определить WMID доверителя. Еще нужно определить его телефон, чтобы отправить туда SMS\USSD. Например, если в lmi_clientnumber передан email, то по нему WebMoney находит пользователя в своей базе (по аттестату) и таким образом определяет его WMID и телефон. Если передан телефон, то WebMoney находит соответствующий ему WMID и т.д.

Остановимся ненадолго на лимитах. В lmi_day_limit, lmi_week_limit и lmi_month_limit нужно передавать цифры, дробная часть отделяется точкой. Например, если в lmi_day_limit передать 41.45, и при этом в lmi_payee_purse передан Z-кошелек, то это означает, что доверенность будет выдана с лимитом 41.45 WMZ в день. Сумму больше 41.45 в течение одного дня по доверенности списать не получится.

Если в lmi_day_limit, lmi_week_limit или lmi_month_limit передается "0", то это означает, что соответствующий лимит установлен не будет. "0" во всех трех лимитах - не допускается. Также не допускается, чтобы lmi_week_limit был меньше lmi_day_limit, а lmi_month_limit был меньше lmi_week_limit, что вполне логично.

И в любом случае лимиты не могут превышать ограничения, установленные для Keeper Mini с проверенным телефоном и формальным аттестатом. См. здесь пункт 3: Финансовые ограничения WebMoney Keeper Mini.

Несколько примеров:

lmi_day_limit=10, lmi_week_limit=0, lmi_month_limit=0 - установит дневной лимит в 10

lmi_day_limit=10, lmi_week_limit=0, lmi_month_limit=20 - установит дневной лимит в 10, а месячный в 20.

lmi_day_limit=0, lmi_week_limit=12, lmi_month_limit=40 - установит недельный лимит в 12, а месячный в 40.

lmi_day_limit=0, lmi_week_limit=0, lmi_month_limit=0 - вызовет ошибку интерфейса (все лимиты равны 0).

lmi_day_limit=10, lmi_week_limit=5, lmi_month_limit=0 - вызовет ошибку интерфейса (недельный лимит меньше дневного).

lmi_day_limit=700, lmi_week_limit=0, lmi_month_limit=0 - вызовет ошибку интерфейса для Z-кошелька (дневной лимит 700 WMZ - это больше максимального допустимого лимита в 600 WMZ за день).

При определении лимитов, которые нужно передавать в X21 в каждом конкретном случае, нужно руководствоваться здравым смыслом. Предположим, Вы - хостинг-провайдер, и Ваш клиент имеет тарифный план стоимостью 20 WMZ в месяц. В таком случае правильнее всего будет передать: lmi_day_limit=0, lmi_week_limit=0, lmi_month_limit=20. Это позволит Вам ежемесячно (раз в месяц, либо частями на протяжении месяца) списывать с клиента необходимую сумму.

Начнем писать нашу PHP-функцию, которая будет реализовывать работу с Х21:


if($step==1) {
	$rsign=_GetSign($Global_WMID.$lmi_payee_purse.$lmi_clientnumber.$lmi_clientnumber_type.$lmi_sms_type);
	$xml="
	<merchant.request>
	    <wmid>$Global_WMID</wmid>
	    <lmi_payee_purse>$lmi_payee_purse</lmi_payee_purse>
	    <lmi_day_limit>$lmi_day_limit</lmi_day_limit> 
	    <lmi_week_limit>$lmi_week_limit</lmi_week_limit> 
	    <lmi_month_limit>$lmi_month_limit</lmi_month_limit> 
	    <lmi_clientnumber>$lmi_clientnumber</lmi_clientnumber>     
	    <lmi_clientnumber_type>$lmi_clientnumber_type</lmi_clientnumber_type>     
	    <lmi_sms_type>$lmi_sms_type</lmi_sms_type>     
	    <sign>$rsign</sign> 
	    <lang>$lang</lang>
	</merchant.request>";
	$resxml=_GetAnswer($XML_addr[211], $xml);
}

Цифровая подпись (поле sign) формируется с помощью WMSigner. В нашей библиотеке XOWM задачу получения цифровой подписи решает функция _GetSign().

Ответ сервера WebMoney:

<?xml version="1.0"?>
<merchant.response>
    <trust purseid="">
        <realsmstype></realsmstype>
    </trust> 
    <retval></retval> 
    <retdesc></retdesc>
    <userdesc></userdesc>  
</merchant.response>

атрибут purseid - некий идентификатор, который WebMoney присвоила Вашему запросу.

realsmstype - какой способ подтверждения применен (1 - SMS; 2 - USSD).

retval - результат отработки запроса. "0" свидетельствует о том, что запрос успешно отработан, и SMS\USSD отправлено. Другое значение retval свидетельствует об ошибке.

retdesc - описание ошибки.

userdesc - текст, который можно транслировать юзеру. В нем WebMoney передает "юзеропонятное" описание ошибки, либо указания к дальнейшим действиям.

Внимание! purseid нужно обязательно сохранить (в сессии, в базе данных и т.п.), поскольку его значение используется во 2-м запросе.

Если юзер заказал подтверждение по SMS (realsmstype = 1), то на этом этапе через интерфейс Вашей программы, сайта, приложения у него нужно запросить код, который он получил смской в телефон.

2-й запрос

Зачем нужен 2-й запрос?
1) Если юзер подтверждает выдачу доверенности по SMS (realsmstype = 1) и ввел полученный SMS-код на Вашей стороне (на сайте, в программе и т.д.), то 2-м запросом вы передаете этот SMS-код на сервер WebMoney и тем самым WebMoney убеждается в "легальности" выдаваемой доверенности и в том, что Вы действительно ожидаете эту доверенность получить.
2) Если юзер подтверждал выдачу доверенности по USSD (realsmstype = 2), иными словами, если подтверждение происходило без Вашего участия, то 2-й запрос позволяет проверить, а было ли подтверждение. Более того, если не "дернуть" 2-й запрос в этом случае, то WebMoney и не "зафиксирует" выдачу доверенности. Таким образом, посылать 2-й запрос даже при USSD-подтверждении нужно обязательно!

Вызов 2-го запроса разумно возложить на самого клиента, например, показать ему кнопку типа "Я подтверждаю выдачу доверенности".

2-й запрос отправляется на URL https://merchant.webmoney.ru/conf/xml/XMLTrustConfirm.asp методом POST.

Состав запроса:


<merchant.request>
    <wmid></wmid>
    <lmi_purseid></lmi_purseid>
    <lmi_clientnumber_code></lmi_clientnumber_code>     
    <sign></sign>
    <lang></lang>
</merchant.request>

wmid - то же, что и в 1-м запросе.

lmi_purseid - номер, полученный в ответе на 1-й запрос.

lmi_clientnumber_code - здесь нужно передать SMS-код, полученный от юзера, если доверенность подтверждается по SMS (realsmstype = 1). Если подтверждалось по USSD, то здесь нужно передать "0".

sign - цифровая подпись запроса, которая должна формироваться с помощью WMSigner. Цифровая подпись должна быть получена из текстовой строки, образованной в результате склеивания значений wmid + lmi_purseid +lmi_clientnumber_code.

lang - язык, на котором будет сформировано описание ответа userdesc ("ru-RU" - русский, "en-EN" - английский).

Наша функция дополнилась таким кодом:


if($step==1) {
...
} elseif($step==2) {
	$rsign=_GetSign($Global_WMID.$lmi_purseid.$lmi_clientnumber_code);
	$xml="
	<merchant.request>
		<wmid>$Global_WMID</wmid>
		<lmi_purseid>$lmi_purseid</lmi_purseid>
		<lmi_clientnumber_code>$lmi_clientnumber_code</lmi_clientnumber_code>
		<sign>$rsign</sign>
		<lang>$lang</lang>
	</merchant.request>";
	$resxml=_GetAnswer($XML_addr[212], $xml);
}

Ответ сервера WebMoney:

<?xml version="1.0"?>
<merchant.response>
    <trust  id="">
        <slavepurse></slavepurse>
        <slavewmid></slavewmid>
        <masterwmid></masterwmid>
    </trust> 
    <retval></retval> 
    <retdesc></retdesc> 
    <userdesc></userdesc> 
</merchant.response>

trust, атрибут id - уникальный идентификатор выданной доверенности.

slavepurse - клиентский кошелек, от которого выдана доверенность.

slavewmid - клиентский WMID, от которого выдана доверенность (понятное дело, slavepurse принадлежит slavewmid).

retval - результат отработки запроса. "0" свидетельствует о том, что запрос успешно отработан, и доверенность выдана.

retdesc и userdesc - смысл у этих полей такой же, как и в 1-м запросе.

Еще пара замечаний по 2-му запросу.

1) retval=0 и id>0 однозначно свидетельствуют о том, что доверенность успешно выдана.

2) Поскольку в будущем нам понадобится списывать деньги с кошелька доверителя (с помощью X2), то нам обязательно нужно сохранить в БД номер этого кошелька, от которого выдана доверенность (slavepurse). Заодно можно сохранить и WMID (slavewmid).

Функция _WMXML21()

Функция _WMXML21() для работы с Х21 включена в библиотеку XOWM (требуются расширения PHP: simplexml, iconv, curl). Ничего сверхъестественного она не делает. В зависимости от принятого параметра $step (1 или 2) отправляет в WebMoney соответственно 1-й или 2-й запрос. Набор входных параметров у этой функции одинаковый для обеих step (запросов). Он огромен:


function _WMXML21 ($step, $lmi_payee_purse, $lmi_day_limit, $lmi_week_limit, $lmi_month_limit, $lmi_clientnumber, $lmi_clientnumber_type, $lmi_sms_type, $lmi_purseid, $lmi_clientnumber_code, $lang) {
      ...
      return $result;
}

Однако, поскольку у 1-го и 2-го запроса есть как общие параметры, так и отличающиеся, то некоторые параметры будут отсутствовать в вызове функции при 1-м запросе ($step=1), а некоторые параметры будут отсутствовать в вызове функции при 2-м запросе ($step=2). Вот пример вызова функции для 1-го запроса. Пустуют $lmi_purseid и $lmi_clientnumber_code:

$r=_WMXML21(1, "Z123456789012", 10, 19, 0, "client@email.ru", 2, 2, "", "", "ru-RU");

А вот пример вызова для 2-го запроса. Имеет смысл передавать только $step, $lmi_purseid, $lmi_clientnumber_code, $lang:

$res=_WMXML21(2, "", "", "", "", "", "", "", 12345, 89898, "ru-RU");

Понятное дело, функция и возвращает в 1-м и 2-м запросе несколько разный набор параметров в массиве $result.

группа: Материалы

категории: Программинг | Бизнесмену |

другие материалы в этих категориях:
   WebMoney запустила сервис для стримеров.
   Новая библиотека для платформы .Net
   Влияет ли ENUM на работу интерфейса Х2?
   Программируем авторизацию через ENUM
   Облагаются ли какими-то налогами суммы, поступающие на кошельки?

прочтений: 9148

Если Вам понравилась статья, подпишитесь на оповещения:

Комментарии (0) ... Будьте первым!

Что нового почитать?

	Снижение комиссии при выводе WMX, WMH, WML 12.04.18 Для участников системы WebMoney с 26 марта 2018 года доступен вывод по расписанию для WMX, WMH, WML со сниженной комиссией.
	Вывод из системы WebMoney на примере WMU (Вебмани Гривни ). 29.03.18 Многие сталкивались с проблемой,когда хотят вывести из системы WebMoney,где лучше,быстрее и безопасно.
	Как пополнить кошелёк WebMoney через терминал ПриватБанка (Украина). 16.03.18 [2] Как пополнить кошелёк WebMoney через терминал ПриватБанка (Украина). Актуально для жителей Украины.
	Кошелёк Bitcoin Cash WMH в системе WebMoney (Вебмани). 13.03.18 [1] Кошелёк Bitcoin Cash WMH в системе WebMoney (Вебмани). Как создать,пополнить и вывести Кошелёк Bitcoin Cash( WMH) в системе WebMoney (Вебмани).
	КОШЕЛЁК WMX (BITCOIN) В СИСТЕМЕ WEBMONEY. 06.03.18 После выхода ролика про создание ролика лайткоин (litecoin) многие спрашивают про кошелёк биткоина в системе Webmoney.Об этом наш новый ролик.
	WebMoney запустила сервис для стримеров. 03.03.18 В последнее время чрезвычайно популярны онлайн-трансляции, они получили название стрим, а люди, которые их ведут – стримеры. WebMoney предоставляет ун
	Как пополнить WMU через платёжный терминал на Украине. 27.02.18 Гуляя недавно по Киеву,надо было пополнить кошелёк WMU,для оплаты сотового,и если у вас нету в друзьях обменный пункт=),вам этот ролик поможет.
	В WebMoney появился кошелёк Litecoin 25.02.18 [1] В WebMoney появился кошелёк Litecoin.Крипто-бум,... который в последнее время потрясает электронную коммерцию, достиг и WebMoney. Не так давно WebMoney п

читать всё

Кофейня (форум)

Перевозка негабаритных грузов 19.02.19

Покупка новостройки 02.02.19

Родовое проклятие и интересное знакомство 31.01.19

читать весь форум

p2p

Меняют 50100 WMR на 50000 Qiwi (курс:+0.2%) 19.02.19

Меняют 60600 Bitcoin на 60000 USD (курс:1.01) 18.02.19

Меняют 20000 WMR на 8097 UAH (курс:2.47) 18.02.19

смотреть все обмены

WebMoney TOP

Зарегистрирован Хозяйственный сектор На сайте hozsektor.ru вы узнаете, как обустроить загородный дом или дачу своими руками, фото, видео,...

Зарегистрирован WebMoney Business Tools WebMoney Business Tools — бесплатная программа с открытым исходным кодом, предназначенная для интерн...

Зарегистрирован Интернет магазин цифровых товаров MyArena На MyArena можно продавать и покупать программное обеспечение, скрипты, музыку, видео, электронные к...

сравнить все сайты

WM-Клуб

Присоединился Василий Галанов

Присоединился Николай Метлюк

Присоединился Николай Бирюк

все участники

Все права на материалы, опубликованные на owebmoney.ru, охраняются в соответствии с законом об авторском праве. Разрешено копирование без согласования при условии указания гиперссылки на сайт (без атрибута nofollow и сокрытий) непосредственно до\после материала.