Интерфейс X21

Интерфейс X21. Установка по СМС доверия на оплату в пользу продавца

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

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

Отсутствие необходимости покидать сайт достигается тем, что покупатель подтверждает установку доверия на регулярное списание средств со своего WebMoney-кошелька различными мобильными способами, в данный момент их два:

  • Подтверждение СМС-кодом, присланным на мобильный телефон покупателя
  • Подтверждение USSD-запросом, присланным на мобильный телефон покупателя

Интерфейс работает по тому же принципу идентификации и аутентификации продавца, что и Интерфейс X2 (WMSigner).

На воображаемом примере работу интерфейса можно описать следующим образом. Допустим, покупатель находится в приложении какой-либо игровой консоли и собирается производить регулярную оплату какой-либо услуги (игры).
При выборе способа оплаты через Вебмани покупателю предлагается указать свой номер мобильного телефона, WM-идентификатор (WM-кошелек) , e-mail (либо взять эту информацию из профайла покупателя), чтобы инициировать оплату.
Далее, приложение (серверная сторона приложения продавца) передает эту информацию (вместе с другими параметрами запроса) в первом XML-запросе данного интерфейса. Результатом выполнения этого запроса является поиск покупателя по переданным данным и отправка СМС кода или USSD запроса . СМС- или USSD-запрос предлагает пользователю разрешить продавцу самостоятельно, без участия самого пользователя, производить регулярную оплату в указанном объеме и за указанный период. Например, разрешить оплачивать услуги продавца в объеме не более 30 WM в месяц.
После успешного выполнения этого запроса приложение продавца предлагает покупателю либо ввести подтверждающий код, присланный по СМС, либо подтвердить, что USSD-запрос получен и одобрен. В этом случае приложение продавца осуществляет вызов второго XML-запроса данного интерфейса, в результате выполнения которого производится установка доверия от кошелька покупателя к WMID продавца. В дальнейшем продавец может обычным образом использовать Интерфейс X2.

<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 подписавшего запрос 12 цифр WM-идентификатора, подписывающего запрос с использовании метода аутентификации WMSigner или стандартных сертификатов x.509 (сертификаты WM Keeper WebPro). Именно этому идентификатору будет устанавливаться доверие по управлению кошельком покупателя и именно он будет вызывать потом Интерфейс X2 для совершения регулярных платежей.
lmi_payee_purse WM-кошелек получателя платежа Номер кошелька, на который продавец будет принимать оплату путем перевода средств с кошелька покупателя при помощи интерфейса Х2
lmi_day_limit сумма в день Максимальная сумма платежей, которую продавец сможет перевести от покупателя в течении одного календарного дня в том же типе WM-валюты, что и кошелек продавца lmi_payee_purse. Сумма должна быть больше или равна нулю, дробная часть отделяется точкой. Если сумма равна нулю, то лимита на оплату в день не существует. При этом, как минимум один из трех лимитов (дневной, недельный, месячный) должен быть обязательно указан, т.е. значения всех трех лимитов не должны равняться нулю (недопустимо полное отсутствие лимитов). При этом, максимальная сумма лимита, которую можно установить с помощью данного интерфейса, такая же, как и в п.3 статьи Финансовые ограничения (лимиты) WebMoney Keeper Standard для Кипера Мини с включенным подтверждением операций с помощью SMS или ENUM. Если по каким-либо причинам магазину или сервису понадобится большая сумма, то об этом надо сообщить покупателю, чтобы он поднял лимит самостоятельно в настройках доверия на security.web.money
lmi_week_limit сумма в неделю См. описание lmi_day_limit с заменой календарного дня на календарную неделю.
lmi_month_limit сумма в месяц См. описание lmi_day_limit с заменой календарного дня на календарный месяц.
lmi_clientnumber данные покупателя В этом параметре могут быть указаны на выбор:
- Мобильный телефон с кодом страны и города (допустимы только цифры, без плюсов, скобок и других символов). Например, для России - 79167777777, а для Украины - 380527777777)
- WM-идентификатор покупателя (строго 12 цифр)
- WM-кошелек покупателя (строго большая буква типа WM-кошелька и 12 цифр)
- E-mail покупателя. При этом, интерфейс автоматически найдет WM-идентификатор, с которого может быть произведена оплата покупателем.
lmi_clientnumber_type тип данных Тип переданных в lmi_clientnumber данных. Если передается мобильный телефон, то необходимо указать в этом поле цифру 0, если WMID – цифру 1, если E-mail – цифру 2, если WM-кошелек – цифру 4
lmi_sms_type тип СМС Данное поле определяет способы подтверждения покупателем устанавливаемого доверия. Если в данном поле передать цифру 1, то покупателю будет выслана СМС. Если цифра 2, то покупателю будет передан USSD-запрос.
sign Подпись запроса Подпись производится ключами идентификатора wmid методом WMSigner и формируется из параметров: wmid + lmi_payee_purse + lmi_clientnumber + lmi_clientnumber_type +lmi_sms_type. Обратите внимание, что если кошелек lmi_payee_purse не принадлежит идентификатору wmid, то необходимо чтобы на security.web.money этому идентификатору было установлено доверие на выписку счетов для кошелька lmi_payee_purse.
lang язык ответа В данном параметре передается значение ru-RU или en-US, соответственно, для русского или английского языка интерфейса. Данное значение определяет и язык отправляемых пользователю СМС- или USSD-запросов, и язык ответов в теге userdesc
  • формат ответа:
<?xml version="1.0"?>
<merchant.response>
    <trust purseid="">
        <realsmstype></realsmstype>
    </trust> 
    <slavepurse></slavepurse>
    <slavewmid></slavewmid>
    <retval>0</retval> 
    <retdesc></retdesc>
    <userdesc></userdesc> 
    <smssecureid></smssecureid> 
</merchant.response> 
  • параметры ответа:
название назначение примечание
wmid WMID подписавшего запрос 12 цифр WM-идентификатора, подписывающего запрос
purseid WM-номер запроса Номер запроса в системе WebMoney Transfer для последующей передачи его во второй запрос для проверки или подтверждения установки доверия
realsmstype тип отправки SMS Если в данном поле передана цифра 1 – это значит, что покупателю отправлена SMS. Если цифра 2 – отправлен USSD-запрос
retval номер ошибки Цифровой код ошибки, в случае если выполнение запроса завершилось с ошибкой
retdesc описание ошибки Текстовое описание ошибки для разработчиков приложения продавца, описывающее причины невозможности успешного выполнения запроса
userdesc информация для покупателя В случае ошибки данный текст можно транслировать покупателю как инструкцию, которая поможет ему быстро и правильно понять что необходимо сделать, чтобы избежать ошибки в дальнейшем.
slavepurse кошелек покупателя Необязательный тег. Независимо от того, завершился ли запрос с ошибкой или без, если данный тег присутствует, то в нем указан номер WM-Кошелька покупателя, для которого ранее уже было успешно установлено доверие.
slavewmid WMID покупателя Необязательный тег. Независимо от того, завершился ли запрос с ошибкой или без, если данный тег присутствует, то в нем указан номер WMID покупателя, для которого ранее уже было успешно установлено доверие.
smssecureid Код отслеживания SMS Необязательный тег. Если SMS сообщение было успешно принято к отправке ,то в данном теге находится SMS Secure Id, с помощью которого можно переложить на плечи пользователя процедуру отслеживания доставки SMS или его переотправки, путем встраивания в клиентское ПО или страницу несложного клиентского скрипта использующего данный код. Подробнее по ссылке https://sms.web.money/SmsStatus/HelpV1/Manual?lang=ru#

Задача приложения продавца при успешном вызове первого запроса - получить и сохранить соответствующее устанавливаемому доверию значение purseid.
Без этого значения не может быть вызван второй, подтверждающий установку доверия, запрос. Если по каким-либо причинам (имеются в виду обрывы связи, таймауты и прочие НЕявные или недокументированные ошибки) данное значение не получено или не сохранено, то необходимо вызвать первый запрос повторно (при этом не меняя его!!!). Все параметры повторного запроса должны оставаться без изменений.
Если состояние запроса не будет выяснено и не будет получен purseid, то повторный вызов с изменением какого-либо параметра, например, лимита или кошелька покупателя, приведет к инициации нового доверия и отправке новой СМС (USSD). При этом, потенциально возможна ситуация, когда покупатель подтвердит ОБА доверия, хотя, исходя из логики работы приложения продавца, возможна только установка единственного доверия.

Также, в любой момент приложение продавца может выяснить состояние текущего доверия путем вызова интерфейса X15, если в теге slavewmid ответа присутствует WMID покупателя. Если он присутствует при наличии ошибки, то это означает, что по указанным параметрам уже установлено доверие этим WMID и изменить его нельзя. Если же ошибки нет и значение retval = 0 - это значит, что запрос на изменение текущего доверия принят и отправлена СМС или USSD, но, тем не менее, в данном направлении для WMID slavewmid и WM-кошелька slavepurse доверие уже есть, и после подтверждения оно будет изменено на новые, переданные в запросе значения.

<merchant.request>
    <wmid></wmid>
    <lmi_purseid></lmi_purseid>
    <lmi_clientnumber_code></lmi_clientnumber_code>     
    <sign></sign>
    <lang></lang>
</merchant.request>
  • параметры запроса:
название назначение примечание
wmid WMID подписавшего запрос 12 цифр WM-идентификатора, подписывающего запрос с использовании метода аутентификации WMSigner или стандартных сертификатов x.509 (сертификаты WM Keeper WebPro). Именно этому идентификатору будет устанавливаться доверие по управлению кошельком покупателя и именно он будет вызывать потом Интерфейс X2 для совершения регулярных платежей.
lmi_purseid WM-номер запроса Номер запроса из ответа в предыдущем вызове
lmi_clientnumber_code код покупателя В данном поле передается цифровой код, который покупатель получил на мобильный телефон для подтверждения платежа. Если СМС не отправлялась покупателю (был отправлен USSD запрос), то здесь необходимо передать код со значением 0.
sign Подпись запроса Подпись производится ключами идентификатора wmid методом WMSigner и формируется из параметров: wmid + lmi_purseid +lmi_clientnumber_code.
lang язык ответа В данном параметре передается значение ru-RU или en-US соответственно для русского или английского языка интерфейса. Данное значение определяет и язык отправляемых пользователю СМС (USSD) запросов и язык ответов в теге userdesc
  • формат ответа:
<?xml version="1.0"?>
<merchant.response>
    <trust  id="">
        <slavepurse></slavepurse>
        <slavewmid></slavewmid>
        <masterwmid></masterwmid>
    </trust> 
    <retval>0</retval> 
    <retdesc></retdesc> 
    <userdesc></userdesc> 
    <smssentstate></smssentstate>
</merchant.response> 
  • параметры ответа:
название назначение примечание
trust параметры доверия атрибут id - уникальный номер доверия в системе учета WebMoney
slavepurse кошелек покупателя Номер WM-Кошелька покупателя, для которого было успешно установлено доверие.
slavewmid WMID покупателя Номер WMID покупателя, для которого было успешно установлено доверие.
retval номер ошибки Цифровой код ошибки, в случае если выполнение запроса завершилось с ошибкой
retdesc описание ошибки Текстовое описание ошибки для разработчиков приложения продавца, описывающее причины невозможности успешного выполнения запроса
userdesc информация для покупателя В случае ошибки данный текст можно транслировать покупателю как инструкцию, которая поможет ему быстро и правильно понять, что необходимо сделать чтобы избежать ошибки в дальнейшем
smssentstate статус отправки СМС Если интерфейс завершен с ошибкой и данный тег присутствует в ответе (если СМС или USSD отправлялись, то есть lmi_sms_type = 1,2,3 ) ,то он содержит состояние СМС или USSD
BUFFERED - ожидает отправки
SENDING - отправляется оператору
SENDED- передано оператору
DELIVERED- доставлено
NON_DELIVERED - не доставлено
SUSPENDED - отложено для повтора
HLRPENDING - cообщение отложено в ожидании проверки идентификации SIM карты по данным HLR.
HLRMISMATCH - проверка идентификации SIM карты по данным HLR выявила несовпадение (Подтвердить замену SIm карты пользователь может по ссылке https://security.web.money/asp/resetphs.asp).

Описание ошибок, возвращаемых интерфейсом:

retval retdesc
-100 общая ошибка при разборе запроса
-1 merchant.request/wmid is incorrect
-2 merchant.request/lmi_payee_purse is incorrect
-4 value of merchant.request/lmi_day_limit is incorrect
-4 value of merchant.request/lmi_week_limit is incorrect
-4 value of merchant.request/lmi_month_limit is incorrect
-6 merchant.request/lmi_clientnumber is incorrect, less than 5 symbols or greater than 50 symbols
-7 merchant.request/lmi_clientnumber_type is incorrect, must be specified 1 digit
-7 merchant.request/lmi_clientnumber_type is incorrect, must be specified 0, 1,2, 4
-2 merchant.request/lmi_payee_purse is incorrect
-1 merchant.request/wmid is incorrect
-9 sign not right
-9 sign not right:planstr
-2 merchant.request/lmi_purseid is incorrect, less than 1 symbol or greater than 25 symbols
-22 merchant.request/request_clientnumber_code is incorrect, less than 5 symbols or greater than 25 symbols
601 The specified WMID in wmid tag is not found
602 Specified WMID in wmid tag no access to XML interfaces (X2 etc)
603 Only WMZ, WME, WMG, purses are allowed
604 Merchant purse is not found
605 Specified limits (lmi_day_limit, lmi_week_limit, lmi_month_limit) is wrong
606 The specified WMID is not the owner for lmi_payee_purse and doesn`t have any trust rights
607 Specified in lmi_clientnumber_type is wrong, trust via phone, wmid, purse or e-mail are available
608 The specified WMID in wmid tag already have the trust. The trust is established to the user`s purse, found on the specified phone (wmid, email or purse)
609 See error number 608. Also merchant purse already specified in the existed trust and it differs from the purse in lmi_payee_purse.
610 User purse found by specifed in lmi_clientnumber tag value already have trust to another control WMID for this merchant purse (lmi_payee_purse)
611 The specified identifier does not have the minimum passport level - personal or above
612 User WMID can not be found via specified in lmi_clientnumber phone number
613 Specified in lmi_clientnumber phone number is not verified
614 User purse can not be found via specified in lmi_clientnumber phone number
615 Purse found via specified in lmi_clientnumber phone number is enabled for merchant interface and this trust is not allowed
616 Specified in lmi_clientnumber WMID is not found
617 Specified in lmi_clientnumber WMID has unverified phone number
618 User purse can not be found via specified in lmi_clientnumber WMID
619 Purse found via specified in lmi_clientnumber WMID is used with merchant interface and this trust is not allowed
620 WMID is not found via specified in lmi_clientnumber email:
621 WMID found via specified in lmi_clientnumber email has unverified phone number
622 User purse can not be found via specified in lmi_clientnumber email
623 Purse found via specified in lmi_clientnumber email is used with merchant interface and this trust is not allowed
624 Specified in lmi_clientnumber purse is not found
625 Specified in lmi_clientnumber purse has unverified phone number
626 The specified in lmi_clientnumber purse is enabled for merchant interface and this trust is not allowed
628 Generated SMS text exceed 160 symbols, SMS not sent.
629 SMS (USSD) not sent. SMS center not ready, try again later and if persist contact to support
635 Too many SMS without trust for the specified WMID/email/phone/purse try again after 1 minute
636 Too many SMS without trust for the specified WMID/email/phone/purse try again after 3 hour
640 Trust is initiated earlier, was not found
641 It took more than 24 hours after trust is initiated, try XMLTrustRequest again
642 Less than 2 hour ago, you`ve tried to use wrong SMS code more than 5 times to make a trust, please try again later
643 Specified in lmi_clientnumber_code code is wrong or payment not yet proceed
650 User cancel trust initiated via USSD
651 The trust initiated via USSD not confirm yet by user
652 Databaser error confirm of the trust

Данные тексты ошибок рекомендуется транслировать покупателю как инструкцию к действию, т.е. непосредственно в интерфейсе (приложении) продавца.

retval userdesc
601 Обратитесь, пожалуйста, к продавцу, доверие к его WMID не может быть установлено, так как WMID не найден (указан с ошибкой) или имеет недопустимый для установки доверия статус.
602 Обратитесь, пожалуйста, к продавцу, доверие к его WMID не может быть установлено, так как WMID не найден (указан с ошибкой) или имеет недопустимый для установки доверия статус (нет доступа к XML-интерфейсам).
603 Обратитесь, пожалуйста, к продавцу, только кошельки WMZ, WME, WMG типа допустимы при установке доверия, а ваш продавец хочет получить доверие на кошелек какого-то другого типа.
604 Обратитесь, пожалуйста, к продавцу, его кошелек на который будут переводиться средства не найден (указан с ошибкой) или имеет статус не разрешающий это делать.
605 Обратитесь, пожалуйста, к продавцу, он запрашивает доверие в объеме выше, чем может быть установлено в рамках данного интерфейса.
606 Обратитесь, пожалуйста, к продавцу, он запрашивает доверие на WMID которому не принадлежит кошелек, куда планируется производить оплату, при этом они не связаны между собой никакими отношениями.
607 Обратитесь, пожалуйста, к продавцу, он запрашивает доверие несуществующего типа.
608 Вы указали телефон (WMID, WM-кошелек или E-mail) для которого данному продавцу уже установлено требуемое доверие, посмотрите Ваши текущие настройки доверия на security.web.money
609 Вы указали телефон (WMID, WM-кошелек или E-mail) для которого данному продавцу уже установлено требуемое доверие, но продавец хочет платить на другой кошелек, посмотрите ваши текущие настройки доверия на security.web.money, если необходимо удалите это доверие и попробуйте снова.
610 Ваш кошелек, найденный по указанному телефону (WMID, WM-кошелек или E-mail) уже имеет доверие, но для другого WMID, если необходимо, то посмотрите ваши текущие настройки доверия на security.web.money, удалите это доверие и попробуйте снова.
611 Обратитесь, пожалуйста, к продавцу, его WMID не имеет требуемого для работы с данным интерфейсом аттестата (персональный или выше)
612 По указанному вами телефону мы не смогли найти WMID в Cистеме, обратитесь к сайту passport.web.money чтобы указать и проверить там свой мобильный телефон.
613 По указанному вами телефону мы нашли WMID в Cистеме, но данный телефон не имеет статус проверенного в данном WMID, обратитесь к сайту passport.web.money чтобы проверить там свой мобильный телефон.
614 По указанному вами телефону мы нашли WMID в Cистеме, но в нем нет требуемого продавцу типа кошелька, Вам необходимо создать кошелек нужного типа и пополнить его.
615 По указанному вами телефону мы нашли WMID в Cистеме, но он настроен на работу с сервисом merchant.webmoney.com, вам необходимо, либо завести другой WM-кошелек в данном WMID и пополнить его, либо если вы сочтете это возможным, дать доверие найденному кошельку, но сделать это самостоятельно на сайте security.web.money
616 Указанный вами WMID в Cистеме не найден (указан с ошибкой), либо имеет статус, который не позволяет работать с данным интерфейсом, обратитесь пожалуйста в тех. поддержку Cистемы на support.wmtransfer.com.
617 Указанный вами WMID в Cистеме найден, но указанный в нем мобильный телефон не проверен, обратитесь с вашим WMID к сайту passport.web.money, чтобы проверить мобильный телефон в аттестате.
618 Кошелек требуемого типа не найден в указанном вами WMID, вам необходимо завести и пополнить его и попробовать снова.
619 По указанному вами WMID мы нашли WM-кошелек в Cистеме, но он настроен на работу с сервисом merchant.webmoney.com, Вам необходимо, либо завести другой WM-кошелек в данном WMID и пополнить его, либо если вы сочтете это возможным, дать доверие найденному кошельку, но сделать это самостоятельно на сайте security.web.money
620 По указанному вами E-mail мы не смогли найти WMID в Системе, обратитесь к сайту passport.web.money чтобы указать и проверить там свой E-mail.
621 По указанному вами E-mail мы нашли WMID в Системе, но мобильный телефон в нем не имеет статус проверенного в аттестате WMID, обратитесь к сайту passport.web.money чтобы проверить там свой мобильный телефон.
622 По указанному вами E-mail мы нашли WMID в Системе, но в нем нет требуемого продавцу типа кошелька, вам необходимо создать кошелек нужного типа и пополнить его.
623 По указанному вами E-mail мы нашли WMID в Системе, но он настроен на работу с сервисом merchant.webmoney.com, вам необходимо, либо завести другой WM-кошелек в WMID с указанным E-mail и пополнить его, либо если вы сочтете это возможным, дать доверие найденному кошельку, но сделать это самостоятельно на сайте security.web.money
624 Указанный вами кошелек не найден в Системе, возможно он указан с ошибкой.
625 В WMID, которому принадлежит указанный вами WM-кошелек, не проверен мобильный телефон. Обратитесь с вашим WMID к сайту passport.web.money, чтобы проверить там свой мобильный телефон.
626 Указанный вами WM-кошелек настроен на работу с сервисом merchant.webmoney.com, вам необходимо, либо завести другой WM-кошелек в данном WMID и пополнить его, либо если вы сочтете это возможным, дать доверие найденному кошельку, но сделать это самостоятельно на сайте security.web.money
628 Созданный для отправки на ваш телефон текст СМС имеет слишком большую длину, обратитесь к продавцу, чтобы он настроил вызов интерфейса с минимально требуемым количеством символов в СМС.
629 К сожалению мы не смогли отправить СМС (или USSD) так как СМС-сервис Системы в данный момент не отвечает, попробуйте пожалуйста повторить операцию несколько позднее.
635 Вы уже пробовали отправлять запрос на установку доверия только что, попробуйте, пожалуйста, в следующий раз не ранее чем через 1 минуту.
636 Вы уже пробовали отправлять запрос на установку доверия, причем уже несколько раз, попробуйте пожалуйста в следующий раз не ранее чем через 3 часа.
640 Мы к сожалению не смогли найти указанное для подтверждения доверие, пожалуйста попробуйте еще раз все с самого начала и если повторится тоже самое, обратитесь с данной проблемой к своему продавцу.
641 К сожалению уже прошло более 24 часов с момента как Вы сделали запрос на установку доверия, необходимо сделать запрос снова, так как этот запрос подтвердить уже нельзя.
642 В течении 2х часов вы попробовали указать неверный СМС-код уже несколько раз, попробуйте пожалуйста снова позднее.
643 Указанный СМС-код неверен, либо USSD запрос пока вами не подтвержден.
650 Вы отменили запрос на установку доверия по USSD.
651 Запрос на установку доверия по USSD пока Вами не подтвержден.
652 Произошел отказ в установке доверия, обратитесь пожалуйста в тех. поддержку Системы с указанием вводимых вами данных.

см. также XML-интерфейсы