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

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

  1. Налаштування облікового запису Інтернет-магазину
  2. Формування платіжної форми
  3. Захист платіжної форми
  4. Вибір доступних способів оплати
  5. Обробка повідомлення про результаті оплати
  6. Налаштування звітів

Крок 1. Налаштування облікового запису Інтернет – магазину

Після реєстрації облікового запису необхідно вказати інформацію про магазин, яка буде показана клієнтам при оплаті. Зробити це можна в особистому кабінеті у розділі «Налаштування», вкладка «Про магазин»:

Налаштування гаманця

Крок 2. Формування платіжної форми

Після того, як покупець вибере товари на сайті Інтернет – магазину і сформує корзину замовлення, Інтернет-магазин направляє його на сторінку оплати замовлення. Сторінка оплати повинна містити платіжну форму з параметрами замовлення.

Платіжна форма містить ідентифікатор Інтернет – магазину (номер гаманця), суму і валюту замовлення, а також посилання на сторінки Інтернет-магазину, на які буде відправлений покупець після успішної або не успішною оплати, наприклад:

 <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>

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

Ім’я параметраОпис
WMI_MERCHANT_IDІдентифікатор (номер гаманця) Інтернет-магазину, отриманий при реєстрації.
WMI_PAYMENT_AMOUNTСума замовлення — число округлене до 2-х знаків після «коми», як роздільник використовується «точка». Наявність 2-х знаків після «коми» обов’язково.
WMI_CURRENCY_IDІдентифікатор валюти (ISO 4217):

  • 643 — Російські рублі
  • 710 — Південно – Африканські ранди
  • 840 — Американські долари
  • 978 — Євро
  • 980 — Українські гривні
  • 398 — Казахстанські тенге
  • 974 — Білоруські рублі
  • 972 — Таджицькі сомони
  • 985 — Польський злотий

WMI_PAYMENT_NOІдентифікатор замовлення в системі обліку Інтернет-магазину. Значення даного параметра має бути унікальним для кожного замовлення.
WMI_DESCRIPTIONОпис замовлення (список товарів тощо) — відображається на сторінці оплати замовлення, а також в історії платежів покупця. Максимальна довжина 255 символів.
WMI_SUCCESS_URL
WMI_FAIL_URL
Адреси (URL) сторінок Інтернет — магазину, на які буде відправлений покупець після успішної або неуспішною оплати.
WMI_EXPIRED_DATEТермін закінчення оплати. Дата вказується в західноєвропейському часовому поясі (UTC +0) і повинна бути більше поточної (ISO 8601), наприклад: 2013 – 10 – 29T11:39:26.

Зверніть увагу: термін дії рахунку не може превищувати 30 днів з моменту виставлення!
WMI_PTENABLED
WMI_PTDISABLED
За допомогою цих параметрів можна управляти доступними способами оплати. Детальніше в розділі. «Вибір доступних способів оплати».
WMI_RECIPIENT_LOGINЛогін платника за замовчуванням. Значення даного параметра буде автоматично підставлятися в поле логіна при авторизації. Можливі формати: електронна пошта, номер телефону в міжнародному форматі.
WMI_CUSTOMER_PHONEНомер мобільного телефону платника у міжнародному форматі. Наприклад, +380123456789. Значення цього поля буде використано за наступними призначеннями:

  • автоматично підставлятися у форми деяких способів оплати;
  • використовуватись для визначення країни платника;
  • використовуватись для пошуку рахунків клієнта у банках і системах електронних грошей.
WMI_CUSTOMER_FIRSTNAME
WMI_CUSTOMER_LASTNAME
WMI_CUSTOMER_EMAIL
Ім’я, прізвище та e-mail платника. Значення даних параметрів будутьавтоматично підставлятися в форми деяких способів оплати.
WMI_CULTURE_IDМова інтерфейсу визначається автоматично, але можна задати його:

  • ru-RU — російська;
  • en-US — англійська.
WMI_AUTO_LOCATIONДозволяє показувати користувачу способи оплати, що відповідають його країні знаходження.

  • 0 — відображаються способи без прив’язки до країни користувача;
  • 1 — країна користувача і відображення способів визначається за IP.
WMI_SIGNATUREПідпис платіжної форми, сформована з використанням «секретного ключа» Інтернет-магазину. Необхідність перевірки цього параметра встановлюється в настройках Інтернет-магазину. Детальніше в розділі «Захист платіжної форми».
WMI_AUTO_ADJUST_AMOUNTДозволяє оплатити інвойс, навіть якщо сума платежу відрізняється від суми інвойсу. Сума інвойсу при цьому прирівнюється до фактичної суми платежу::

  • 0 — очікувати надходження повної суми інвойсу;
  • 1 — вважати інвойс спаченим при надходженні будь-якої суми.

Параметр неможна використовувати разом з WMI_ORDER_ITEMS.

Всі інші поля платіжної форми, що не мають префікс «WMI_», будуть збережені і передані в Інтернет-магазин.
У уникнення проблем при використанні національних символів при передачі параметра WMI_DESCRIPTION існує можливість кодування параметра рядком BASE64 (UTF-8). Формат передачі: BASE64: <кодоване в BASE64 значення>. Пример: BASE64:0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==

У тестовому режимі використовуються спеціальні платіжні інструменти. Рахунок буде оплачений, але руху грошових коштів по балансу не відбудеться. Види інструментів: TestCardUSD, TestCardEUR, TestCardRUB.

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

Наводимо список карт і відповідних моделей поведінки:

  • 5457 2100 0100 0019 — Успішна оплата, без 3DS
  • 5457 2100 0100 0043 — Успішна оплата, з 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',
    
    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);
    }
  });

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

  console.log('
' + inputs + '
');
Переконайтеся, що всі параметри, які присутні в платіжній формі, за винятком WMI_SIGNATURE, беруть участь при формуванні підпису. Наприклад, якщо кнопка «submit» має встановлений атрибут «name», платіжна форма також буде містити значення атрибута «value» цієї кнопки.
Переконайтеся, що ваша функція MD5 повертає масив байт, а не їх подання до HEX. Якщо все зроблено правильно, довжина параметра WMI_SIGNATURE складає рівно 24 символу.

Якщо параметр WMI_DESCRIPTION містить кирилицю, переконайтеся, що форма відправляється на сервер в кодуванні UTF-8. Для цього форма повинна мати атрибут accept-charset=»UTF-8″.

Крок 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>

Електронні гроші

Спосіб оплатиІдентифікатор
Єдиний гаманецьWalletOne
W1 RUBWalletOneRUB
W1 UAHWalletOneUAH
W1 USDWalletOneUSD
W1 EURWalletOneEUR
W1 ZARWalletOneZAR
W1 BYRWalletOneBYR
W1 GELWalletOneGEL
W1 KZTWalletOneKZT
W1 PLNWalletOnePLN
W1 TJSWalletOneTJS
Яндекс.Гроші
Яндекс.ГрошіYandexMoneyRUB
Unistream Гроші
QIWI Гаманець
QIWI ГаманецьQiwiWalletRUB
B-pay
B-PayBPayMDL
CashU
CashUCashUUSD
EasyPay
EasyPayEasyPayBYR
LiqPay MoneyLiqPayMoney
LiqPayMoneyUAHLiqPayMoneyUAH
Google WalletGoogleWalletUSD
OKPAY
OKPAYOkpayUSD
OKPAYOkpayRUB

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

Спосіб оплатиІдентифікатор
Мобільний платіж «Білайн» (Росія)BeelineRUB
Мобільний платіж «МТС» (Росія)MtsRUB
Мобільний платіж «Мегафон» (Росія)MegafonRUB
Мобільний платіж Tele2 (Росія)Tele2RUB
Мобільний платіж Yota (Росія)YotaRUB
Київстар. Мобільні гроші (Україна)KievStarUAH

Готівкові

Спосіб оплатиІдентифікатор
Платіжні терміналиCashTerminal
Платіжні термінали БілорусіCashTerminalBYR
Платіжні термінали ГрузіїCashTerminalGEL
Платіжні термінали КазахстануCashTerminalKZT
Платіжні термінали МолдовиCashTerminalMDL
Платіжні термінали РосіїCashTerminalRUB
Платіжні термінали УкраїниCashTerminalUAH
Платіжні термінали ТаджикістануCashTerminalTJS
Платіжні термінали ПАРCashTerminalZAR
ATMATM
Прием наличных (UAH)AtmUAH
Automated Teller MachineAtmZAR
Салони зв’язкуMobileRetails
Салони зв’язку «Євромережа»EurosetRUB
Салони зв’язку «Зв’язковий»SvyaznoyRUB
Салони зв’язку «Диксис»DixisRUB
Салони зв’язку «Цифроград»CifrogradRUB
Салони зв’язку «Стільниковий світ»CellularWorldRUB
Відділення банківBankOffice
Відділення Ощадбанку РосіїSberbankRUB
Отделения Сбербанка в КазахстанеSberbankKZT
Відділення Приватбанку в УкраїніPrivatbankUAH
Відділення Правекс-Банку в УкраїніPravexBankUAH
Відділення УкрСіббанку в УкраїніUkrsibBankUAH
Отделения Казкоммерцбанка КазахстанеKazkomBankKZT
Відділення Liberty BankLibertyBankGEL
Отделения Standard Bank в ЮАРStandardBankZAR
Відділення Пошти РосіїRussianPostRUB
Грошові переказиMoneyTransfer
Грошові перекази LEADERLiderRUB
Грошові перекази Unistream (RUB)UnistreamRUB
Грошові перекази Unistream (USD)UnistreamUSD

Безготівкові

Спосіб оплатиІдентифікатор
Інтернет-банкиOnlineBank
Інтернет – банк «Альфа-Клік» («Альфа -Банк»)AlfaclickRUB
TinkoffTinkoffRUB
Інтернет-банк «Приват24»Privat24UAH
Інтернет-банк «PSB-Retail» («Промсвязьбанк»)PsbRetailRUB
Сбербанк ОнЛ@йнSberOnlineRUB
Faktura.ruFakturaruRUB
Интернет-банк Банка «Русский Стандарт»RsbRUB
Единое Расчетное Информационное Пространство (ЕРИП)EripBYR
Electronic funds transferEftZAR
Банківський переказBankTransfer
Банковский перевод в китайских юаняхBankTransferCNY
Банківський переказ y євроBankTransferEUR
Банковский перевод в лариBankTransferGEL
Банковский перевод в тенгеBankTransferKZT
Банковский перевод в леяхBankTransferMDL
Банковский перевод в польских злотахBankTransferPLN
Банківський переказ в рубляхBankTransferRUB
Банківський переказ у гривняхBankTransferUAH
Банківський переказ у доларахBankTransferUSD
Банківські картки
Карты SmartiviSmartiviGEL
VISAVISA
VISA BYRCreditCardBYR
VISA RUBCreditCardRUB
VISA UAHCreditCardUAH
VISA USDCreditCardUSD
VISA EURCreditCardEUR
MasterCardMasterCard
MasterCard BYRCreditCardBYR
MasterCard RUBCreditCardRUB
MasterCard UAHCreditCardUAH
MasterCard USDCreditCardUSD
MasterCard EURCreditCardEUR
MaestroMaestro
Maestro RUBCreditCardRUB
MIRMIR
MIRCreditCardRUB
MIR
MIRCreditCardRUB

Крок 5. Обробка повідомлення про результаті оплати

Після того, як покупець завершить оплату замовлення, Єдина каса виконує POST-запит на «Дані для відправки результату транзакції», зазначений в настройках Інтернет-магазину. Запит містить параметри платіжної форми, інформацію про результат оплати і деякі додаткові параметри:

Ім’я параметраОпис
WMI_MERCHANT_IDІдентифікатор (номер гаманця) Інтернет-магазину
WMI_PAYMENT_AMOUNTСума замовлення
WMI_COMMISSION_AMOUNTСума утриманої комісії
WMI_CURRENCY_IDІдентифікатор валюти замовлення (ISO 4217).
WMI_TO_USER_IDДванадцятизначний номер гаманця платника
WMI_PAYMENT_NOІдентифікатор замовлення в системі обліку Інтернет-магазину
WMI_ORDER_IDІдентифікатор замовлення в системі обліку Єдиної каси.
WMI_DESCRIPTIONОпис замовлення.
WMI_INVOICE_OPERATIONSjson масив з об’єктів INVOICEOPERATION c полями CreateDate, PaymentId, Amount, AmountEntryId. Скоуп інформації про операції в складі інвойсу. Якщо операцій по інвойсу кілька, кожній з них будуть відповідати свої поля. AmountEntryId відповідає TransferId, відображеним у виписці.
WMI_SUCCESS_URL
WMI_FAIL_URL
Адреси (URL) сторінок Інтернет-магазину, на які буде відправлений покупець після успішної або неуспішною оплати
WMI_EXPIRED_DATEТермін закінчення оплати в західноєвропейському часовому поясі (UTC +0)
WMI_CREATE_DATE
WMI_UPDATE_DATE
Дата створення і зміни замовлення в західноєвропейському часовому поясі (UTC +0)
WMI_ORDER_STATEСтан оплати замовлення:

  • Accepted — замовлення оплачений;
WMI_SIGNATUREПідпис повідомлення про оплату, сформована з використанням «секретного ключа» Інтернет-магазину.
WMI_TEST_MODE_INVOICEПараметр, який передається в складі повідомлень, одержуваних при оплаті тестовими способами. За замовчуванням має значення 1.
Всі інші параметри платіжної форми, що не мають префікс «WMI_».

Інтернет-магазин повинен обробити запит оповіщення про результат оплати і повернути відповідь. Обробка запиту для Інтернет-магазину відбувається також, як ніби він отримав 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=" .urlencode($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)
{
  //Конвертація з поточного кодування (UTF-8)
  //необхідна тільки якщо кодування магазину відмінна від Windows-1251
  $value = iconv("utf-8", "windows-1251", $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"]);
}

?>

Крок 6. Налаштування звітів

Для проведення звірки передбачено механізм відправки реєстрів платежів.

Підписатися на розсилку реєстрів платежів можна в особистому кабінеті у вкладці «Магазин», розділ «Інтеграція», як показано на малюнку:

Налаштування гаманця

Також можна вибрати періодичність отримання звірок (щодня, щотижня або щомісяця) та їх формат (xml або csv).

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

Ім’я параметраОпис
IdНомер рахунку
ExternalIdІдентифікатор замовлення в системі обліку Інтернет-магазину.
DirectionНапрям
UserIdДванадцяти значний номер гаманця платника.
CurrencyIdІдентифікатор валюти замовлення (ISO 4217).
AmountСума замовлення
StateСтан рахунку
PaymentDateДата оплати
PaymentTypeIdСпосіб оплати
DescriptionОпис
CommissionAmountСума утриманої комісії
ApprovalCodeКод авторизації банку (лише для платежів банківськими картками)
CardNumberМаскований номер банківської картки

Приклади реєстрів платежів:

У випадку, коли в налаштуваннях увімкнено метод формування ЕЦП, лист буде містити другий файл з тим же ім’ям, але з розширенням «.key», в якому буде міститися ЕЦП.

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

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