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

Документация (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>

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

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

  • 643 — Российские рубли
  • 710 — Южно-Африканские ранды
  • 840 — Американские доллары
  • 978 — Евро
  • 980 — Украинские гривны
  • 398 — Казахстанские тенге
  • 974 — Белорусские рубли
  • 972 — Таджикские сомони
  • 944 — Азербайджанский манат
  • 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Номер мобильного телефона плательщика в международном формате. Например, +71234567890. Значение этого поля будет использоваться в следующих целях:

  • автоматически подставляться в формы некоторых способов оплаты;
  • использоваться для определения страны плательщика;
  • использоваться для поиска счетов клиента в банках и системах электронных денег.
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 — Успешная оплата, 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 + '
');
Убедитесь, что все параметры, которые присутствуют в платежной форме, за исключением WMI_SIGNATURE, участвуют при формировании подписи. Например, если кнопка «submit» имеет установленный атрибут «name», платежная форма также будет содержать значение атрибута «value» этой кнопки.
Убедитесь, что ваша функция MD5 возвращает массив байт, а не их представление в HEX. Если все сделано правильно, длина параметра WMI_SIGNATURE составляет ровно 24 символа.

Если параметр WMI_DESCRIPTION содержит кириллицу, убедитесь, что форма отправляется на сервер в кодировке UTF-8. Для этого форма должна иметь атрибут accept-charset=»UTF-8″.

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

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

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

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

<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="WebMoneyRUB"/>
  <input name="WMI_PTENABLED"      value="WebMoneyUSD"/>
  <input name="WMI_PTENABLED"      value="WebMoneyEUR"/>
  <input name="WMI_PTENABLED"      value="WebMoneyUAH"/>
  <input name="WMI_PTENABLED"      value="WebMoneyGLD"/>
  <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
W1 AZNWalletOneAZN
Viber Кошелек
Viber КошелекViberRUB
Яндекс.Деньги
Яндекс.ДеньгиYandexMoneyRUB
WebMoney
WMRWebMoneyRUB
WMBWebMoneyBYR
QIWI Кошелек
QIWI КошелекQiwiWalletRUB
B-pay
B-PayBPayMDL
CashU
CashUCashUUSD
EasyPay
EasyPayEasyPayBYR
LiqPay MoneyLiqPayMoney
LiqPayMoneyUAHLiqPayMoneyUAH
Google WalletGoogleWalletUSD
OKPAY
OKPAYOkpayUSD
OKPAYOkpayRUB
Микрозайм KvikuKvikuRUB

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

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

Наличные

Способ оплатыИдентификатор
Платежные терминалыCashTerminal
Платежные терминалы БеларусиCashTerminalBYR
Платежные терминалы ГрузииCashTerminalGEL
Платежные терминалы КазахстанаCashTerminalKZT
Платежные терминалы МолдовыCashTerminalMDL
Платежные терминалы РоссииCashTerminalRUB
Платежные терминалы УкраиныCashTerminalUAH
Платежные терминалы ТаджикистанаCashTerminalTJS
Платежные терминалы ЮАРCashTerminalZAR
ATMATM
Прием наличных (UAH)AtmUAH
Standard Bank (ZAR)StandardAtmZAR
Салоны связиMobileRetails
Салоны связи «Евросеть»EurosetRUB
Салоны связи «Связной»SvyaznoyRUB
Салоны связи «Цифроград»CifrogradRUB
Салоны связи «Сотовый мир»CellularWorldRUB
Отделения банковBankOffice
Отделения Сбербанка РоссииSberbankRUB
Отделения Сбербанка в КазахстанеSberbankKZT
Отделения Приватбанка в УкраинеPrivatbankUAH
Отделения Правэкс-Банка в УкраинеPravexBankUAH
Отделения УкрСиббанка в УкраинеUkrsibBankUAH
Отделения Казкоммерцбанка КазахстанеKazkomBankKZT
Отделения Liberty Bank в ГрузииLibertyBankGEL
Отделения Standard Bank в ЮАРStandardBankZAR
Отделения Почты РоссииRussianPostRUB
Денежные переводыMoneyTransfer
Денежные переводы «ЛИДЕР»LiderRUB
Денежные переводы Unistream (RUB)UnistreamRUB
Денежные переводы Unistream (USD)UnistreamUSD

Безналичные

Способ оплатыИдентификатор
Интернет-банкиOnlineBank
Интернет-банк «Альфа-Клик» («Альфа-Банк»)AlfaclickRUB
Интернет-банк «Тинькофф»TinkoffRUB
Интернет-банк «Приват24»Privat24UAH
Интернет-банк «PSB-Retail» («Промсвязьбанк»)PsbRetailRUB
Сбербанк ОнЛ@йнSberOnlineRUB
Faktura.ruFakturaruRUB
Интернет-банк Банка «Русский Стандарт»RsbRUB
Единое Расчетное Информационное Пространство (ЕРИП)EripBYR
SetcomSid ZAR (ЮАР)SetcomSidZAR
Standard Bank EFT (ЮАР)StandardBankEftZ
Банковский переводBankTransfer
Банковский перевод в китайских юаняхBankTransferCNY
Банковский перевод в евро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
МИР
МИРCreditCardRUB

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

Способ оплатыИдентификатор
TestCardEURTestCardEUR
TestCardRUBTestCardRUB
TestCardUSDTestCardUSD

Шаг 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
}
ПараметрТипОписаниеОбязательное требование
TitleСтрока, 128 символовОписание товараДа
QuantityДесятичное число с точностью
3 символа после запятой
Количество товараДа
UnitPriceДесятичное число с точностью
2 символа после запятой
Цена единицы товараДа
SubTotalДесятичное число с точностью
2 символа после запятой
Цена товараДа
TaxTypeСтрока, 9 символов

Ставка НДС, возможные значения:

  • tax_ru_1 —без НДС;
  • tax_ru_2 — НДС по ставке 0%;
  • tax_ru_3 — НДС чека по ставке 10%;
  • tax_ru_4 —НДС чека по ставке 18%;
  • tax_ru_5 — НДС чека по расчетной ставке 10/110;
  • tax_ru_6 — НДС чека по расчетной ставке 18/118.
Да
TaxДесятичное число с точностью
2 символа после запятой
Сумма налогаДа

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

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

После того, как покупатель завершит оплату заказа, Единая касса выполняет 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=" .$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).

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

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

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

В случае если в настройках включен метод формирования ЭЦП, письмо будет содержать второй файл с тем же именем но с расширением «.key» в котором будет содержаться ЭЦП.

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

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

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

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

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

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

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

ЗаголовокОписание заголовка
X-Wallet-TimestampДата формирования запроса в часовом поясе UTC+0. Значение заголовка должно иметь формат yyyy-MM-ddTHH:mm:ss.
X-Wallet-ProviderIdИдентификатор поставщика услуг в каталоге W1
X-Wallet-SignatureЦифровая подпись запроса

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

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

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

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

ЗаголовокОписание заголовка
X-Wallet-TimestampДата формирования запроса в часовом поясе UTC+0. Значение заголовка должно иметь формат yyyy-MM-ddTHH:mm:ss.
X-Wallet-SignatureЦифровая подпись запроса

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

  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"
}
Код ошибкиОписание
INVALID_SIGNATUREОшибка подписи.
INTERNAL_SERVER_ERRORВнутренняя ошибка сервера.
ARGUMENT_ERRORНеверное значение параметра запроса.
VIBER_MESSAGE_FAILUREПроизошел отказ в отправке сервисного сообщения в Viber.
В описании ошибки должен быть передан код ошибки по шлюзу сервисных сообщений Viber.
PROVIDER_ID_NOT_FOUNDПоставщик услуг с переданным идентификатором не найден в каталоге Wallet One.
TEMPLATE_NOT_FOUNDИдентификатор шаблона сообщения не найден.

Самостоятельная отправка платежной ссылки в 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
    }
  ]
}

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

ПараметрОписание параметра запроса
X-Wallet-ProviderIdИдентификатор поставщика услуг в каталоге WalletOne.
X-Wallet-SignatureПодпись запроса.
X-Wallet-TimestampДата формирования запроса в часовом поясе UTC+0. Значение заголовка должно иметь формат yyyy-MM-ddTHH:mm:ss.
Expiry(Опционально) Время после которого данная ссылка будет считаться не валидной. Если отсутствует — данная платежная ссылка не имеет ограничений по времени.
FieldsКоллекция полей платежа.
FieldIdИдентификатор поля платежа в каталоге Wallet One.
ValueЗначение поля платежа.
IsLockedОпределят, возможно ли изменение пользователем значения поля в пользовательском интерфейсе Viber Wallet.

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

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

ПараметрОписание параметра ответа
X-Wallet-SignatureПодпись ответа.
X-Wallet-TimestampДата формирования ответа в часовом поясе UTC+0. Значение заголовка должно иметь формат yyyy-MM-ddTHH:mm:ss.
PaymentUrlПлатежная ссылка для оплаты в Viber Wallet.

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

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

ПараметрОписание параметра запроса
X-Wallet-ProviderIdИдентификатор поставщика услуг.
X-Wallet-SignatureПодпись запроса.
X-Wallet-TimestampВремя выполнения запроса.
RecipientPhoneНомер телефона зарегистрированный в Viber, на который будет выполнена отправка сервисного сообщения.
ServiceMessageTypeИдентификатор шаблона, на базе которого строится сервисное сообщение.
ServiceMessageDataКоллекция параметров для подстановки в шаблон сообщения.
Expiry(Опционально) Время после которого данная ссылка будет считаться не валидной. Если отсутствует — данная платежная ссылка не имеет ограничений по времени.
FieldsКоллекция полей платежа.
(Fields) FieldIdИдентификатор поля платежа.
(Fields) ValueЗначение поля платежа.
(Fields) IsLocked(Опционально) Определят, возможно ли изменение пользователем данного поля платежа при отображении на графическом интерфейсе. Если не передано — данное платежное запрещается изменять пользователю.

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

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

ПараметрОписание параметра ответа
X-Wallet-SignatureПодпись ответа.
X-Wallet-TimestampВремя выполнения ответа.

Оплата с помощью 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
    }
}

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

ПараметрОписание параметра ответа
PhoneNumberПоддерживается 2 режима работы:

  • Передан номер телефона клиента зарегистрированного в Viber: в этом случае пользователю будет направлено сервисное сообщение в Viber.
  • Параметр не передан: в этом случае в ответе на запрос будет сформирована ссылка на которую необходимо переадресовать пользователя для оплаты инвойса.
NotificationLanguageЯзык получаемого пользователем сервисного сообщения. Имеет смысл указывать только если передан номер телефона получателя сообщения.
Поддерживаемые значения:

  • ru-RU
  • en-US
SchemeTypeЗадает схему для ссылки, которая будет возвращена в ответе при отсутствии параметра “PhoneNumber” в запросе. Поддерживаемые значения:

  • web — значение по умолчанию, в ответе будет стандартный http URL который можно открыть в любом браузере
  • mobile — в ответе будет deeplink для мобильной платформы.

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

ПримерRUEN
Текст на кнопкеОплатить 100 руб.Оплатить ${Amount}Pay ${Amount}
Текст сообщенияВам выставлен счет. Получатель средств: Интернет-магазин Ozon.ru. Описание покупки: оплата заказа №1232.Вам выставлен счет. Получатель средств: ${MerchantName}. Описание покупки: ${OrderDescription}.You’ve received an invoice. Merchant: ${MerchantName}. Description of purchase: ${OrderDescription}.
ИзображениеНе передается, или, в зависимости от настройки мерчанта, передается нормализованного лого мерчанта указанное в его настройках

Ответ для режима 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-запрос на адрес, указанный в данных для отправки результатов транзакции в настройках интернет-магазина. Подробно об уведомлении можно ознакомиться по ссылке.

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

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

Код ошибкиОписаниеКомментарий
INTERNAL_SERVER_ERRORВнутренняя ошибка сервера.При возникновении ошибки данного типа подробности нужно уточнять у технической поддержки Wallet One
SERVER_ERRORВнешняя ошибкаВозникает при взаимодействии с платежным шлюзом. Пример — сетевая ошибка
SUSPECTED_FRAUDПодозрение на мошеничество
INSUFFICIENT_BALANCE_ERRORНедостаточно средствНа балансе плательщика отсутствует достаточное количество средств для оплаты счета
OPERATION_LIMIT_EXCEEDЛимит операцииМожет возникать при превышении допустимого количества операций, суммы операций либо некоторых внутренних ограничений.
AUTHORIZATION_ERRORОшибка авторизации