Документация (API)
- Настройка учетной записи интернет-магазина
- Формирование платежной формы
- Защита платежной формы
- Выбор доступных способов оплаты
- Настройка отправки чеков в налоговую в соответствии с ФЗ-54
- Обработка уведомления о результате оплаты
- Настройка отчетов
- Генерация ссылки на оплату
Шаг 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):
|
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 | Язык интерфейса определяется автоматически, но можно задать его:
|
WMI_AUTO_LOCATION | Позволяет показывать пользователю способы оплаты, соответствующие его стране нахождения.
|
WMI_SIGNATURE | Подпись платежной формы, сформированная с использованием «секретного ключа» интернет-магазина. Необходимость проверки этого параметра устанавливается в настройках интернет-магазина. Подробнее в разделе «Защита платежной формы». |
WMI_AUTO_ADJUST_AMOUNT | Позволяет оплатить инвойс даже если сумма платежа отличается от суммы инвойса. Сумма инвойса при этом приравнивается к фактическому платежу.
Параметр нельзя использовать вместе с 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('');
Если параметр 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 RUB | WalletOneRUB |
W1 UAH | WalletOneUAH |
W1 USD | WalletOneUSD |
W1 EUR | WalletOneEUR |
W1 ZAR | WalletOneZAR |
W1 BYR | WalletOneBYR |
W1 GEL | WalletOneGEL |
W1 KZT | WalletOneKZT |
W1 PLN | WalletOnePLN |
W1 TJS | WalletOneTJS |
Яндекс.Деньги | |
Яндекс.Деньги | YandexMoneyRUB |
QIWI Кошелек | |
QIWI Кошелек | QiwiWalletRUB |
B-pay | |
B-Pay | BPayMDL |
CashU | |
CashU | CashUUSD |
EasyPay | |
EasyPay | EasyPayBYR |
LiqPay Money | LiqPayMoney |
LiqPayMoneyUAH | LiqPayMoneyUAH |
Google Wallet | GoogleWalletUSD |
OKPAY | |
OKPAY | OkpayUSD |
OKPAY | OkpayRUB |
Микрозайм Kviku | KvikuRUB |
Мобильная коммерция
Способ оплаты | Идентификатор |
---|---|
Мобильный платеж «Билайн» (Россия) | BeelineRUB |
Мобильный платеж «МТС» (Россия) | MtsRUB |
Мобильный платеж «Мегафон» (Россия) | MegafonRUB |
Мобильный платеж «Tele2» (Россия) | Tele2RUB |
Мобильный платеж «Yota» (Россия) | YotaRUB |
КиевСтар.Мобильные деньги (Украина) | KievStarUAH |
Наличные
Способ оплаты | Идентификатор |
---|---|
Платежные терминалы | CashTerminal |
Платежные терминалы Беларуси | CashTerminalBYR |
Платежные терминалы Грузии | CashTerminalGEL |
Платежные терминалы Казахстана | CashTerminalKZT |
Платежные терминалы Молдовы | CashTerminalMDL |
Платежные терминалы России | CashTerminalRUB |
Платежные терминалы Украины | CashTerminalUAH |
Платежные терминалы Таджикистана | CashTerminalTJS |
Платежные терминалы ЮАР | CashTerminalZAR |
ATM | ATM |
Прием наличных (UAH) | AtmUAH |
Automated Teller Machine | AtmZAR |
Салоны связи | MobileRetails |
Салоны связи «Евросеть» | EurosetRUB |
Салоны связи «Связной» | SvyaznoyRUB |
Салоны связи «Цифроград» | CifrogradRUB |
Салоны связи «Сотовый мир» | CellularWorldRUB |
Отделения банков | BankOffice |
Отделения Сбербанка России | SberbankRUB |
Отделения Сбербанка в Казахстане | SberbankKZT |
Отделения Приватбанка в Украине | PrivatbankUAH |
Отделения Правэкс-Банка в Украине | PravexBankUAH |
Отделения УкрСиббанка в Украине | UkrsibBankUAH |
Отделения Казкоммерцбанка Казахстане | KazkomBankKZT |
Отделения Liberty Bank в Грузии | LibertyBankGEL |
Bank Branch Deposit | BranchZAR |
Отделения Почты России | RussianPostRUB |
Денежные переводы | MoneyTransfer |
Денежные переводы «ЛИДЕР» | LiderRUB |
Денежные переводы Unistream (RUB) | UnistreamRUB |
Денежные переводы Unistream (USD) | UnistreamUSD |
Безналичные
Способ оплаты | Идентификатор |
---|---|
Интернет-банки | OnlineBank |
Интернет-банк «Альфа-Клик» («Альфа-Банк») | AlfaclickRUB |
Интернет-банк «Тинькофф» | TinkoffRUB |
Интернет-банк «Приват24» | Privat24UAH |
Интернет-банк «PSB-Retail» («Промсвязьбанк») | PsbRetailRUB |
Сбербанк ОнЛ@йн | SberOnlineRUB |
Faktura.ru | FakturaruRUB |
Интернет-банк Банка «Русский Стандарт» | RsbRUB |
Единое Расчетное Информационное Пространство (ЕРИП) | EripBYR |
Electronic funds transfer | EftZAR |
Банковский перевод | BankTransfer |
Банковский перевод в китайских юанях | BankTransferCNY |
Банковский перевод в евро | BankTransferEUR |
Банковский перевод в лари | BankTransferGEL |
Банковский перевод в тенге | BankTransferKZT |
Банковский перевод в леях | BankTransferMDL |
Банковский перевод в польских злотах | BankTransferPLN |
Банковский перевод в рублях | BankTransferRUB |
Банковский перевод в гривнах | BankTransferUAH |
Банковский перевод в долларах | BankTransferUSD |
Банковские карты | |
Карты Smartivi | SmartiviGEL |
VISA | VISA |
VISA BYR | CreditCardBYR |
VISA RUB | CreditCardRUB |
VISA UAH | CreditCardUAH |
VISA USD | CreditCardUSD |
VISA EUR | CreditCardEUR |
MasterCard | MasterCard |
MasterCard BYR | CreditCardBYR |
MasterCard RUB | CreditCardRUB |
MasterCard UAH | CreditCardUAH |
MasterCard USD | CreditCardUSD |
MasterCard EUR | CreditCardEUR |
Maestro | Maestro |
Maestro RUB | CreditCardRUB |
МИР | |
МИР | CreditCardRUB |
Тестовые способы оплаты
Способ оплаты | Идентификатор |
---|---|
TestCardEUR | TestCardEUR |
TestCardRUB | TestCardRUB |
TestCardUSD | TestCardUSD |
Шаг 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 | Десятичное число с точностью 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_OPERATIONS | json массив из объектов 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 | Состояние оплаты заказа:
|
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 | Маскированный номер банковской карты |
Примеры реестров платежей:
- 01112012000000-15032013000000.119973638979.csv.zip
- 01112012000000-15032013000000.119973638979.xml.zip
Генерация ссылки на оплату
Сгенерировать ссылку для оплаты заказа можно в специальном разделе сайта.
Возможные коды ошибок
Это не полный перечень возможных ошибок а лишь часто встречающиеся.
Код ошибки | Описание | Комментарий |
---|---|---|
INTERNAL_SERVER_ERROR | Внутренняя ошибка сервера. | При возникновении ошибки данного типа подробности нужно уточнять у технической поддержки Wallet One |
SERVER_ERROR | Внешняя ошибка | Возникает при взаимодействии с платежным шлюзом. Пример — сетевая ошибка |
SUSPECTED_FRAUD | Подозрение на мошеничество | |
INSUFFICIENT_BALANCE_ERROR | Недостаточно средств | На балансе плательщика отсутствует достаточное количество средств для оплаты счета |
OPERATION_LIMIT_EXCEED | Лимит операции | Может возникать при превышении допустимого количества операций, суммы операций либо некоторых внутренних ограничений. |
AUTHORIZATION_ERROR | Ошибка авторизации |