Technical documentation

Technical documentation

  1. Online-store account Setup
  2. Payment form settings
  3. Payment form protection
  4. Selection of accessible payment methods
  5. Processing of the payment result notification
  6. Reports configuration
  7. Generate links for payments

Step 1. Online-store account Setup

After you register your online store account with Wallet One service, you must allow the acceptance of payments and provide information about the store, which will be displayed to customers at the time of payment. This can be done in your Private account on the tab “Settings” at “E-commerce” section:


Step 2. Payment form settings

Once the buyer have selected goods from the online store and created a shopping cart order, the online shop sends it to the order payment page.
The payment page must include a payment form indicating order parameters.

Payment forms contain the online store ID (account number), the amount and currency of the order, as well as links to the online store web-site, which will be sent to the buyer after successful or unsuccessful payment. Example:


The payment form can consist of additional parameters that can affect accessible payment methods, expiry date of the order, interface language and so on.
Full list of payment form parameters shown below:

Parameter nameDescription
WMI_MERCHANT_IDOnline store ID (account number), received at registration.
WMI_PAYMENT_AMOUNTOrder amount, showing 2 digits after decimal point. Full stop symbol is used as decimal point. It is compulsory to indicate 2 digits after decimal.
WMI_CURRENCY_IDCurrency ID (ISO 4217):

  • 643 — Russian Rubles
  • 710 — South African Rand
  • 840 — US Dollar
  • 978 — Euro
  • 980 — Ukrainian Hryvnia
  • 398 — Kazakhstani tenge
  • 974 — Belarusian rubles
  • 972 — Tajik Somoni
  • 985 — Polish zloty

WMI_PAYMENT_NOOrder ID in online store’s accounting system. Each order has to have a unique ID number.
WMI_DESCRIPTIONOrder description (List of goods, etc.) is reflected on the order payment page, as well as in payment history of the buyer maximum amount of symbols – 255.
Online store web-pages addresses (URL), where buyer will be directed after successful or unsuccessful payment.
WMI_EXPIRED_DATEThe expiry date of payment. Date is indicated in Western European time zone (UTC+0) and should be more than current date value(ISO 8601),
for example: 2013-11-09T16:18:52.

Please note: invoice validity period may not exceed 30 days after the moment of issue!
These parameters allow you to control available payment methods. Read more in the section
«Selection of available payment methods».
WMI_RECIPIENT_LOGINPayer default login. The value of this parameter will be inserted into login field on authorisation. Possible formats: e-mail, phone number in international format.
WMI_CUSTOMER_PHONE the telephone number of payer in international format. For example, +71234567890. The meaning of this field will be used for:

  • it will be placed automatically in forms of some methods of payment;
  • it will be used for determination of payer’s country;
  • it will be used for search of client’s invoices in banks and systems of e – commerce.
Payer’s firstname, lastname and e-mail. These values will be inserted into fields of some payment type forms.
WMI_CULTURE_IDInterface language is defined automatically, but you can choose to set it:

  • ru-RU — russian;
  • en-US — english.
WMI_AUTO_LOCATIONAllows to show the methods of payment available for user according to his location.

  • 0 — shows the methods regardless of the user’s country;
  • 1 — the user’s country and the display of methods determines according to the IP.
WMI_SIGNATUREPayment form signature, formed using online store’s “secret key”. Requirement to verify this parameter can be set in “online-store” settings. Read more in the section «Payment form Protection».
WMI_AUTO_ADJUST_AMOUNTIt allows to pay for invoice even if payment amount differs from the invoice amount. Besides the invoice amount is equal to the actual payment:

  • 0 — wait for full amount of invoice;
  • 1 — consider invoice paid when any amount is received.

The parameter can not be used together with WMI_ORDER_ITEMS.

Other fields of payment form, indicated without prefix “WMI_”, will be saved and transferred to online-store.

To avoid problems when using national characters parameter WMI_DESCRIPTION, it is possible to encode this parameter in BASE64-string (UTF-8).
Transmission format: BASE64:
Sample: BASE64:RGVtbyBvcmRlciBwYXltZW50

In test mode special payment instrumnets are used. Invoice will be paid, but the movement of funds on the balance will not happened. Types of instruments: TestCardUSD, TestCardEUR, TestCardRUB.

Parameters CardholderName, ExpiredDate, CVV meet the general conditions of validation. Parameter Email is obligatory (can be transferred as WMI_CUSTOMER_EMAIL).

There is the list of cards and corresponding behaviour models below:

  • 5457 2100 0100 0019 — Successful payment, without 3DS
  • 5457 2100 0100 0043 — Successful payment, with 3DS
  • 4024 0071 0471 6096 — Successful payment, mistakes while return
  • 4847 0000 6602 5312 — Unsuccessful paymnet, wrong card data
  • 5329 3728 6227 2032 — Unsuccessful payment, fraud
  • 4189 0692 9106 7072 — Unsuccessful payment, card is expired
  • 5326 7268 9031 5936 — Unsuccessful payment, wrong owner
  • 5304 4927 9124 6052 — Unsuccessful payment, wrong cvv
  • 5312 2498 1443 1065 — Unsuccessful payment, card is not supported
  • 4539 6574 9236 2685 — Unsuccessful payment, insufficient balance
  • 4716 7187 0398 6236 — Unsuccessful payment, сard authorization error

Each type of error corresponds with code that is returned as part of the request.

Pay attention: It is not possible to pass certain methods in test mode. In this case, the creation of payment form will be finished with mistake.

Step 3. Payment form protection

The online shop’s order parameters are transmitted to Wallet One Checkout via buyer’s web-browser, therefore, to prevent changes in the parameters
on buyer’s side, the online store should make a digest of payment form fields.

The online store should add parameter WMI_SIGNATURE to the payment form, produced using your digital signature algorithm and online store’s “secret key”.

Digital signature algorithm and “secret key” can be set in your personal Wallet One account in Settings tab,
section “Settings” as it is shown in the picture below:


Note! After generating the secret key click the «Save» button at the bottom of the page. This is a necessary condition for the correct operation of electronic signature.

WMI_SIGNATURE parameter is produced by concatenation of the values of other parameters of the form sorted in alphabetical order
of their names (not case sensitive) ending with the online store “secret key”. If the form contains multiple fields with identical names, such fields should be sorted in alphabetical order.

Concatenation of form’s field values and “secret key” (Windows-1251encoded) should be hashed using digital signature algorithm and
it’s bytes should be encoded by Base64.

WMI_SIGNATURE = Base64(Byte(MD5(Windows1251(Sort(Params) + SecretKey))));

Example (PHP):

            usort($val, "strcasecmp");
            $fields[$name] = $val;

    // WMI_SIGNATURE parameter production by 
    // digital signature production of produced message 
    // the MD5 and presenting it in Base64

    uksort($fields, "strcasecmp");
    $fieldValues = "";

    foreach($fields as $value) 
            foreach($value as $v)
                $v = iconv("utf-8", "windows-1251", $v);
                $fieldValues .= $v;
            $value = iconv("utf-8", "windows-1251", $value);
            $fieldValues .= $value;

    $signature = base64_encode(pack("H*", md5($fieldValues . $key)));

    $fields["WMI_SIGNATURE"] = $signature;

    // Production of payment form’s HTML-code

    print "
"; foreach($fields as $key => $val) { if(is_array($val)) foreach($val as $value) { print "$key: "; } else print "$key: "; } print "
"; ?>

Example (Perl):


use Digest::MD5 qw(md5_base64);
use MIME::Base64;

# Online shop’s secret key


my %fields; # Add form’s fields into array of form fields

$fields{"WMI_MERCHANT_ID"}    = "123456789012";
$fields{"WMI_PAYMENT_AMOUNT"} = "100.00";
$fields{"WMI_CURRENCY_ID"}    = "840";
$fields{"WMI_PAYMENT_NO"}     = "12345-001";
$fields{"WMI_DESCRIPTION"}    =  encode_base64("Payment for order #12345-001 in");
$fields{"WMI_EXPIRED_DATE"}   = "2019-12-31T23:59:59";
$fields{"WMI_SUCCESS_URL"}    = "";
$fields{"WMI_FAIL_URL"}       = "";
$fields{"MyShopParam1"}       = "Value1"; # Additional parameters
$fields{"MyShopParam2"}       = "Value2"; # of online store are used
$fields{"MyShopParam3"}       = "Value3"; # to produce digital signature!

# Message production by concatenation of form field values 
# sorted by field name in ascending order.

my $fieldValues = "";

for my $key (sort { lc($a) cmp lc($b) } keys %fields)
  $fieldValues .= $fields{$key};

# WMI_SIGNATURE parameter production by
# digital signature production of produced message
# the MD5 and presenting it in Base64

my $signature = md5_base64($fieldValues, $key) . '==';

# Add WMI_SIGNATURE parameter into array of form’s fields

$fields{"WMI_SIGNATURE"} = $signature;

# Production of payment form’s HTML-code

print "Content-type: text/html; charset=UTF-8nn";

print "
"; for my $key (sort { lc($a) cmp lc($b) } keys %fields) { print "$key: "; } print "

Example (С#):

using System;
using System.Web;
using System.Text;
using System.Security.Cryptography;
using System.Collections.Generic;

public class PaymentForm : IHttpHandler 
  public void ProcessRequest(HttpContext context) 
  // Online shop secret key


    // Add form’s fields into array of form fields

    SortedDictionary formField 
      = new SortedDictionary();

    formField.Add("WMI_MERCHANT_ID",    "123456789012");
    formField.Add("WMI_PAYMENT_AMOUNT", "100.00");
    formField.Add("WMI_CURRENCY_ID",    "643");
    formField.Add("WMI_PAYMENT_NO",     "12345-001");
    formField.Add("WMI_DESCRIPTION",    "BASE64:" + Convert.ToBase64String(Encoding.UTF8.GetBytes("Payment for order #12345-001 in")));
    formField.Add("WMI_EXPIRED_DATE",   "2019-12-31T23:59:59");
    formField.Add("WMI_SUCCESS_URL",    "");
    formField.Add("WMI_FAIL_URL",       "");
    formField.Add("MyShopParam1", "Value1"); // Additional parameters
    formField.Add("MyShopParam2", "Value2"); // of online store take participate
    formField.Add("MyShopParam3", "Value3"); // in signature production!

  // WMI_SIGNATURE parameter production by
  // digital signature production of produced message
  // the MD5 and presenting it in Base64

    StringBuilder signatureData = new StringBuilder();

    foreach (string key in formField.Keys)

    // WMI_SIGNATURE parameter production by
    // digital signature production of produced message
    // the MD5 and presenting it in Base64

  string message = signatureData.ToString() + merchantKey;
    Byte[] bytes = Encoding.GetEncoding(1251).GetBytes(message);
    Byte[] hash = new MD5CryptoServiceProvider().ComputeHash(bytes);
    string signature = Convert.ToBase64String(hash);

    // Add WMI_SIGNATURE parameter into array of form’s fields

    formField.Add("WMI_SIGNATURE", signature);

    // Production of payment form’s HTML-code

    StringBuilder output = new StringBuilder();

"); foreach (string key in formField.Keys) { output.AppendLine(String.Format("{0}: ", key, formField[key])); } output.AppendLine("
"); context.Response.ContentType = "text/html; charset=UTF-8"; context.Response.Write(output.ToString()); } }

Example (Python):

from collections import defaultdict
import binascii
from hashlib import md5

def get_signature(params, secret_key):
    Base64(Byte(MD5(Windows1251(Sort(Params) + SecretKey))))
    params - list of tuples [('WMI_CURRENCY_ID', 643), ('WMI_PAYMENT_AMOUNT', 10)]
    icase_key = lambda s: unicode(s).lower()

    lists_by_keys = defaultdict(list)
    for key, value in params:

    str_buff = ''
    for key in sorted(lists_by_keys, key=icase_key):
        for value in sorted(lists_by_keys[key], key=icase_key):
            str_buff += unicode(value).encode('1251')
    str_buff += secret_key
    md5_string = md5(str_buff).digest()
    return binascii.b2a_base64(md5_string)[:-1]

Example (NodeJS):

  var iconv = require('iconv-lite');
  var crypto = require('crypto');


  var fields = {
    WMI_MERCHANT_ID: '123456789012',
    WMI_PAYMENT_AMOUNT: '100.00',
    WMI_CURRENCY_ID: '643',
    WMI_PAYMENT_NO: '12345-001',
    WMI_DESCRIPTION: 'BASE64:' + new Buffer('Payment for order #12345-001 in').toString('base64'),
    WMI_EXPIRED_DATE: '2019-12-31T23:59:59',
    WMI_FAIL_URL: '',

    MyShopParam1: 'Value1',
    MyShopParam2: 'Value2',
    MyShopParam3: 'Value3'

  var comparator = function(a, b){
    var a = a.toLowerCase();
    var b = b.toLowerCase();
    return a > b ? 1 : a < b ? -1 : 0;

  var createInput = function(name, value){
    return '';

  var inputs = '';
  var values = '';

    var value = fields[name];
    if (Array.isArray(value)) {
      values += value.sort(comparator).join('');
      inputs +={ return createInput(name, val); }).join('');
    else {
      values += value;
      inputs += createInput(name, value);

  inputs += createInput('WMI_SIGNATURE', crypto.createHash('md5').update(iconv.encode(values + key, 'win1251')).digest('base64'));

' + inputs + '
Make sure that all parameters, represented in the payment form, excluding WMI_SIGNATURE parameter, are used in digital signature production.
For example, if the submit button has a «name» attribute, the payment form will contain a «value» attribute for this button.
Make sure that your MD5 function returns byte array, not HEX representation.
If everything was done correctly, WMI_SIGNATURE parameter length will equal 24 symbols.
If WMI_DESCRIPTION parameter contains Cyrillic letters, make sure that form is sent to the server in UTF-8 encoding.
This form must have attribute accept-charset=”UTF-8″.

Step 4. Selection of accessible payment methods

After transferring the payment form to Wallet One Checkout, the buyer can choose a convenient payment method. The Online store can restrict the list
of available payment methods, or explicitly define one of them.

To manage available payment methods WMI_PTENABLED and WMI_PTDISABLED parameters are used.
Each of these fields can be present in the payment form several times, and must contain one of the payment methods.

For example this order can be paid only with CreditCard:

This example shows how to prohibit order payment via W1 system:

Payment systems

Payment methodID
Wallet OneWalletOne
W1 RUBWalletOneRUB
W1 UAHWalletOneUAH
W1 USDWalletOneUSD
W1 EURWalletOneEUR
W1 ZARWalletOneZAR
W1 BYRWalletOneBYR
W1 GELWalletOneGEL
W1 KZTWalletOneKZT
W1 PLNWalletOnePLN
W1 TJSWalletOneTJS
Viber Wallet
Viber WalletViberRUB
QIWI Wallet
QIWI WalletQiwiWalletRUB
LiqPay MoneyLiqPayMoney
Google WalletGoogleWalletUSD
Kviku microloanKvikuRUB

Mobile Commerce

Payment methodID
Beeline (Russia)BeelineRUB
MTS (Russia)MtsRUB
Megafon (Russia)MegafonRUB
Tele2 (Russia)Tele2RUB
Mobile money from Kyivstar (Ukraine)KievStarUAH


Payment methodID
Cash terminalsCashTerminal
Cash terminals in Georgia BelarusCashTerminalBYR
Cash terminals in GeorgiaCashTerminalGEL
Cash terminals in KazakhstanCashTerminalKZT
Cash terminals in MoldovaCashTerminalMDL
Cash terminals in RussiaCashTerminalRUB
Cash terminals in UkraineCashTerminalUAH
Cash terminals in TajikistanCashTerminalTJS
Cash terminals in South AfricaCashTerminalZAR
Receiving cash (UAH)AtmUAH
Automated Teller MachineAtmZAR
Mobile RetailsMobileRetails
Cellular WorldCellularWorldRUB
Bank OfficesBankOffice
Sberbank (Russia) officesSberbankRUB
Sberbank (Kazakhstan) officesSberbankKZT
Privatbank (Ukraine) officesPrivatbankUAH
Pravex Bank (Ukraine) officesPravexBankUAH
UkrsibBank (Ukraine) officesUkrsibBankUAH
Kazkommertsbank (Kazakhstan) officesKazkomBankKZT
Liberty Bank (Georgia) officesLibertyBankGEL
Bank Branch DepositBranchZAR
Russian PostRussianPostRUB
Money TransferMoneyTransfer
LIDER money transfersLiderRUB
Unistream money transfers (RUB)UnistreamRUB
Unistream money transfers (USD)UnistreamUSD


Payment methodID
Alfaclick (Alfabank)AlfaclickRUB
PSB-Retail («Promsvyazbank»)PsbRetailRUB
Sberbank OnlineSberOnlineRUB
Internet-banking of «Russian Standard»RsbRUB
ERIP (Belarus)EripBYR
Electronic funds transferEftZAR
Bank transferBankTransfer
Bank/Wire transfer in Chinese YuanBankTransferCNY
Bank/Wire transfer in euroBankTransferEUR
Bank/Wire transfer in Georgian LariBankTransferGEL
Bank/Wire transfer in tengeBankTransferKZT
Bank/Wire transferBankTransferMDL
Bank/Wire transfer in Polish zlotyBankTransferPLN
Bank/Wire transfer in roublesBankTransferRUB
Bank/Wire transfer in hryvniaBankTransferUAH
Bank/Wire transfer in dollarsBankTransferUSD
Bank cards
Smartivi cardsSmartiviGEL
MasterCard BYRCreditCardBYR
MasterCard RUBCreditCardRUB
MasterCard UAHCreditCardUAH
MasterCard USDCreditCardUSD
MasterCard EURCreditCardEUR
Maestro RUBCreditCardRUB

Step 5. Processing of the payment result notification

Once the buyer completes the payment order, Wallet One Checkout performs POST-request to the «Data to send the results of transaction», indicated the in the online store settings. This request contains parameters of the payment form, information about the result of payment and some additional parameters:

Parameter nameDescription
WMI_MERCHANT_IDOnline store ID (account number).
WMI_CURRENCY_IDCurrency ID (ISO 4217).
WMI_TO_USER_ID12-digit payee wallet number.
WMI_PAYMENT_NOOrder ID in online store’s accounting system.
WMI_ORDER_IDOrder ID in Wallet One Checkout accounting system.
WMI_DESCRIPTIONOrder description.
WMI_INVOICE_OPERATIONSThis parameter is a json array of INVOICEOPERATION objects with the following fields: «CreateDate», «PaymentID», «Amount», and «AmountEntryId». Scope of transaction information is given in the invoice! If there are several transactions on invoice, each of them will have their proper fields. Parameter «AmountEntryId» corresponds to «TransferId» given in the register.
Online store web-pages addresses (URL), where buyer will be directed after successful of unsuccessful payment.
WMI_EXPIRED_DATEThe expiry date of payment, indicated in Western European time zone (UTC+0).
Date of creation and changes of the order in Western European time zone (UTC+0).
WMI_ORDER_STATEOrder payment status:

  •  Accepted  — order is paid;
WMI_SIGNATUREPayment notification signature produced using online shop “secret key”.
WMI_TEST_MODE_INVOICEParameter transfered as part of the notifications received when paying by test methods. The default value is 1.
All other parameters of the payment form that do not have “WMI_” prefix.

The online store should process the request of the payment result notification and send a response. The processing request for the online store should happen the same way as if it had received a POST-request from a standard HTML-form,but instead of pages it should return the following line:



WMI_RESULT=RETRY&WMI_DESCRIPTION=Server is temporary unavailable

Parameter WMI_RESULT in store’s response should contain result of request processing and can accept one of the following values:

  •  OK  — online store has processed the notification and accepted the order.
  •  RETRY  — online store is unable to process notification at the moment. Wallet One Checkout will resend the request later.

In the online store’s response parameter WMI_DESCRIPTION it can contain a comment which will be stored in the logs of Wallet One Checkout.It is recommended to return it in case of an error. The value of this parameter must be encoded in UrlEncode:

For various reasons, Wallet One Checkout may not receive a response from the online store and send a second request, the online-shop must respond to a second request the same way as the first one.

Verify data source

To make sure that the request came from Wallet One Checkout and the information received can be trusted, the online store has to calculate the digital signature of the request using his “secret key” and to compare it with the parameter WMI_SIGNATURE, received in the request.

This can be done using the algorithm described in section “Payment form Protection”, combining all the request parameters values (except WMI_SIGNATURE) in ascending order of their names with the online store’s “secret key” and produce a hash fingerprint of this value by your digital signature algorithm.

Example (PHP):

  if ($name !== "WMI_SIGNATURE") $params[$name] = $value;

// Array sorting in ascending order of key names and join them

ksort($params, SORT_STRING); $values = "";

foreach($params as $name => $value)
  //Conversion of the current encoding (UTF-8)
  //required only if the encoding is different from the store Windows-1251
  $value = iconv("utf-8", "windows-1251", $value);
  $values .= $value;

// Generating a signature to compare with WMI_SIGNATURE

$signature = base64_encode(pack("H*", md5($values . $skey)));

// Comparing generated signature with WMI_SIGNATURE

if ($signature == $_POST["WMI_SIGNATURE"])
  if (strtoupper($_POST["WMI_ORDER_STATE"]) == "ACCEPTED")
    // TODO: Mark order as "paid" in store’s accounting system

    print_answer("Ok", "Order #" . $_POST["WMI_PAYMENT_NO"] . " is paid!");
  // Something wrong, unknown order status received

    print_answer("Retry", "Unknown order status ". $_POST["WMI_ORDER_STATE"]);
  // Signature does not match, probably you have changed online shop settings

  print_answer("Retry", "Wrong digital signature " . $_POST["WMI_SIGNATURE"]);


Step 6. Registry configuration

There is a payment registry mechanism for reconciliation.

You can subscribe to the registry mailing in your Personal Wallet One Account in the Settings tab, section “Online-store” as it is shown in the picture below:


Also you can choose the frequency for receiving reconciliation registries (daily, weekly or monthly) and their format (xml or csv).

Registry parameters:

Parameter nameDescription
IdInvoice ID
ExternalIdOrder ID in online store’s accounting system.
UserId12-digit payee wallet number.
CurrencyIdCurrency ID (ISO 4217).
AmountOrder amount.
StateOrder payment status
PaymentDatePayment date
PaymentTypeIdPayment method
CommissionAmountCommission amount
ApprovalCodeBank authorization code (for payments using bank cards only)
CardNumberMasked bank card number

Registry examples:

In case EDS-generation method is ON, the letter will contain second file under same name but with .key extension, EDS is contained is this file.

Payment link generator

Payment link for the order can be generated here.