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

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

Шаг 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

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

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

Выставление счетов в Viber

Для формирования и отправки платежных ссылок в Viber поставщик услуг должен быть зарегистрирован в каталоге Wallet One и интегрирован с Wallet One в части осуществления платежей в его пользу.

Формирование и отправка платежных ссылок для поставщиков услуг

Формирование цифровой подписи запроса

Для данного API использование цифровой подписи является обязательным условием.
В запросе необходимо передавать дополнительные заголовки:

Цифровая подпись запроса формируется следующим путем:

1. Конкатенация URL (на который отправляется запрос), идентификатора поставщика услуги (X-Wallet-ProviderId), значения заголовка X-Wallet-Timestamp, тела запроса и секретного ключа поставщика услуги.
2. Получение массива байт данной строки, с учетом использования кодировки UTF-8.
3. Вычисление значения хэш функции SHA256 для полученного массива байт.
4. Кодирование байт рассчитанного значения хеша в Base64 строку.

Пример:

Signature = Base64(SHA256.ComputeHash(UTF8(URL + X-Wallet-ProviderId + X-Wallet-Timestamp + RequestBody + SecretKey)));

Формирование цифровой подписи ответа

На запросы сервер генерирует ответ, который также должен быть подписан. Для этого к ответу добавляются заголовки:

Цифровая подпись ответа формируется следующим путем:

1. Конкатенации значения подписи запроса, заголовка ответа X-Wallet-Timestamp, тела ответа и секретного ключа поставщика услуг.
2. Получение массива байт данной строки, с учетом использования кодировки UTF-8.
3. Вычисление значения хэш функции SHA256 для полученного массива байт.
4. Кодирование байт рассчитанного значения хеша в Base64 строку.

Пример:

Signature = Base64(SHA256.ComputeHash(UTF8(IncomingSignature + X-Wallet-Timestamp + ResponseBody + SecretKey)))

Обработка ошибочных ситуаций

Ошибки возвращаются с HTTP-статус кодом 500.
Ответ с ошибкой включает тело со следующими полями:

{
   "Error":"invalid_signature",
   "ErrorDescription":"invalid signature"
}

Самостоятельная отправка платежной ссылки в Viber поставщиком услуг

1. Запрос на формирование платежной ссылки

POST /ViberBillersGateway/PaymentUrl

Content-type: application/json; charset=utf-8
X-Wallet-ProviderId: 
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==
X-Wallet-Timestamp: 2015-01-07T21:45:33

{
  "Expiry": "2016-12-31T00:00:00",   -- optional
  "Fields": [
    {
      "FieldId": "Phone",
      "Value": "9111111111",
      "IsLocked": true
    },
    {
      "FieldId": "Amount",
      "Value": "1000",
      "IsLocked": false
    }
  ]
}

Описание параметров

2. Ответ содержащий платежную ссылку

HTTP 200
Content-type: application/json; charset=utf-8
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==
X-Wallet-Timestamp: 2015-01-07T21:45:33

{
  "PaymentUrl": "viber://wallet/pay?payload=EE%2FbFfHQGZL50pf2ww4IU36ZYLY7vBQ4NYeUXsM0d1DdRkxiQ7Di9%2Bbjjb7RF2340rQfY5EmgR6lC7iOJw%2Fghoocvplg85RKbJu%2BGeVeDar2l6WrjEpYHsjiHEiCODRV1NpxA%2FBsrvcqEuXEGPmD5g%3D%3D&signature=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA%3D"
}

Описание параметров

3. Сервисное сообщение в систему Viber с платежной ссылкой

Поставщик услуг самостоятельно выполняет передачу платежной ссылки в систему Viber сервисным сообщением.

1. Запрос на отправку платежной ссылки

С содержимым:

POST /ViberBillersGateway/PaymentMessage

Content-type: application/json; charset=utf-8
X-Wallet-ProviderId: 
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==
X-Wallet-Timestamp: 2015-01-07T21:45:33

{
  "RecipientPhone": "7911111111",
  "ServiceMessageType": "CustomPaymentMessage",
  "ServiceMessageData": {
      "Name" : "John Doe",
      "Amount" : "1000"
  },
  "Expiry": "2016-12-31T00:00:00",            -- optional
  "Fields": [
    {
      "FieldId": "Phone",
      "Value": "79111111111",
      "IsLocked": true
    },
    {
      "FieldId": "Amount",
      "Value": "1000",
      "IsLocked": true
    }
  ]
}

Описание параметров

2. Создание сервисного сообщения в системе Viber с платежной ссылкой

В зависимости от настроек поставщика услуг, выполняется либо сборка сообщения по шаблону, либо по параметрам переданным в запросе.
Далее выполняется запрос в систему Viber согласно документации протокола сервисных сообщений.

3. Обработка ответа от системы Viber

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

4. Ответ содержащий URL для платежа

HTTP 200
Content-type: application/json; charset=utf-8
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==
X-Wallet-Timestamp: 2015-01-07T21:45:33

{}

Описание параметров

Оплата с помощью Viber на вашем сайте

Интеграция посредством H2H протокола, позволяет осуществлять прием платежей без перехода плательщика на платежные страницы Wallet One, что в свою очередь позволяет более гибко управлять процессом оплаты, а также производить интеграцию в различные устройства, где по каким-либо причинам, невозможно использование традиционной платежной страницы. В документации приведены общие правила составления запросов и разбора ответов, описание всех методов, а также примеры реальных ситуаций, в которых может быть использовано API.

Общее описание протокола

Взаимодействие с сервисом происходит, путем передачи HTTP запросов на URL (далее в примерах {baseUrl}):

https://wl.walletone.com/checkout/InvoicingApi/{version}/

Формат передаваемых данных в запросах и ответах — JSON. Для поддержания обратной совместимости методов API, во всех запросах требуется передавать номер версии. Актуальная версия API — v1.5.

Авторизация

Все запросы к API должны содержать заголовки, идентифицирующие интернет магазин и подтверждающие подлинность передаваемых данных:

• X-Wallet-UserId — идентификатор интернет магазина
• X-Wallet-Timestamp — дата формирования запроса в часовом поясе UTC+0
• X-Wallet-Signature — цифровая подпись (ЭЦП) запроса

Цифровая подпись запроса формируется путем конкатенации URL, на который отправляется запрос, идентификатора магазина, значения заголовка X-Wallet-Timestamp, тела запроса и секретного ключа магазина. Полученная строка, представленная в кодировке UTF-8, подписывается с помощью выбранного алгоритма ЭЦП, после чего байтовое представление подписи кодируется в Base64:

Signature = Base64(SignatureMethod(UTF8(
URL + MerchantId + Timestamp + RequestBody + SecretKey)));

Пример:

X-Wallet-UserId: 123456789012
X-Wallet-Timestamp: 2015-01-07T21:45:33
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==

Проверка ЭЦП ответов

В качестве дополнительной меры безопасности магазин может проверять подлинность ответов возвращаемых сервером. Для этого, сервис добавляет в каждый ответ заголовки:

• X-Wallet-Timestamp — дата формирования ответа в часовом поясе UTC+0
• X-Wallet-Signature — цифровая подпись ответа.

Цифровая подпись в данном случае формируется путем конкатенации значения подписи полученной в запросе, заголовка ответа X-Wallet-Timestamp, тела ответа и секретного ключа магазина. Полученная строка преобразовывается и хешируется аналогично алгоритму для запросов:

Signature = Base64(SignatureMethod(UTF8(
IncomingSignature + Timestamp + ResponseBody + SecretKey)))

Обработка ошибок

Ошибки возвращаются в HTTP-статусе кодом 4xx и 5xx, согласно RFC 2616. В ответе может содержаться объект ErrorDetails, содержащий дополнительную информацию об ошибке. Например:

{
    "Error": "OPERATION_LIMIT_EXCEEDED",
    "ErrorDescripton": "Превышен лимит на количество операций"
}

Оплата Viber кошельком

Метод создает инвойс с переданными параметрами и резервирует идентификатор платежа. В теле запроса необходимо передать объект содержащий информацию о сумме заказа и способе оплаты.

POST {baseUrl}/invoices
Content-Type: application/json; charset=utf-8
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==
X-Wallet-Timestamp: 2015-01-07T21:45:33
X-Wallet-UserId: 119973638979

{
    "Amount":2.91,
    "CurrencyId":643,
    "PaymentTypeId":"ViberRUB",
    "OrderId":"GQYOE-MJNPO-49623"
}

Ответ:

HTTP/1.1 200 OK
X-Wallet-Timestamp: 2016-08-04T07:43:50
X-Wallet-Signature: 1SVVi80EB1FRp8tvPaGqRQ==

{
    "Invoice": {
        "InvoiceId":341234567891,
        "Amount":2.19,
        "CurrencyId":643,
        "InvoiceStateId":"Created",
        "CreateDate":"2014-06-10T09:54:05.033",
        "UpdateDate":"2014-06-10T09:54:05.033",
        "Payment": {
            "PaymentId":123456,
            "PaymentCode":"341234567891,
            "PaymentCodeType":"InvoiceId"
            "CreateDate":"2014-06-10T09:54:05.033",
            "UpdateDate":"2014-06-10T09:54:05.033",
            "PaymentState":"Created",
            "PaymentTypeId":"ViberRUB"
        }                  
    },  
    "CanSaveAsExternalAccount":"false"
}

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

POST {baseUrl}/payments/{paymentId}/process
Content-type: application/json; charset=utf-8
X-Wallet-Signature: 0J7Qv9C70LDRgtCwINC30LDQutCw0LfQsA==
X-Wallet-Timestamp: 2015-01-07T21:45:33
X-Wallet-UserId: 119973638979

{
    "AuthData": {
        "PhoneNumber":"79228807051",         -- optional
        "NotificationLanguage":"ru-RU",      -- optional
        "SchemeType":"web",                  -- optional
    }
}

Описание параметров

Используемый шаблон сервисного сообщения в Viber:

Ответ для режима 1 (отправка сервисного сообщения в Viber):

HTTP/1.1 200 OK

X-Wallet-Timestamp: 2016-08-04T07:44:29
X-Wallet-Signature: H49Q9kk/OxXCGHMNHNfc3g==

{
    "Payment": {
        "PaymentId":64115070,
        "Amount":2.19,
        "CurrencyId":643,
        "PaymentCode":"345775450837",
        "PaymentCodeType":"InvoiceId",
        "CreateDate":"2015-10-29T21:00:04",
        "UpdateDate":"2015-10-29T21:00:04",
        "PaymentStateId":"AuthRequired",
        "PaymentTypeId":"ViberRUB",
        "ExternalAccountId":null
    },
    "Authorization": {
        "AuthType":"PayerConfirmation"
    }
}

Ответ для режима 2 (получение ссылки на оплату для переадресации пользователя):

HTTP/1.1 200 OK
X-Wallet-Timestamp: 2016-08-04T07:44:29
X-Wallet-Signature: H49Q9kk/OxXCGHMNHNfc3g==

{
    "Payment": {
        "PaymentId":64115070,
        "Amount":2.19,
        "CurrencyId":643,
        "PaymentCode":"345775450837",
        "PaymentCodeType":"InvoiceId",
        "CreateDate":"2015-10-29T21:00:04",
        "UpdateDate":"2015-10-29T21:00:04",
        "PaymentStateId":"AuthRequired",
        "PaymentTypeId":"ViberRUB",
        "ExternalAccountId":null
    },
    "Authorization": {
        "AuthType":"Redirect",
        "HttpForm": {                            
            "Action":"https://wallet.integration.viber.com
/pay?invoiceid=12f74e25-0221-4645-a79c-e6b5e277fced",
            "Method":"GET"
        }
    }
}

Режим 2 имеет смысл использовать для случаев когда пользователь интернет магазина использует мобильное устройство, но это не запрещает использовать режим 1.

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

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

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