Interface X21

Interface X21. Setting trust for merchant payments by SMS

This interface is accessible only to users who already use Interface X2. It is of no interest to merchants, services and other business users of WebMoney who use Interface X2

  • With this interface, a WebMoney user (the "Buyer") can "set trust" one time, allowing recurring deductions of funds to a merchant (through Interface X2), without the user's further intervention. Trust is set directly on the site, service, application, console, etc. (the "Merchant Application"), and the WebMoney user does not need to go to any other websites.

There is no need to leave the website because the buyer allows recurring deduction of funds from the user's WebMoney purse (trust) through various mobile methods. At present, there are two such methods:

  • SMS confirmation: an SMS code is sent to the buyer's cell phone
  • USSD confirmation: a USSD query is sent to the buyer's cell phone

The interface uses the same basic merchant identification/authentication scheme as Interface X2 (WMSigner).

The functioning of the interface can be imagined as follows. Let's say that the buyer is using the application for a gaming console. The buyer is planning to make recurring payments for a service (games, in this case).

When selecting how to pay through WebMoney, the buyer is asked to enter a phone number, WMID (WM purse), and e-mail address (or this information is taken from the buyer's profile) in order to initiate payment.

Then the application (the server side of the merchant application) passes this information (together with the other query parameters) in the first XML query in Interface X21. The query's result: a search is performed for the user with the passed data, and an SMS code or USSD query is sent. The SMS or USD query asks the user to allow the merchant to independently charge, without the user's further intervention, recurring payments in the specified amount for the specified period. For example, this could be to pay up to 30 WMZ for the merchant's services every month.

After the query is successfully completed, the merchant application asks the user to either enter the confirmation code received via SMS or confirm that the USSD query has been received and approved. If so, the merchant application makes a second call for an XML query; this time, trust is established from the buyer's purse to the merchant's WMID. From here on out, the merchant can use Interface X2 as normal.

  • query format:
<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>
  • query parameters:
name purpose comments
wmid WMID that signed the query 12-digit WMID that signed the query using the WMSigner authentication method or the standard x.509 certificates (WM Keeper WebPro certificates). It is for this ID that trust for managing the user's purse will be given, and which will be called later by Interface X2 to perform recurring payments.
lmi_payee_purse WM purse of payment recipient Number of the purse through which the merchant will accept buyer payments with the help of the Х2 interface
lmi_day_limit daily limit Maximum amount that the merchant can transfer from the buyer in one calendar day, in the same WM currency as the purse of the merchant lmi_payee_purse. The amount must be greater than or equal to zero; fractional amounts are indicated with a period. If the amount is zero, then there is no limit on payments per day. At least one of the three limits (daily, weekly, monthly) must be given a value. It is not possible for there to be no limits at all, or that is to say, for all three limits to equal zero. The maximum amount which can be set through this interface is the same as in WebMoney Keeper Standard financial restrictions for Keeper Standard with SMS or ENUM-confirmation of transactions enabled. If for some reason a store or service needs a larger amount, then tell the buyer to raise the limit independently in their trust settings, at security.wmtransfer.com
lmi_week_limit weekly limit Analogous to lmi_day_limit (substituting "calendar week").
lmi_month_limit monthly limit Analogous to lmi_day_limit (substituting "calendar month").
lmi_clientnumber buyer info This parameter can contain, optionally:
- Cell phone, with country code and city/area code (numbers only, without plus signs, parentheses and other symbols). Examples: Russia – 79167777777, Ukraine – 380527777777, U.K. – 44127777777)
- buyer's WMID (12 numbers exactly)
- buyer's WM purse (upper-case letter and 12 numbers)
- buyer's e-mail address. The interface will automatically find the WMID from which buyer payment can be made.
lmi_clientnumber_type data type Type of data passed in lmi_clientnumber. If this is a cell phone, then indicate 0 in this field; for a WMID, indicate 1; for an email address, indicate 2; for a WM purse, indicate 4
lmi_sms_type SMS type This field sets the methods with which the buyer can confirm trust. If this field equals 1, the buyer will receive an SMS. If the field equals 2, the buyer will receive a USSD query.
sign Query signature Signing is performed by the WMID keys using WMSigner, based on the parameters: wmid + lmi_payee_purse + lmi_clientnumber + lmi_clientnumber_type +lmi_sms_type. Note that if lmi_payee_purse does not belong to the WMID, then this ID needs to be granted the trust necessary to issue invoices for the purse lmi_payee_purse at security.wmtransfer.com.
lang response language This parameter passes the values ru-RU and en-US for the Russian- and English-language interfaces, respectively. This value defines the language used in the SMS messages (USSD queries) sent to the user and the language of the responses in the userdesc tag
  • response format:
<?xml version="1.0"?>
<merchant.response>
    <trust purseid="">
        <realsmstype></realsmstype>
    </trust> 
    <retval>0</retval> 
    <retdesc></retdesc>
    <userdesc></userdesc>  
</merchant.response> 
  • response parameters:
name purpose comments
wmid WMID that signed the query 12-digit WMID that signed the query
purseid WM number of the query Number of the query in the WebMoney Transfer system; then passed to the second query for checking or confirming the trust limit
realsmstype SMS sending type If 1 is passed in this field, an SMS was sent to the buyer. If 2 is passed, a USSD query was sent
retval error number Numeric code of the error if the query finished with an error
retdesc error description Textual description of the error for the developers of the merchant application; describes why the query could not be successfully completed
userdesc info for buyer In case of an error, this text can be displayed to the user as instructions, which help to quickly and correctly figure out what to do to avoid such errors.
slavepurse buyer's purse Regardless of whether the error finished with an error or not, if this tag is present, it indicates the number of the WM purse of the buyer for which trust has previously been successfully set.
slavewmid buyer's WMID Regardless of whether the error finished with an error or not, if this tag is present, it indicates the WMID number of the buyer for which trust has previously been successfully set.

When the first query is successfully called, the job of the merchant application is to get and save the purseid value that matches the trust instance that has been set.

Without this value, the second query (which confirms the trust) cannot be called. If this value is not received or not saved for any reason (whether a connection failure, timeout, or other NON-obvious or undocumented errors), then the first query needs to be called again (but without altering it!). All parameters in the repeat query should stay the same.

If the status of the query is unknown and no purseid is obtained, issuing a repeat query with a change in any parameter at all (such as the limit or buyer purse) will start initiation of a new trust limit and will send a new SMS (USSD). Moreover, it is possible that the buyer could confirm BOTH trust limits, even though based on the logic of the merchant app, it is possible to set only one trust limit.

Additionally, the merchant application can get the status of the current trust limit at any time: by calling the X15 interface (second query), if the buyer's WMID is not in the slavewmid tag. If the buyer's WMID is present, even though an error has occurred, this means that the WMID has already established a trust limit with the given parameters and it cannot be changed. If there is no error and the value of retval = 0, then the request to change the current trust limit has been accepted and an SMS or USSD has been sent. All the same, there is already trust in this direction for WMID slavewmid and WM purse slavepurse, and after confirmation, it will be changed to the new values passed in the query.

  • query format:
<merchant.request>
    <wmid></wmid>
    <lmi_purseid></lmi_purseid>
    <lmi_clientnumber_code></lmi_clientnumber_code>     
    <sign></sign>
    <lang></lang>
</merchant.request>
  • query parameters:
name purpose comments
wmid WMID that signed the query 12-digit WMID that signed the query using the WMSigner authentication method or the standard x.509 certificates (WM Keeper WebPro certificates). It is for this ID that trust for managing the user's purse will be given, and which will be called later by Interface X2 to perform recurring payments.
lmi_purseid WM number of the query Number of the query from the response during the previous call
lmi_clientnumber_code buyer code This field passes the digital code which the buyer received via mobile phone for confirming payment. If no SMS was sent to the buyer (a USSD query was sent), then you should pass a code with a value of 0 here.
sign Query signature Signing is performed by the WMID keys using WMSigner, based on the parameters: wmid + lmi_purseid +lmi_clientnumber_code.
lang response language This parameter passes the values ru-RU and en-US for the Russian- and English-language interfaces, respectively. This value defines the language used in the SMS messages (USSD queries) sent to the user and the language of the responses in the userdesc tag
  • response format:
<?xml version="1.0"?>
<merchant.response>
    <trust  id="">
        <slavepurse></slavepurse>
        <slavewmid></slavewmid>
        <masterwmid></masterwmid>
    </trust> 
    <retval>0</retval> 
    <retdesc></retdesc> 
    <userdesc></userdesc> 
</merchant.response> 
  • response parameters:
name purpose comments
trust trust parameters The unique ID for the trust instance in the WebMoney system
slavepurse buyer's purse number of the WM purse of the buyer for which trust has been successfully set.
slavewmid buyer's WMID WMID number of the buyer for which trust has been successfully set.
retval error number Numeric code of the error if the query finished with an error
retdesc error description Textual description of the error for the developers of the merchant application; describes why the query could not be successfully completed
userdesc information for buyer In case of an error, this text can be displayed to the user as instructions, which help to quickly and correctly figure out what to do to avoid such errors

Description of errors returned by the interface:

retval retdesc
-100 general query parsing error
-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

These error messages should be displayed to the buyer as instructions for action, that is, they should be displayed directly in the merchant interface (application).

retval userdesc
601 Please contact the merchant. Trust for the merchant's ID cannot be set since the WMID could not be found (incorrectly specified) or its status does not allow setting trust.
602 Please contact the merchant. Trust for the merchant's ID cannot be set since the WMID could not be found (incorrectly specified) or its status does not allow setting trust (no access to XML interfaces).
603 Please contact the merchant. Only purses of types WMZ, WME, WMG can be used to set trust. The merchant wants to receive trust for a purse of another type.
604 Please contact the merchant. The merchant purse to which funds will be transferred was not found (incorrectly entered) or has an incompatible status.
605 Please contact the merchant. The merchant is asking for a greater trust limit than can be set through this interface.
606 Please contact the merchant. The merchant is asking for trust for an WMID to which the purse for receiving funds does not belong, and there is no relationship between the WMID and the purse.
607 Please contact the merchant. The type of trust required by the merchant does not exist.
608 You have specified a phone number (WMID, WM purse or email address) for which the merchant already has the required trust. Please review your current trust settings at security.wmtransfer.com
609 You have specified a phone number (WMID, WM purse or email address) for which the merchant already has the required trust, but the merchant wants payment to another purse. Please review your current trust settings at security.wmtransfer.com If necessary, delete this trust and try again.
610 The purse found for the indicated phone number (WMID, WM purse or email address) already has trust, but for another WMID. If necessary, review your trust settings at security.wmtransfer.com, delete that trust and try again.
611 Please contact the merchant. The merchant's WMID does not have the passport necessary for using this interface (personal or higher)
612 We could not find a WMID in the system that matches the phone number you entered. Visit passport.wmtransfer.com to enter and verify your cell phone number.
613 We found a WMID in the system for the phone number you entered, but the phone number is not verified for that WMID. Visit passport.wmtransfer.com to verify your cell phone number.
614 We found a WMID in the system for the phone number you entered, but it does not have the type of purse required by the merchant. Create a purse of the necessary type and top it up.
615 We found a WMID in the system for the phone number you entered, but it is configured to work with "merchant.wmtransfer.com". You need to either create another WM purse under this WMID and top it up, or if you think it feasible, grant trust to the found purse, but do this independently at security.wmtransfer.com
616 The WMID you specified was not found in the system (incorrectly specified) or has a status incompatible with this interface. Contact technical support at support.wmtransfer.com.
617 The WMID you specified was found in the system, but the mobile phone indicated for it has not been verified. Log in with your WMID on passport.wmtransfer.com to check the cell phone number in your passport.
618 A purse of the necessary type was not found for the WMID you entered. Create one, top it up, and try again.
619 We found a WM purse in the system for the WMID you specified, but it is configured to work with "merchant.wmtransfer.com". You need to either create another WM purse under this WMID and top it up, or if you think it feasible, grant trust to the found purse, but do this independently at security.wmtransfer.com
620 We could not find a WMID in the system that matches the e-mail address you entered. Visit passport.wmtransfer.com to enter and verify your e-mail address.
621 We found a WMID in the system for the e-mail address you entered, but the cell phone number for it does not have verified status in the WMID passport. Visit passport.wmtransfer.com to verify your cell phone number.
622 We found a WMID in the system for the e-mail address you entered, but it does not have the type of purse required by the merchant. Create a purse of the necessary type and top it up.
623 We found a WMID in the system for the e-mail address you entered, but it is configured to work with "merchant.wmtransfer.com". You need to either create another WM purse under the WMID with this e-mail address and top it up, or if you think it feasible, grant trust to the found purse, but do this independently at security.wmtransfer.com.
624 The purse you specified was not found in the system. Check your information and try again.
625 The WMID to which the specified WM purse belongs does not have a verified cell phone number. Log in with your WMID on passport.wmtransfer.com to verify your cell phone number.
626 The WM purse you specified is configured to work with "merchant.wmtransfer.com". You need to either create another WM purse under this WMID and top it up, or if you think it feasible, grant trust to the found purse, but do this independently at security.wmtransfer.com
628 The SMS text to be sent to your phone is too long. Contact the merchant to call the interface with the smallest amount of SMS characters possible.
629 Unfortunately we could not send an SMS (USSD) since the WebMoney SMS service is currently not responding. Please try again a bit later.
635 You were already trying to send a request for trust just a little bit ago. Please try again in at least one minute.
636 You were already trying to send a request for trust just a little bit ago, and you tried a large number of times. Please try again after three hours.
640 Unfortunately, we could not find the trust indicated for confirmation. Please try starting again from the beginning, and if this error happens again, contact the merchant about the problem.
641 Unfortunately, it has already been over 24 hours since you requested that trust be set. This request cannot be confirmed anymore, so please make your request again.
642 You have tried several times in two hours to indicate an incorrect SMS code. Please try again later.
643 Specified SMS code is invalid or you have not confirmed the USSD query yet.
650 You canceled the request for setting trust over USSD.
651 You have not confirmed the request for setting trust over USSD.
652 Failed to set trust. Contact WebMoney technical support and indicate the data you entered.

See also: XML-interfaces