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

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

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

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

XML-интерфейс Х20 позволяет любому торговцу, который принимает вебмани с помощью WM Merhchant, полностью интегрировать весь процесс оплаты на своей сайт или в приложение и принимать платежи БЕЗ отправки плательщика на сайт Мерчанта.


Предыдущие статьи о 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.

    А также: WM Merchant и интерфейс Х18.

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



    Введение

    Х20 - это новый XML-интерфейс WebMoney, который работает на той же платформе, что и WebMoney Merchant и интерфейс Х18. Он обращается к тому же серверу merchant.webmoney.ru и использует те же принципы аутентификации на базе SecretKey и торговых кошельков.

    Х20 позволяет принимать оплату БЕЗ отправки юзера на сайт merchant.webmoney.ru в браузере. Поэтому Х20 - это идеальный способ принимать WM-платежи там, где открытие и использование браузера нежелательно или невозможно. Например, в мобильных приложениях, Windows-программах. Кроме того, Х20 можно применять для приема WebMoney-платежей даже в оффлайне, ведь плательщику понадобится только мобильник.

    Тем не менее, для простоты и наглядности, мы будем демонстировать работу Х20 именно в браузере здесь. Программный код мы реализуем на PHP и включим соответствующую функцию _WMXML20() в библитеку XOWM, которую оВебМани.Ру давно поддерживает и дополняет.

    Использовать Х20 может любой торговец - владелец кошелька, настроенного на работу с WM Merchant. Статью о том, как работает этот сервис и как его использовать, можно прочесть здесь на owebmoney.ru.

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

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

    Как работает Х20 детально описано на wiki. Читать обязательно! Однако, оВебМани.Ру для того и нужен, чтобы расжевать всё и разложить по полочкам :) Поэтому вернитесь сюда, когда дочитаете статью на wiki.

    Х20 работает так:

    1-й запрос, инициирование оплаты

    В 1-м запросе вы передаете:
  • идентификатор плательщика - email, либо телефон, либо WMID;
  • желаемый способ подтверждения платежа - SMS или USSD.
  • другие параметры будущего платежа, например, сумму (это очень похоже на "форму запроса платежа" в классическом протоколе WM Merchant).

    Исходя из идентификатора юзера и желаемого способа подтверждения, сервер WebMoney определяет недостающую информацию. Например, если вы сообщили: "email юзера такой-то, а подтвердить оплату он хочет по SMS", то сервер WebMoney по email отыщет его WMID и телефон, после чего отправит на телефон SMS с кодом подтверждения.

    Независимо от того, какой способ подтверждения выбран - SMS или USSD - сервер WebMoney всегда дополнительно выписывает WM-счет. Юзер на выбор может либо подтвердить оплату по SMS\USSD, либо оплатить WM-счет в своем Кипере (а оплачивать счета - напомним - позволяет абсолютно любая версия Кипера: Классик, Лайт, Мини и Мобайл).

    При подтверждении по SMS\USSD сервер WebMoney списывает оплату с первого попавшегося кошелька юзера (если внутри его WMID есть несколько кошельков), на котором достаточно денег.

    Таблица ниже демонстрирует, что происходит на сервере WebMoney в зависимости от тех или иных входных данных:



    При нахождении WMID по email, WMID по телефону, телефона по WMID и т.п. - используются email и телефон, которые указаны в аттестате.

    Кроме того, X20 учитывает телефоны, зарегистрированные в WebMoney Чек. Если в запросе будет передан телефон, который зарегистрирован в WebMoney Чек и не зарегистрирован ни в одном аттестате, то оплата спишется именно с Чека. При этом, конечно, WM-счет выписан не будет, т.к. Чек не поддерживает оплату счетов.

    Если вы обратите внимание на последнюю строчку таблицы, то увидите, что Х20 позволяет просто выписать юзеру WM-счет, не отправляя SMS или USSD. А значит, Х20 - это простая и удобная замена совместному использованию интерфейсов X1 + X4. Мы говорим "простая", потому что в Х1 и Х4 обязательно нужно применять WMSigner для подписи запросов, а в X20 - не обязательно.

    В ответ на 1-й запрос WebMoney отдает вам уникальный номер счета.

    2-й запрос, подтверждение оплаты

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

    Во 2-м запросе вы передаете:
  • номер счета, который получен в 1-м запросе;
  • если подтверждение по SMS, то юзер должен ввести у вас на сайте (в программе, в приложении) SMS-код, который он получил от WebMoney, а вы должны передать этот SMS-код.

    Получив от вас 2-й запрос, сервер WebMoney:
  • Проверяет, а не оплачен ли уже данный счет. Это логично, потому что после отработки 1-го запроса до вызова 2-го могло пройти время, в течение которого юзер мог подтвердить оплату, например, через USSD (если, конечно, было заказано подтверждение по USSD), либо путем оплаты WM-счета в Кипере.
  • Если подтверждение по SMS, то проверяется корректность SMS-кода, который вы передали в запросе, и если он корректен, то тут же происходит списание денег с кошелька юзера и сервер WebMoney рапортует вам о том, что оплата успешно произведена.

    1-й запрос

    Как мы уже знаем, 1-й запрос инициирует оплату.

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

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

    <merchant.request>
    <wmid></wmid>
    <lmi_payee_purse></lmi_payee_purse>
    <lmi_payment_no></lmi_payment_no>
    <lmi_payment_amount></lmi_payment_amount>
    <lmi_payment_desc></lmi_payment_desc>
    <lmi_clientnumber></lmi_clientnumber>
    <lmi_clientnumber_type></lmi_clientnumber_type>
    <lmi_sms_type></lmi_sms_type>
    <secret_key></secret_key>
    <sign></sign>
    <md5></md5>
    </merchant.request>


  • wmid - ваш WMID, подключенный к WM Merchant.
  • lmi_payee_purse - ваш торговый кошелек (в рамках wmid), подключенный к WM Merchant.
  • lmi_payment_no - номер платежа в вашей учетной системе (аналог LMI_PAYMENT_NO в "форме запроса платежа" WM Merchant). Можно оставлять пустым, но лучше все-таки назначать и, более того, лучше делать его уникальным.
  • lmi_payment_amount - сумма в валюте кошелька (аналог LMI_PAYMENT_AMOUNT в "форме запроса платежа" WM Merchant), разделитель дробной части - точка.
  • lmi_payment_desc - описание покупки (аналог LMI_PAYMENT_DESC в "форме запроса платежа" WM Merchant). Внимание! В отличие от WM Merchant, где этот параметр передается в Win1251, здесь его нужно передавать в UTF8.
  • lmi_clientnumber - идентификатор юзера: номер телефона (без знака "+"), либо email, либо WMID.
  • lmi_clientnumber_type - указатель, что именно было передано в lmi_clientnumber (0 - телефон; 1 - WMID; 2 - email).
  • lmi_sms_type - желаемый способ подтверждения (1 - SMS; 2 - USSD; 4 - только оплата WM-счета; 3 - WebMoney по какому-то ей одной известному алгоритму определит способ подтверждения, предпочтительный для данного юзера).
  • sign, md5, secret_key - это поля для подтверждения аутентичности вашего запроса. Можно использовать ЛЮБОЙ из этих способов, тогда 2 других поля нужно оставить незаполненными. Мы в наших примерах будем использовать md5.

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


    if($step==1) {
    $md5=strtoupper(md5($wmid.$lmi_payee_purse.$lmi_payment_no.$lmi_clientnumber.$lmi_clientnumber_type.$secret_key));
    $lmi_payment_desc=iconv("CP1251", "UTF-8", $lmi_payment_desc);
    $xml="
    <merchant.request>
    <wmid>$wmid</wmid>
    <lmi_payee_purse>$lmi_payee_purse</lmi_payee_purse>
    <lmi_payment_no>$lmi_payment_no</lmi_payment_no>
    <lmi_payment_amount>$lmi_payment_amount</lmi_payment_amount>
    <lmi_payment_desc>$lmi_payment_desc</lmi_payment_desc>
    <lmi_clientnumber>$lmi_clientnumber</lmi_clientnumber>
    <lmi_clientnumber_type>$lmi_clientnumber_type</lmi_clientnumber_type>
    <lmi_sms_type>$lmi_sms_type</lmi_sms_type>
    <secret_key></secret_key>
    <sign></sign>
    <md5>$md5</md5>
    </merchant.request>";
    $resxml=_GetAnswer($XML_addr[201], $xml);
    }


    В поле <md5> передается МД5-хеш строки параметров. Эта строка получается путем склейки параметров, среди которых $secret_key. В эту переменную мы будем передавать SecretKey из настроек нашего торгового кошелька в WM Merchant.

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


    <?xml version="1.0"?>
    <merchant.response>
    <operation wminvoiceid="">
    <realsmstype></realsmstype>
    </operation>
    <retval>0</retval>
    <retdesc></retdesc>
    <userdesc></userdesc>
    </merchant.response>


  • атрибут wminvoiceid - номер счета, выписанного юзеру, в системе WebMoney. Если возникла ошибка, то здесь будет пусто.
  • realsmstype - какой способ подтверждения применен (1 - SMS; 2 - USSD; 4 - SMS и USSD не отправлялись, а только был выписан WM-счет).
    Возникает вопрос, а зачем нам это поле в ответе, ведь способ подтверждения мы сами назначили и передали в поле <lmi_sms_type> запроса. Дело в том, что если в <lmi_sms_type> было передано "3", то WebMoney самостоятельно приняла решение, какой способ подтверждения для юзера предпочтительный. Предположим, WebMoney решила, что предпочтительно отправить SMS, тогда в <realsmstype> мы увидим "1".
  • retval - результат отработки запроса. "0" свидетельствует о том, что запрос успешно отработан, и WM-счет выписан (+ SMS\USSD отправлено). Другое значение retval свидетельствует об ошибке.
  • retdesc - описание ошибки.
  • userdesc - текст на русском языке, который можно транслировать юзеру. В нем WebMoney передает "юзеропонятный" текст ошибки, либо указания к дальнейшим действиям.

    Внимание! wminvoiceid нужно обязательно сохранить хотя бы в сессии, а лучше - в базе данных.

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

    2-й запрос

    Зачем нужен 2-й запрос?
    1) Если юзер оплачивал WM-счет (realsmstype = 4) или подтверждал оплату по USSD (realsmstype = 2), иными словами, если оплата произошла без вашего участия, то 2-й запрос позволяет проверить состояние оплаты.
    2) Если юзер подтверждал оплату по SMS (realsmstype = 1), после чего ввел полученный SMS-код на вашей стороне (на сайте или в программе), то 2-м запросом вы передаете этот SMS-код на сервер WebMoney и тем самым завершаете операцию оплаты.
    3) Если юзер еще не успел оплатить (не подтвердил USSD и не оплатил WM-счет), то 2-й запрос позволяет отменить операцию.

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

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


    <merchant.request>
    <wmid></wmid>
    <lmi_payee_purse></lmi_payee_purse>
    <lmi_clientnumber_code></lmi_clientnumber_code>
    <lmi_wminvoiceid></lmi_wminvoiceid>
    <secret_key></secret_key>
    <sign></sign>
    <md5></md5>
    </merchant.request>


  • wmid и lmi_payee_purse - то же, что и в 1-м запросе.
  • lmi_clientnumber_code - здесь нужно передать SMS-код, полученный от юзера, если оплата подтверждалась по SMS (realsmstype = 1). Если же оплата подтверждалась по USSD (realsmstype = 2) или был только выписан WM-счет (realsmstype = 4), то в этом поле нужно передать "0".
  • lmi_wminvoiceid - номер счета, полученный в 1-м запросе (вы же его сохранили хотя бы в сессии?!).
  • sign, md5, secret_key - это поля для подтверждения аутентичности вашего запроса. Можно использовать ЛЮБОЙ из этих способов, тогда 2 других поля нужно оставить незаполненными. Мы в наших примерах будем использовать md5.

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


    if($step==1) {
    ...
    } elseif($step==2) {
    $md5=strtoupper(md5($wmid.$lmi_payee_purse.$lmi_wminvoiceid.$lmi_clientnumber_code.$secret_key));
    $xml="
    <merchant.request>
    <wmid>$wmid</wmid>
    <lmi_payee_purse>$lmi_payee_purse</lmi_payee_purse>
    <lmi_clientnumber_code>$lmi_clientnumber_code</lmi_clientnumber_code>
    <lmi_wminvoiceid>$lmi_wminvoiceid</lmi_wminvoiceid>
    <secret_key></secret_key>
    <sign></sign>
    <md5>$md5</md5>
    </merchant.request>";
    $resxml=_GetAnswer($XML_addr[202], $xml);
    }


    Поле <md5> здесь формируется точно по такому же принципу, как и в 1-м запросе, только строка подписи формируется из других переменных.

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


    <merchant.response>
    <operation wmtransid="" wminvoiceid="">
    <amount></amount>
    <operdate></operdate>
    <purpose></purpose>
    <pursefrom></pursefrom>
    <wmidfrom></wmidfrom>
    </operation>
    <retval>0</retval>
    <retdesc></retdesc>
    <userdesc></userdesc>
    </merchant.response>


  • атрибут wmtransid - уникальный номер транзакции в системе WebMoney (если операция оплаты прошла успешно).
  • operdate - дата и время проведения этой транзакции на сервере WebMoney (если операция оплаты прошла успешно).
  • pursefrom и wmidfrom - кошелек и WMID плательщика (если операция оплаты прошла успешно).
  • retval - результат отработки запроса. "0" свидетельствует о том, что запрос успешно отработан, и оплата успешно произведена.
  • retdesc и userdesc - смысл у этих полей такой же, как и в 1-м запросе.

    Это, в принципе, уже финал. Осталось лишь обратить ваше внимание на несколько принципиальных моментов по поводу 2-го запроса:

    1) Во-первых, получение retval = 0 и wmtransid > 0 - говорит о том, что оплата успешно состоялась!

    2) Во-вторых, получение retval = 556 означает, что оплата еще не подтверждена (если был USSD или чистый WM-счет), либо SMS-код передан неверный (если было SMS-потверждение).

    3) В-третьих, если вы хотите отменить операцию, то в lmi_clientnumber_code передавайте "-1". Если юзер еще не успел оплатить, то операция будет отменена и в ответе вы увидите retval = 557 или retval = 551. Рекоммендуем дать юзеру кнопку "отметить", чтобы он сам на вашей стороне мог инициировать отмену ранее заказанного платежа.

    4) Даже в том случае, когда юзер подтверждал оплату по USSD, дергать 2-й запрос нужно обязательно! Без этого оплата "не зафиксируется", не будет проведена.

    Функция _WMXML20()

    Функция _WMXML20() для работы с Х20 включена в библиотеку XOWM. Ничего сверхъестественного она не делает. В зависимости от принятого параметра $step (1 или 2) отправляет соответственно 1-й или 2-й запрос. Набор входных параметров у этой функции одинаковый для обеих step (запросов). Он огромен:


    function _WMXML20 ($step, $wmid, $lmi_payee_purse, $lmi_payment_no, $lmi_payment_amount, $lmi_payment_desc, $lmi_clientnumber, $lmi_clientnumber_type, $lmi_sms_type, $lmi_clientnumber_code, $lmi_wminvoiceid, $secret_key) {
    ...
    return $result;
    }


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

    $res=_WMXML20($step, $wmid, $lmi_payee_purse, $lmi_payment_no, $lmi_payment_amount, $lmi_payment_desc, $lmi_clientnumber, $lmi_clientnumber_type, $lmi_sms_type, "", "", $secretkey);

    А вот пример вызова для 2-го запроса. Пустуют $lmi_payment_no, $lmi_payment_amount, $lmi_payment_desc, $lmi_clientnumber, $lmi_clientnumber_type, $lmi_sms_type:

    $res=_WMXML20($step, $wmid, $lmi_payee_purse, "", "", "", "", "", "", $lmi_clientnumber_code, $lmi_wminvoiceid, $secretkey);

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

    Если вы будете использовать библиотеку XOWM и не хотите читать предыдущие статьи нашего цикла о XML-интерфейсах, то сразу даём подсказку: для Х20 нужно в блоке настроек прописать $Global_WMID и $Path_Certs.

    Для работы библиотеки нужны расширения PHP: simplexml, iconv, curl.

    Логика со стороны клиента

    Здесь мы продемонстрировали работу Х20 в реализации на PHP. Не очень оригинально, тем не менее, понять логику вполне можно.

    А логика такая.

    1) Демонстрируем юзеру, сколько и за что он сейчас будет платить.

    V

    2) Юзер выбирает, как он хочет идентифицироваться в системе WebMoney (email, телефон, WMID) и как он хочет подтвердить оплату (SMS, USSD, либо только оплата WM-счета).

    V

    3) По нажатию на кнопку посылаем 1-й запрос.

    V

    4) Если есть ошибки (retval не 0) - отображаем на экране userdesc и просим повторить.
    Если же ошибок нет (retval = 0), то предлагаем юзеру ввести SMS-код (но только если было заказано подтверждение по SMS: realsmstype = 1) и подтвердить оплату.

    V

    5) По нажатию на кнопку посылаем 2-й запрос.

    V

    6) Если есть ошибки (любой retval кроме 0, 557, 551) - отображаем на экране userdesc и просим повторить.
    Если retval = 557 или retval = 551, то понимаем, что оплата была отменена (например, юзер в Кипере отказался от оплаты WM-счета).
    Если же retval = 0 и wmtransid > 0, то оплата подтверждена. Отображаем сообщение об УСПЕХЕ и отрабатываем бизнес-поведение при успешном платеже.

    Вот и всё. Еще на шаге 4 даем юзеру возможность отменить операцию. Тогда посылаем 2-й запрос с lmi_clientnumber_code = -1 , а в ответе получим retval = 557 или retval = 551.
    группа: Материалы
    прочтений: 14083
    Если Вам понравилась статья, подпишитесь на оповещения:

    Комментарии (2)
    Andrey 07.05.12 12:24 #
    В библиотеке XOWM не прописаны $XML_addr[201] и $XML_addr[202]
    niksen 07.05.12 16:01 #
    Andrey сказал(а):
    В библиотеке XOWM не прописаны $XML_addr[201] и $XML_addr[202]



    Fixed, спасибо

    введите этот код
    Мое имя:
    я не зарегистрирован и не хочу
    это моё зарегистрированное имя
    хочу зарегистрировать это имя
    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 [2]
    WebMoney предоставила возможность работы с кошельком, номинированным в молдавских леях. Однако, кошелек этот не совсем обычный.Во-первых, кошелек созд...
    В обновленных Киперах появились регулярные платежи 04.08.16
    Обновилась вся линейка мобильных Киперов (iOS, Android, Windows Phone, MacOs X и BlackBerry OS 10), а также браузерный Keeper Standard.Главное новшест...

       Кофейня (форум)
    Автоматизация masspayment 22.03.17
    Продам премиум домен для кредитного сайта 21.02.17
    СРОЧНО продается обменный пункт 21.02.17

       p2p
    Меняют Qiwi на Skrill 28.03.17
    Меняют 30000 Qiwi на 27000 PayPal (курс:1.11) 28.03.17
    Меняют 10000 Qiwi на 9500 Яндекс.Д (курс:+5.3%) 28.03.17

       WebMoney TOP
    Зарегистрирован PVcash Наш On-line сервис предназначен для тех, кто хочет быстро, безопасно и по выгодному курсу обменять т...
    Зарегистрирован ЧANGE.ME Выгодный обмен PayPal, WebMoney, Яндекс.Денег, QIWI и других валют....
    Зарегистрирован Changedanger.com Сервис денежных обменов Changedanger.com Почему именно мы? Хороший вопрос, на который имеется очень ...

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


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