о WebMoney
Информационный портал о WebMoney
  
  
подписка  
реклама здесь 
обратная связь 
  Материалы      Вопросы и ответы     Курс обучения      Файлы
 Кофейня      WebMoney TOP      p2p      WM-Клуб      Гид   
о WebMoney / Материалы / XML-интерфейсы. Часть 6. X21

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

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

моя оценка:
[средняя: 4]

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


Предыдущие статьи о 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.
    группа: Материалы
    прочтений: 7585
    Если Вам понравилась статья, подпишитесь на оповещения:

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

    введите этот код
    Мое имя:
    я не зарегистрирован и не хочу
    это моё зарегистрированное имя
    хочу зарегистрировать это имя
    Email:      
     оповещать об ответах
  •    Что нового почитать?
    Мой номер телефона утерян и не подлежит восстановлению. Как быть? 06.10.16 [3]
    ВОПРОС: Долго не пользовался своей симкой. Номер заблокирован, восстановлению не подлежит. Как востановить доступ к кошельку?
    Автомобилистам на заметку: как оплатить штраф по WM 04.10.16
    Сегодня мы хотим напомнить о возможностях, которые существуют в WebMoney для оплаты штрафов ГАИ и дорожных сборов. Если неприятность всё же произошла ...
    На WebMoney Merchant можно принимать Биткоины 30.09.16 [5]
    Если вы на вашем сайте принимаете WebMoney и делаете это через WebMoney Merchant, то для вас есть хорошая новость. Теперь с вами смогут рассчитаться т...
    Муравей-бот отвечает на вопросы о WebMoney в Telegram 27.09.16
    WebMoney запустил интеллектуального бота-помощника для мессенджера Telegram. Он постарается понять ваш вопрос и дать на него ответ.Для начала, разбере...
    Автоплатежи помогут не забыть об оплате 27.09.16
    В WebMoney Keeper, а также в личный кабинет Telepay добавлена опция автоплатежа для 3х крупнейших мобильных операторов России: Билайна, МТС и Мегафона...
    Новая библиотека для платформы .Net 14.09.16
    Разработчикам будет полезно узнать, что выпущена новая версия библиотеки для работы с XML-интерфейсами WebMoney для платформы Microsoft .Net.В ней реа...
    WebMoney пришла в Молдову 14.09.16 [1]
    WebMoney предоставила возможность работы с кошельком, номинированным в молдавских леях. Однако, кошелек этот не совсем обычный.Во-первых, кошелек созд...
    В обновленных Киперах появились регулярные платежи 04.08.16
    Обновилась вся линейка мобильных Киперов (iOS, Android, Windows Phone, MacOs X и BlackBerry OS 10), а также браузерный Keeper Standard.Главное новшест...

       Кофейня (форум)
    Проблема с Кипером WinPro версии 3.9.9.8 01.12.16
    Работает ли корректно в данный момент Х19? 30.11.16
    НБУ объяснил запрет электронных денег 08.11.16

       p2p
    Меняют 15225 WMZ на 15000 USD (курс:+1.5%) 07.12.16
    Меняют 26300 UAH на 1000 WMZ (курс:26.3) 07.12.16
    Меняют 100000 UAH на 250000 WMR (курс:2.5) 07.12.16

       WebMoney TOP
    Зарегистрирован Обмен24 Ввод/Вывод WebMoney, ЯД, QIWI на Privat24, СберБанк, АльфаБанк, ТКСБ и другие. Быстрая обработка зая...
    Зарегистрирован Green Cash Обменный пункт WebMoney в Москве. Ввод/вывод WebMoney на выгодных условиях. Работаем 7 дней в неделю...
    Зарегистрирован Bestchange.ee Ввод и вывод WM в Эстонии и Европе. Карты (чеки Paymer), высылаем на e-mail. Оплату принимаем на бан...

       WM-Клуб
    Присоединился Василий Галанов
    Присоединился Евгений Кудрявцев
    Присоединился Николай Бирюк


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