| Permalink: |
Interface X22
Interface X22. Receiving the ticket of prerequest payment form at merchant.webmoney¶
This interface is available only for the members who use the merchant.wmtransfer.com service (merchant.webmoney.ru)
The interface allows to save the payment request form preliminarily and receive a corresponding ticket with which a direct link to the given payment can be formed. The advantage of this method over the passing of the request form from the merchant's site is, firstly, that a direct link can be sent by any method of communication, and secondly, a direct link with a ticket number excludes
any corruption of the payment parameters (payment parameters, when passed in a form, can be - unintentionally or on purpose - falsified by the user, and they should always be rechecked in the prerequest form or payment notification form).
The result of using the request can be illustrated by the link to an exmaple of a payment with ticket:
https://merchant.wmtransfer.com/lmi/payment.asp?gid=D31A3F81-B953-4F55-B1B4-8DCBA881076F . This link leads to a page of the merchant.webmoney service with already adjusted payment parameters. Such ticket, as the one passed in the 'gid' parameter of this link, can be generated by a merchant for any payment by means of the interface described below.
- URL for sending the request - https://merchant.webmoney.ru/conf/xml/XMLTransSave.asp
- method - POST
- request format:
<merchant.request>
<signtags>
<wmid></wmid>
<validityperiodinhours></validityperiodinhours>
<sign></sign>
<sha256></sha256>
<md5></md5>
<secret_key></secret_key>
</signtags>
<paymenttags>
<lmi_...></lmi_...>
<lmi_...></lmi_...>
<lmi_...></lmi_...>
...
<usertagname1></usertagname1>
<usertagname2></usertagname2>
<usertagname3></usertagname3>
</paymenttags>
</merchant.request>
- request parameters:
| name | purpose | comments |
| wmid | A WM-identifier of the recipient or signature | The WMID that owns the purse that the lmi_payment_no payment was sent to via the merchant.wmtransfer.com service or the WMID that signed the request if the WMSigner authentication method was used. If this WMID is not the owner of the purse that received the payment, there must be a trust issued for generating payment requests on behalf of this identifier |
| validityperiodinhours | ticket validity period | A positive integer defining the number of hours during which the ticket is valid. It can't exceed the period of 744 hours: in that case the ticket becomes invalid. The number of tickets with a specific validity period is unlimited. There is a possibility to create a 'timeless' ticket by defining the validity period as '0', but there can be only one such ticket generated for a WM-purse. If the interface is called repeatedly for the same purse and with null validity period, the previous ticket will be updated with the new data and without changing the ticket number. |
| sign | Query signature | Signing is performed by the wmid keys using WMSigner, based on the parameters: wmid & lmi_payee_purse & lmi_payment_no & validityperiodinhours. Note that if purse specified in 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 specified in lmi_payee_purse at security.wmtransfer.com. If this request authentication option is used, secret_key and md5 parameters should be left empty or omitted altogether. |
| sha256 | Request signature | Requests are signed using the "SHA256" method (http://en.wikipedia.org/wiki/SHA256). The signature is comprised of the following parameters: wmid & lmi_payee_purse & lmi_payment_no & validityperiodinhours & secret_key. If this request authentication option is used, sign, sha256 and secret_key parameters should be left empty or be omitted altogether. Please note that when generating a string for processing by the sha256 algorithm, the system uses the value of the secret word from the purse settings in the merchant.wmtransfer.com service as the value of the secret_key parameter. The request itself must contain ONLY the SHA256 encrypted value, and the secret_key parameter should be undefined or empty!!! |
| md5 | Request signature | Requests are signed using the "MD5" method (http://en.wikipedia.org/wiki/MD5). The signature is comprised of the following parameters: wmid & lmi_payee_purse & lmi_payment_no & validityperiodinhours & secret_key. If this request authentication option is used, sign, sha256 and secret_key parameters should be left empty or be omitted altogether. Please note that when generating a string for processing by the MD5 algorithm, the system uses the value of the secret word from the purse settings in the merchant.wmtransfer.com service as the value of the secret_key parameter. The request itself must contain ONLY the MD5 encrypted value, and the secret_key parameter should be undefined or empty!!! |
| secret_key | secret word | This parameter is used for passing the value of the secret word from the settings of the lmi_payee_purse purse in the merchant.wmtransfer.com service. Please note that when this method is used, https-connection authentication checks (for determining the validity and association with the root server certificate of https://merchant.wmtransfer.com/) aimed at preventing DNS-fishing and other types of fraud are the responsibility of the party sending the request. If this request authentication option is used, sign, sha256 and md5 parameters should be left empty or omitted altogether. |
| lang | may take on the following values: EN-us en-US vi-VN uk-UA | |
| paymenttags | payment request form tags | In the paymenttags tag section exactly the same fields should be specified, as those which would have been passed in a regular payment through the payment request form from the merchant's website. The tags lmi_payee_purse, lmi_payment_amount, lmi_payment_no, lmi_payment_desc should be specified obligatorily. If the lmi_onetimepay tag is equal to 1, then the ticket for a one-time payment (does not work for eternal validityperiodinhours tickets equal to 0). All the other tags described in this section will be processed exactly the same way as if they had been specified in the payment request form. |
- response format:
<?xml version="1.0"?>
<merchant.response>
<transtoken></transtoken>
<validityperiodinhours></validityperiodinhours>
<retval>0</retval>
<retdesc></retdesc>
</merchant.response>
- response parameters:
| name | purpose | comments |
| transtoken | operation token | Transaction token which should be obligatorily passed in the link to the payment request form in the 'gid' parameter as follows: to call in Russian https://merchant.webmoney.ru/lmi/payment.asp?gid=token and in English https://merchant.wmtransfer.com/lmi/payment.asp?gid=token |
| validityperiodinhours | ticket validity period | If the value of validityperiodinhours passed in the request is less than 0, greater than 744, isn't a digit or is omitted at all, than the default value, which is '744', will be assigned as the ticket validity period. |
| retval | error code | A numeric error code which differs from 0 if the execution of the request has generated an error |
| retdesc | error description | A text description for the developers of the seller's application that explains why the request could not be executed successfully |
The members who receive payments via Web Merchant Interface can call the given interface manually at the merchant wizard page
- list of errors:
| retval | retdesc |
| -100 | general request parsing error |
| -2 | merchant.request/wmid is incorrect |
| -2 | merchant.request/lmi_payee_purse is incorrect |
| -2 | merchant.request/lmi_payement_no is incorrect |
| -2 | merchant.request/wmid is incorrect |
| -3 | merchant.request/lmi_payee_purse is incorrect |
| -6 | sign not right |
| -7 | sign not right: PlanStr |
| -7 | SHA256 or MD5 not right:PlanStr(this planstr without secret_key) |
| -8 | internal error:error code |
| 1 | Merchant purse not found:1 |
| 3 | Please use sign or sha256 method for authentication:3 |
| 2 | Please use sign or sha256 method for authentication, and specify secret key in merchant service settings:2 |
| 4 | Merchant wmid not found or security trust for purse is not exists:4 |
| 6 | Merchant wmid not found or security trust for purse is not exists:6 |
| 7 | Payment with lmi_payment_no number not found for this merchant purse:7 |
See also: XML-interfaces