Документация (API)

1. Настройка учетной записи интернет-магазина
2. Формирование платежной формы
3. Защита платежной формы
4. Выбор доступных способов оплаты
5. Настройка отправки чеков в налоговую в соответствии с ФЗ-54
6. Обработка уведомления о результате оплаты
7. Настройка отчетов
8. Генерация ссылки на оплату

Шаг 1. Настройка учетной записи интернет-магазина

После регистрации учетной записи необходимо указать информацию о магазине, которая будет отображаться клиентам при оплате. Сделать это можно в личном кабинете в разделе «Настройки», вкладка «О магазине»:

Шаг 2. Формирование платежной формы

После того, как покупатель выберет товары на сайте интернет-магазина и сформирует корзину заказа, интернет-магазин направляет его на страницу оплаты заказа. Страница оплаты должна содержать платежную форму с параметрами заказа.
Платежная форма содержит идентификатор интернет-магазина, сумму и валюту заказа, а также ссылки на страницы интернет-магазина, на которые будет отправлен покупатель после успешной или не успешной оплаты, например:

<form method="post" action="https://wl.walletone.com/checkout/checkout/Index">
  <input name="WMI_MERCHANT_ID"    value="123456789012"/>
  <input name="WMI_PAYMENT_AMOUNT" value="100.00"/>
  <input name="WMI_CURRENCY_ID"    value="643"/>
  <input name="WMI_DESCRIPTION"    value="Оплата демонстрационного заказа"/>
  <input name="WMI_SUCCESS_URL"    value="https://myshop.ru/w1/paid.php"/>
  <input name="WMI_FAIL_URL"       value="https://myshop.ru/w1/fail.php"/>
  <input type="submit"/>
</form>

Платежная форма может содержать дополнительные параметры, которые влияют на доступные способы оплаты, срок действия заказа, язык торгового интерфейса и т.п. Полный перечень параметров платежной формы приведен ниже:

В тестовом режиме используются специальные платёжные инструменты. Счёт будет оплачен, но движения денежных средств по балансу не произойдёт. Виды инструментов: TestCardUSD, TestCardEUR, TestCardRUB.

Параметры CardholderName, ExpiredDate, CVV отвечают общим условиям валидации. Обязателен параметр Email (может передаваться как WMI_CUSTOMER_EMAIL).

Приводим список карт и соответствующих моделей поведения:

• 5457 2100 0100 0019 — Успешная оплата, без 3DS
• 5457 2100 0100 0043 — Успешная оплата, c 3DS
• 4024 0071 0471 6096 — Успешная оплата, ошибка при возврате
• 4847 0000 6602 5312 — Неуспешная оплата, неверные данные карты
• 5329 3728 6227 2032 — Неуспешная оплата, фрод
• 4189 0692 9106 7072 — Неуспешная оплата, истёкшая карта
• 5326 7268 9031 5936 — Неуспешная оплата, неверный владелец
• 5304 4927 9124 6052 — Неуспешная оплата, неверный cvv
• 5312 2498 1443 1065 — Неуспешная оплата, карта не поддерживается
• 4539 6574 9236 2685 — Неуспешная оплата, недостаточно денежных средств
• 4716 7187 0398 6236 — Неуспешная оплата, ошибка авторизации карты

Каждому виду ошибки соответствует код, возвращаемый в составе запроса.

Шаг 3. Защита платежной формы

Параметры заказа интернет-магазина передаются в Единую кассу через web-браузер покупателя, поэтому, чтобы предотвратить изменение параметров на стороне покупателя, интернет-магазину необходимо подписать параметры платежной формы.

Для этого интернет-магазину необходимо добавить в платежную форму параметр WMI_SIGNATURE, сформированный с использованием выбранного метода формирования ЭЦП и «секретного ключа» интернет-магазина.

Метод формирования ЭЦП и «секретный ключ» интернет-магазина можно настроить в личном кабинете Единой кассы в разделе «Настройки» во вкладке «Интеграция», как показано на рисунке:

Параметр WMI_SIGNATURE формируется путем объединения значений всех остальных параметров формы в алфавитном порядке их имен (без учета регистра) с добавлением в конец «секретного ключа»
интернет-магазина. Если форма содержит несколько полей с одинаковыми именами, такие поля сортируются в алфавитном порядке их значений.

Полученное после объединения параметров и «секретного ключа» значение, представленное в кодировке Windows-1251, хешируется выбранным методом формирования ЭЦП и его байтовое представление кодируется в Base64.

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

Пример (PHP):

<?php

  //Секретный ключ интернет-магазина
  $key = "XkZMYW56NzVbNV1aekxGNVxvT3xwVHExZ005";

  $fields = array();

  // Добавление полей формы в ассоциативный массив
  $fields["WMI_MERCHANT_ID"]    = "119175088534";
  $fields["WMI_PAYMENT_AMOUNT"] = "100.00";
  $fields["WMI_CURRENCY_ID"]    = "643";
  $fields["WMI_PAYMENT_NO"]     = "12345-001";
  $fields["WMI_DESCRIPTION"]    = "BASE64:".base64_encode("Payment for order #12345-001 in MYSHOP.com");
  $fields["WMI_EXPIRED_DATE"]   = "2019-12-31T23:59:59";
  $fields["WMI_SUCCESS_URL"]    = "https://myshop.com/w1/success.php";
  $fields["WMI_FAIL_URL"]       = "https://myshop.com/w1/fail.php";
  $fields["MyShopParam1"]       = "Value1"; // Дополнительные параметры
  $fields["MyShopParam2"]       = "Value2"; // интернет-магазина тоже участвуют
  $fields["MyShopParam3"]       = "Value3"; // при формировании подписи!
  //Если требуется задать только определенные способы оплаты, раскоментируйте данную строку и перечислите требуемые способы оплаты.
  //$fields["WMI_PTENABLED"]      = array("UnistreamRUB", "SberbankRUB", "RussianPostRUB");

  //Сортировка значений внутри полей
  foreach($fields as $name => $val)
  {
      if(is_array($val))
      {
          usort($val, "strcasecmp");
          $fields[$name] = $val;
      }
  }

  // Формирование сообщения, путем объединения значений формы,
  // отсортированных по именам ключей в порядке возрастания.
  uksort($fields, "strcasecmp");
  $fieldValues = "";

  foreach($fields as $value)
  {
      if(is_array($value))
          foreach($value as $v)
          {
              //Конвертация из текущей кодировки (UTF-8)
              //необходима только если кодировка магазина отлична от Windows-1251
              $v = iconv("utf-8", "windows-1251", $v);
              $fieldValues .= $v;
          }
      else
      {
          //Конвертация из текущей кодировки (UTF-8)
          //необходима только если кодировка магазина отлична от Windows-1251
          $value = iconv("utf-8", "windows-1251", $value);
          $fieldValues .= $value;
      }
  }

  // Формирование значения параметра WMI_SIGNATURE, путем
  // вычисления отпечатка, сформированного выше сообщения,
  // по алгоритму MD5 и представление его в Base64

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

  //Добавление параметра WMI_SIGNATURE в словарь параметров формы

  $fields["WMI_SIGNATURE"] = $signature;

  // Формирование HTML-кода платежной формы

  print "<form action='https://wl.walletone.com/checkout/checkout/Index' method='POST'>";

  foreach($fields as $key => $val)
  {
      if(is_array($val))
          foreach($val as $value)
          {
              print "$key: <input type='text' name='$key' value='$value'/>";
          }
      else
          print "$key: <input type='text' name='$key' value='$val'/>";
  }

  print "<input type='submit'/></form>";

?>

Пример (Perl):

#!/usr/bin/perl
use Digest::MD5 qw(md5_base64);
use MIME::Base64;

# Секретный ключ интернет-магазина

$key = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

my %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 MYSHOP.com", "");
$fields{"WMI_EXPIRED_DATE"}   = "2019-12-31T23:59:59";
$fields{"WMI_SUCCESS_URL"}    = "https://myshop.com/w1/success.php";
$fields{"WMI_FAIL_URL"}       = "https://myshop.com/w1/fail.php";
$fields{"MyShopParam1"}       = "Value1"; # Дополнительные параметры
$fields{"MyShopParam2"}       = "Value2"; # интернет-магазина тоже участвуют
$fields{"MyShopParam3"}       = "Value3"; # при формировании подписи!

# Формирование сообщения, путем объединения значений формы,
# отсортированных по именам ключей в порядке возрастания.

my $fieldValues = "";

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

# Формирование значения параметра WMI_SIGNATURE, путем
# вычисления отпечатка, сформированного выше сообщения,
# по алгоритму MD5 и представление его в Base64.

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

# Добавление параметра WMI_SIGNATURE в словарь параметров формы.

$fields{"WMI_SIGNATURE"} = $signature;

# Формирование HTML-кода страницы с платежной формой.

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

print "<form action="https://wl.walletone.com/checkout/checkout/Index" method="POST" >";

for my $key (sort { lc($a) cmp lc($b) } keys %fields)
{
  print "$key: <input name="$key" value="$fields{$key}"/>";
}

print "<input type="submit"/></form>n";

Пример (С#):

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)
  {
    // Секретный ключ интернет-магазина

    string merchantKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

    // Добавление полей формы в словарь, сортированный по именам ключей.

    SortedDictionary<string, string> formField
      = new SortedDictionary<string, string>();

    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 MYSHOP.com")));
    formField.Add("WMI_EXPIRED_DATE",   "2019-12-31T23:59:59");
    formField.Add("WMI_SUCCESS_URL",    "https://myshop.com/w1/success.php");
    formField.Add("WMI_FAIL_URL",       "https://myshop.com/w1/fail.php");
    formField.Add("MyShopParam1", "Value1"); // Дополнительные параметры
    formField.Add("MyShopParam2", "Value2"); // магазина тоже участвуют
    formField.Add("MyShopParam3", "Value3"); // при формировании подписи!

    // Формирование сообщения, путем объединения значений формы,
    // отсортированных по именам ключей в порядке возрастания и
    // добавление к нему "секретного ключа" интернет-магазина

    StringBuilder signatureData = new StringBuilder();

    foreach (string key in formField.Keys)
    {
        signatureData.Append(formField[key]);
    }

    // Формирование значения параметра WMI_SIGNATURE, путем
    // вычисления отпечатка, сформированного выше сообщения,
    // по алгоритму MD5 и представление его в Base64

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

    // Добавление параметра WMI_SIGNATURE в словарь параметров формы

    formField.Add("WMI_SIGNATURE", signature);

    // Формирование платежной формы

    StringBuilder output = new StringBuilder();

    output.AppendLine("<form method="POST" action="https://wl.walletone.com/checkout/checkout/Index">");

    foreach (string key in formField.Keys)
    {
        output.AppendLine(String.Format("{0}: <input name="{0}" value="{1}"/>", key, formField[key]));
    }

    output.AppendLine("<input type="submit"/></form>");

    context.Response.ContentType = "text/html; charset=UTF-8";
    context.Response.Write(output.ToString());
  }
}

Пример 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:
          lists_by_keys[key].append(value)

      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]

Пример NodeJS:

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

    // Секретный ключ интернет-магазина
  var key = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';

  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 MYSHOP.com').toString('base64'),
    WMI_EXPIRED_DATE: '2019-12-31T23:59:59',
    WMI_SUCCESS_URL: 'https://myshop.com/w1/success.php',
    WMI_FAIL_URL: 'https://myshop.com/w1/fail.php',
    // Если требуется задать только определенные способы оплаты, раскоментируйте данную строку и перечислите требуемые способы оплаты.
    // WMI_PTENABLED: ['UnistreamRUB', 'SberbankRUB', 'RussianPostRUB'],
    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 = '';

  // Формирование сообщения, путем объединения значений формы,
  // отсортированных по именам ключей в порядке возрастания
  Object.keys(fields).sort(comparator).forEach(function(name){
    var value = fields[name];
    if (Array.isArray(value)) {
      values += value.sort(comparator).join('');
      inputs += value.map(function(val){ return createInput(name, val); }).join('');
    }
    else {
      values += value;
      inputs += createInput(name, value);
    }
  });

  // Формирование значения параметра WMI_SIGNATURE, путем
  // вычисления отпечатка, сформированного выше сообщения,
  // по алгоритму MD5 и представление его в Base64
  inputs += createInput('WMI_SIGNATURE', crypto.createHash('md5').update(iconv.encode(values + key, 'win1251')).digest('base64'));

  //Формирование HTML-кода платежной формы.
  console.log('
' + inputs + '
');

Шаг 4. Выбор доступных способов оплаты

После передачи платежной формы в Единую кассу покупатель может выбрать удобный для него способ оплаты. Интернет-магазин может ограничить список доступных способов оплаты или явно определить один из них.

Для управления доступными способами оплаты используются параметры платежной формы WMI_PTENABLED и WMI_PTDISABLED. Каждый из этих полей может присутствовать в платежной форме несколько раз и должен содержать один из способов оплаты.

Например, этот заказ можно оплатить только CreditCard:

<form method="post" action="https://wl.walletone.com/checkout/checkout/Index" accept-charset="UTF-8">
  <input name="WMI_MERCHANT_ID"    value="123456789012"/>
  <input name="WMI_PAYMENT_AMOUNT" value="100.00"/>
  <input name="WMI_CURRENCY_ID"    value="643"/>
  <input name="WMI_DESCRIPTION"    value="Оплата демонстрационного заказа"/>
  <input name="WMI_PTENABLED"      value="CreditCardRUB"/>
  <input name="WMI_PTENABLED"      value="CreditCardUSD"/>
  <input name="WMI_PTENABLED"      value="CreditCardEUR"/>
  <input name="WMI_PTENABLED"      value="CreditCardUAH"/>
  <input name="WMI_PTENABLED"      value="CreditCardGLD"/>
  <input name="WMI_SUCCESS_URL"    value="https://myshop.ru/w1/paid.php"/>
  <input name="WMI_FAIL_URL"       value="https://myshop.ru/w1/fail.php"/>
  <input type="submit"/>
</form>

Следующий пример показывает, как запретить оплату заказа определенным способом:

<form method="post" action="https://wl.walletone.com/checkout/checkout/Index" accept-charset="UTF-8">
  <input name="WMI_MERCHANT_ID"    value="123456789012"/>
  <input name="WMI_PAYMENT_AMOUNT" value="100.00"/>
  <input name="WMI_CURRENCY_ID"    value="643"/>
  <input name="WMI_DESCRIPTION"    value="Оплата демонстрационного заказа"/>
  <input name="WMI_PTDISABLED"     value="W1RUB"/>
  <input name="WMI_SUCCESS_URL"    value="https://myshop.ru/w1/paid.php"/>
  <input name="WMI_FAIL_URL"       value="https://myshop.ru/w1/fail.php"/>
  <input type="submit"/>
</form>

Электронные деньги

Мобильная коммерция

Наличные

Безналичные

Тестовые способы оплаты

Шаг 5. Настройка отправки чеков в налоговую в соответствии с ФЗ-54

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

• данные плательщика, WMI_CUSTOMER_PHONE и WMI_CUSTOMER_EMAIL (допускается передача только одного из параметров);
• информацию о товаре (услуге), WMI_ORDER_ITEMS.

Параметр WMI_ORDER_ITEMS представляет собой json объект следующей структуры:

[
  {
    "Title": "Position 1",
    "Quantity": 3.00,
    "UnitPrice": 150.00,
    "SubTotal": 450.00,
    "TaxType": "tax_ru_3",
    "Tax": 45.00
  },
  {
    "Title": "Position 2",
    "Quantity": 1.00,
    "UnitPrice": 70.00,
    "SubTotal": 70.00,
    "TaxType": "tax_ru_3",
    "Tax": 7.00
  }
]

Содержит коллекцию объектов, характеризующих конкретный товар в чеке.

Объект товара

{
  "Title": "Position 1",
  "Quantity": 3.000,
  "UnitPrice": 150.00,
  "SubTotal": 450.00,
  "TaxType": "tax_ru_3",
  "Tax": 45.00
}

После успешной оплаты счета указанные данные будут отправлены в налоговую инспекцию.

Шаг 6. Обработка уведомления о результате оплаты

После того, как покупатель завершит оплату заказа, Единая касса выполняет POST-запрос на адрес, указанный в данных для отправки результатов транзакции в настройках интернет-магазина. Запрос содержит параметры платежной формы, информацию о результате оплаты и некоторые дополнительные параметры:

Интернет-магазин должен обработать запрос оповещения о результате оплаты и вернуть ответ. Обработка запроса для интернет-магазина происходит также, как будто он получил POST-запрос от обычной HTML-формы, только вместо страницы он должен вернуть строку следующего содержания:

WMI_RESULT=OK

или

WMI_RESULT=RETRY&WMI_DESCRIPTION=Сервер временно недоступен

Параметр WMI_RESULT в ответе интернет-магазина должен содержать результат обработки запроса и может принимать одно из следующих значений:

•  OK   — все в порядке, интернет-магазин обработал уведомление и принял заказ.
•  RETRY   — интернет-магазин не может в данный момент обработать уведомление. Единая касса повторит запрос позже.

Параметр WMI_DESCRIPTION в ответе интернет-магазина может содержать комментарий, который будет сохранен в логах Единой кассы. Рекомендуется возвращать его в случае ошибки. Значение данного параметра должно быть в кодировке UrlEncode:

#!/usr/bin/php
<?php
  function print_answer($result, $description)
  {
      print "WMI_RESULT=" . strtoupper($result) . "&";
      print "WMI_DESCRIPTION=" .urlencode($description);
      exit();
  }
?>

Проверка источника данных

Для того, чтобы убедиться, что запрос поступил от Единой кассы и поступившей информации можно доверять, интернет-магазину необходимо вычислить цифровую подпись запроса с использованием своего «секретного ключа» и сравнить ее с параметром WMI_SIGNATURE, полученным в запросе.

Сделать это можно по алгоритму, описанному в разделе «Защита платежной формы», объединив все значения параметров запроса (кроме WMI_SIGNATURE) в алфавитном порядке их имен с «секретным ключом» интернет-магазина и вычислив хеш-отпечаток этого значения выбранным методом формирования ЭЦП.

Пример (PHP):

#!/usr/bin/php
<?php

  // Секретный ключ интернет-магазина (настраивается в кабинете)

  $skey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

  // Функция, которая возвращает результат в Единую кассу

  function print_answer($result, $description)
  {
    print "WMI_RESULT=" . strtoupper($result) . "&";
    print "WMI_DESCRIPTION=" .$description;
    exit();
  }

  // Проверка наличия необходимых параметров в POST-запросе

  if (!isset($_POST["WMI_SIGNATURE"]))
    print_answer("Retry", "Отсутствует параметр WMI_SIGNATURE");

  if (!isset($_POST["WMI_PAYMENT_NO"]))
    print_answer("Retry", "Отсутствует параметр WMI_PAYMENT_NO");

  if (!isset($_POST["WMI_ORDER_STATE"]))
    print_answer("Retry", "Отсутствует параметр WMI_ORDER_STATE");

  // Извлечение всех параметров POST-запроса, кроме WMI_SIGNATURE

  foreach($_POST as $name => $value)
  {
    if ($name !== "WMI_SIGNATURE") $params[$name] = $value;
  }

  // Сортировка массива по именам ключей в порядке возрастания
  // и формирование сообщения, путем объединения значений формы

  uksort($params, "strcasecmp"); $values = "";

  foreach($params as $name => $value)
  {

    $values .= $value;
  }

  // Формирование подписи для сравнения ее с параметром WMI_SIGNATURE

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

  //Сравнение полученной подписи с подписью W1

  if ($signature == $_POST["WMI_SIGNATURE"])
  {
    if (strtoupper($_POST["WMI_ORDER_STATE"]) == "ACCEPTED")
    {
      // TODO: Пометить заказ, как «Оплаченный» в системе учета магазина

      print_answer("Ok", "Заказ #" . $_POST["WMI_PAYMENT_NO"] . " оплачен!");
    }
    else
    {
      // Случилось что-то странное, пришло неизвестное состояние заказа

      print_answer("Retry", "Неверное состояние ". $_POST["WMI_ORDER_STATE"]);
    }
  }
  else
  {
    // Подпись не совпадает, возможно вы поменяли настройки интернет-магазина

    print_answer("Retry", "Неверная подпись " . $_POST["WMI_SIGNATURE"]);
  }

?>

Шаг 7. Настройка отчетов

Для проведения сверки предусмотрен механизм отправки реестров платежей.

Подписаться на рассылку реестров платежей можно в личном кабинете во вкладке «Магазин», раздел «Интеграция», как показано на рисунке:

Также можно выбрать периодичность получения сверок (ежедневно, еженедельно или ежемесячно) и их формат (xml или csv).

Формат реестров:

Примеры реестров платежей:

• 01112012000000-15032013000000.119973638979.csv.zip
• 01112012000000-15032013000000.119973638979.xml.zip

Генерация ссылки на оплату

Сгенерировать ссылку для оплаты заказа можно в специальном разделе сайта.

Возможные коды ошибок

Это не полный перечень возможных ошибок а лишь часто встречающиеся.