| Permalink: |
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.
- The first query (for initiating) requests using WM Keeper WinPro key authorization should be sent to https://merchant.webmoney.ru/conf/xml/XMLTrustRequest.asp
- The first query (for initiating) requests using WM Keeper WebPro certificate authorization should be sent to https://merchant.wmtransfer.com/conf/xml/XMLTrustRequest.asp
- method: POST
- 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.
- The second query (for initiating) requests using WM Keeper WinPro key authorization should be sent to https://merchant.webmoney.ru/conf/xml/XMLTrustConfirm.asp
- The second query (for initiating) requests using WM Keeper WebPro certificate authorization should be sent to https://merchant.wmtransfer.com/conf/xml/XMLTrustConfirm.asp
- method: POST
- 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