NAV
JS PHP

Интеграция виджета Itez

ITEZ - быстрый и безопасный способ покупки криптовалюты с банковской карты. Вы можете разместить готовый виджет покупки криптовалюты с банковской карты на своем сайте или интегрировать через наш API.

Шаг 1 - получите реквизиты партнера Itez.

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

Шаг 2 - выберите нужную вам платформу и настройте решение.

Website
WordPress
Landing

Устанавливая виджет на свой ресурс, вы соглашаетесь со следующими правилами.

Реквизиты доступа к сервисам Itez

Для получения реквизитов свяжитесь с вашим персональным менеджером либо заполните данную форму.

Токен партнера Itez

Токен - это уникальная сторока в системе сервисов Itez. При помощи токена идентифицируется партнер Itez и осуществляется доступ к сервисам Itez.

Itez secret

Itez secret - это ключ для формирования и проверки подписи параметров в протоколах сервисов Itez. Itez secret нужен для интеграции виджета на страницу, формирования сообщений API и проверки входящих данных колбэков.

Размещение на web-сайте

...
<script src="https://pay.itez.com/static/main/share/merchant.js"></script>
<script>
function runItezWidget() {
  ItezWidget.run({
    partner_token:'...', 
    target_element:'widget-container',
    timestamp: ...,
    signature: '...'
    }, 'POST');
}
window.onload = runItezWidget;
</script>
...
<div id="widget-container"></div>
...
  1. Подключите https://pay.itez.com/static/main/share/merchant.js
  2. Вызовите ItezWidget.run. Первым параметром этого метода должен быть объект, содержащий настройки виджета.
    Минимальный набор полей этого объекта для запуска:
Параметр Type Description
target_element string ID HTML-элемента на странице. В примере это - <div id="widget-container"></div>.
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Рartner_token, target_element, timestamp и signature являются обязательными полями для запуска. Так же можно настроить виджет при помощи дополнительных параметров.

Параметры виджета

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

Обязательные параметры

Параметр Тип Описание
target_element string ID HTML-элемента на странице. В примере это - <div id="widget-container"></div>.
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Опциональные параметры

Параметр Тип Описание
from_currency string Код конвертируемой валюты (ISO 4217). Например: USD.
from_amount number Сумма в исходной валюте (в минимальных единицах валюты, например 1 USD = 100 минимальных единиц - центов). Если параметр задан, то в виджет в поле ввода будет подставлена сумма из from_amount. From_amount нельзя передавать без параметра from_currency.
to_currency string Код результирующей валюты (аналогично ISO 4217). Например: BTC
to_amount number Сумма в результирующей валюте (в минимальных единицах валюты, для BTC, 1 BTC = 100000000 минимальных единиц - сатоши). Параметр нельзя передавать без to_currency.
to_account string Адрес криптокошелька клиента.
lang string Язык, на котором сгенерированная платежная страница будет открыта пользователю. Язык передается в формате ISO 639-1 alpha-2. Если этот параметр не передается, то по умолчанию используется значение "en".
user_login string Логин клиента в Itez (email-адрес). Если параметр установлен, пользователь не сможет поменять его в виджете.
partner_operation_id string ID операции в партнерской системе.
partner_css string Адрес по которому располагается CSS-файл. С помощью него можно изменять внешний вид виджета. Подробнее...

Обработчики событий

Все обработчики событий являются необязательными параметрами.

Обработчик события Описание
onLoaded Завершение загрузки контента виджета.
onResize Изменение размеров документа внутри iframe-виджета.
onExit Закрытие виджета, параметров нет.
onError Ошибка в работе виджета, которая не позволяет продолжить действия пользователя.
onStarted Работа виджета начата с начальной точки.
onPaymentSent Отправка платежных данных — пользователь нажал на Оплатить.
onOperationCreated Регистрация операции в процессинге.
onOperationSuccess Успешное проведение операции покупки.
onOperationPending Операция в процессе исполнения.
onOperationFail Неуспешное проведение операции покупки.

onLoaded

// Пример.
// Вывод в консоль длины и ширины виджета.
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onLoaded = (data) => {
    console.log('width', data.width);
    console.log('height', data.height);
};
ItezWidget.run(data, 'POST');
// Пример data.
{
    width: 372, 
    height: 352
}

Обработчик события загрузки виджета. Событие генерируется сразу после загрузки на страницу.

На вход обработчик принимает JSON-объект:

Поле Тип Описание
width number Ширина виджета в пикселях.
height number Высота виджета в пикселях.

onResize

// Пример.
// Вывод в консоль длины и ширины виджета
// после изменения размеров. 
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onLoaded = (data) => {
    console.log('width', data.width);
    console.log('height', data.height);
};
ItezWidget.run(data, 'POST');
// Пример data.
{
    width: 372, 
    height: 352
}

Обработчик события. Событие вызывается во время изменения виджетом его размеров. Это происходит когда в виджете меняется набор элементов. Например при прохождении пользователем этапов покупки. В большинстве случаев виджет меняет height.

На вход обработчик принимает JSON-объект:

Поле Тип Описание
width number Ширина виджета в пикселях.
height number Высота виджета в пикселях.

onExit

Обработчик события закрытия виджеиа. Входных параметров нет.

onError

// Пример.
// Вывод в консоль текста ошибки. 
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onError = (data) => console.log('error', data.message);
ItezWidget.run(data, 'POST');
// Пример data.
{
    message: "Application error Network Error"
}

Обработчик ошибки в работе виджета, которая не позволяет продолжить действия пользователя.

На вход обработчик принимает JSON-объект, содержащий поле:

Поле Тип Описание
message string Текст ошибки.

onStarted

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

onPaymentSent

Обработчик события. Событие генерируется когда пользователь нажал "Оплатить". Входных параметров нет.

onOperationCreated

// Пример.
// Вывод в консоль ID операции.
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onOperationCreated = (id) => console.log('operation ID', id);
ItezWidget.run(data, 'POST');
// Пример входного параметра.
id == "1234567890"

Обработчик события регистрации операции в процессинге.

На вход принимает ID операции, тип string.

onOperationSuccess

// Пример.
// Вывод в консоль статуса и ID операции. 
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onOperationSuccess = (data) => {
    console.log('ID', data.operation_info.id);
    console.log('status', data.status);
}
ItezWidget.run(data, 'POST');

Обработчик события успешной покупки. Обработчик вызывается когда статус транзакции становится равным "success".

Обработчик принимает параметр типа operation_data.

onOperationPending

// Пример.
// Вывод в консоль статуса и ID операции. 
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onOperationPending = (data) => {
    console.log('ID', data.operation_info.id);
    console.log('status', data.status);
}
ItezWidget.run(data, 'POST');

Обработчик события. Обработчик вызывается когда статус операции становится равным "pending".

Обработчик принимает параметр типа operation_data.

onOperationFail

// Пример.
// Вывод в консоль статуса и ID операции. 
const data = {
    partner_token: '...',
    target_element: 'widget-container',
    timestamp: ...,
    signature: '...'
};
data.onOperationFail = (data) => {
    console.log('ID', data.operation_info.id);
    console.log('status', data.status);
}
ItezWidget.run(data, 'POST');

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

Обработчик принимает параметр типа operation_data.

Подпись параметров виджета

// Это пример простого web-сервера для node.js.
// Сервер выдает web-страницу на которой расположен только виджет Itez. 

const { createServer } = require('http');
const { createHmac } = require('crypto');

// Ваш токен партнера.
const partner_token = '';
// Itez Secret. 
const itez_secret = '';

// Сождание HTML-страницы
function getDocument() {
  const params = {
    partner_token: partner_token, // partner token
    target_element: 'widget-container', // id html item that contains itez widget
    timestamp: Date.now(), // current time
  };

  const jsonToString = (obj) => {
    return Object.entries(obj)
      .sort()
      .map((items) => `${items[0]}:${items[1]}`)
      .join(';');
  };

  function signHmacSha512(obj, secret) {
    return createHmac('sha512', secret)
      .update(jsonToString(obj))
      .digest('hex');
  }

  // Формирование подписи
  params.signature = signHmacSha512(params, itez_secret);
  // signed - JSON-object that contains parameters + signature
  const signed = JSON.stringify(params);

  // шаблон web-страницы
  return `
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <script src="https://pay.itez.com/static/main/share/merchant.js"></script>

      <title>Widget integration sample</title>

      <script type="text/javascript">
        function runItezWidget() {
          ItezWidget.run( ${signed}, 'POST');
        }
        window.onload=runItezWidget;
      </script>

    </head>
    <body >
      <div id="widget-container"></div>
    </body>
  </html>`;
}

createServer((req, res) => {
  if (req.url === '/') {
    res.end(getDocument());
  }
}).listen(80);

// PHP
// формирование подписи параметров
$token = '';
$secret = '';

$params = [
    'partner_token' => $token,
    'target_element' => 'widget-container',
    'timestamp' =>  (int) (microtime(true) * 1000),
    'from_amount' => '3000',
    'from_currency' => 'USD',
    'lang' => 'EN',
];
ksort($params);

$data = [];
foreach ($params as $key => $value) {
    $data[] = "$key:$value";
}
$data = join(";", $data);

$hash = hash_hmac('sha512', $data, $secret);
$params['signature'] = $hash;

<!-- add js script -->
<script src="https://pay.itez.com/static/main/share/merchant.js"></script>
<!-- add container: id of container may be various 
      but you must set it into parameters -->

<div id="widget-container"></div>

<!-- initialise the widget -->
<script type="text/javascript">
    ItezWidget.run(
        <?php echo json_encode($params);  ?>
    );
</script>

Для запуска виджета используется метод ItezWidget.run. Первым параметром этого метода является объект в котором содержатся настройки запуска виджета. Подпись передается как поле signature этого объекта.
Поле signature - это строка которая формируется на основе остальных полей объекта настроек виджета и Itez Secret. Параметр “signature” не участвует в формировании подписи.

Алгоритм подписи:

  1. Для каждого из подписываемых параметров (параметр signature не участвует) формируется строка вида:
      "<имя>:<значение>".
    Удаляются все кавычки и апострофы, обрамляющие строковые значения.
    Строки должны быть представлены в кодировке UTF-8.
  2. Список полученных строк сортируется по алфавиту(ordinal).
  3. Отсортированный список строк объединяется в одну строку с разделителем ";".
  4. Вычисляется код HMAC(SHA-512) полученной строки с использованием Itez Secret, код HMAC должен создаваться в виде необработанных двоичных данных(raw BINARY-array).
  5. Полученный двоичный код преобразуется в HEX-string.
  6. Полученная строка записывается в поле signature;

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

Itez API

https://api.itez.com - URL-адрес Itez API. Доступны следующие запросы:

Возможные ошибки выполнения запросов можно посмотреть здесь.

Страны

Запрос возвращает список поддерживаемых стран.

https://api.itez.com/api/partner/countries

 POST   https://api.itez.com/api/partner/countries

Запрос

// Пример запроса
{
  "partner_token":"c0aaee39-...",
  "timestamp":1661161559871,
  "signature":"8190f8227d68c8af1..."
}
Параметр Тип Описание
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Ответ

// Пример ответа
{
    "countries": [
        {
            "code": 10001,
            "name": "Abhazia",
            "alpha2": "AB",
            "alpha3": "ABH"
        },
        {
            "code": 372,
            "name": "Ireland",
            "alpha2": "IE",
            "alpha3": "IRL"
        },
        {
            "code": 833,
            "name": "Isle of Man",
            "alpha2": "IM",
            "alpha3": "IMN"
        },
        {
            "code": 376,
            "name": "Israel",
            "alpha2": "IL",
            "alpha3": "ISR"
        },
        ...
        {
            "code": 876,
            "name": "Wallis and Futuna Islands",
            "alpha2": "WF",
            "alpha3": "WLF"
        }
    ],
    "signature": "7332c5349fb6d54424c..."
}
Параметр Тип Описание
countries object Список содержащий доступные страны..
signature string Подпись.

Каждый элемент countries состоит из следующих полей:

Параметр Тип Описание
code number ISO 3166-1 код страны.
name string Название страны.
alpha2 string ISO 3166-1 alpha-2.
alpha3 string ISO 3166-1 alpha-3.

Комиссия партнера

https://api.itez.com/api/partner/params

 POST   https://api.itez.com/api/partner/params

Запрос

// Пример запроса
{
  "partner_token":"c0aaee39-...",
  "timestamp":1661161559871,
  "signature":"8190f8227d68c8af1..."
}
Параметр Тип Описание
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Ответ

// Пример ответа
{
  "service_fee": 0.05,
  "signature": "8aa916e7d979f4d5c16..."
}
Параметр Тип Описание
service_fee number Размер комиссии партнера в процентах (0.01 = 1%).
signature string Подпись.

Цена покупки

https://api.itez.com/api/partner/exchange

 POST   https://api.itez.com/api/partner/exchange

Запрос

// Пример запроса
{
  "partner_token":"c0aaee39-...",
  "timestamp":1661161559871,
  "signature":"8190f8227d68c8af1..."
}
Параметр Тип Описание
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Ответ

// Пример ответа
{
    "pairs": [
        {
            "from": {
                "amount": 50,
                "min_amount": 50,
                "max_amount": 300,
                "min_kyc_amount": 50,
                "max_kyc_amount": 5000,
                "code": "EUR",
                "name": "Euro",
                "symbol": "€",
                "minor_unit": 2
            },
            "to": {
                "amount": 0.00234279,
                "code": "BTC",
                "name": "Bitcoin",
                "symbol": "₿",
                "minor_unit": 8
            }
        },
        {
            "from": {
                "amount": 50,
                "min_amount": 50,
                "max_amount": 300,
                "min_kyc_amount": 50,
                "max_kyc_amount": 5000,
                "code": "EUR",
                "name": "Euro",
                "symbol": "€",
                "minor_unit": 2
            },
            "to": {
                "amount": 0.041908,
                "code": "ETH",
                "name": "Ethereum ",
                "symbol": "Ξ",
                "minor_unit": 6
            }
        },
        ...
   ],
    "signature": "..."
}
Параметр Тип Описание
pairs object Currency pairs parameters.
signature string Подпись.

Pairs

Каждый элемент массива pairs состоит из двух частей: From - объект содержащий параметры фиатной валюты и to параметры криптовалюты.

From

Parameter Type Description
amount number Сумма фиатных денег
min_amount number Минимальная сумма покупки
max_amount number Максиимальная сумма покупки
min_kyc_amount number Минимальная сумма покупки если покупатель прошел идентификацию KYC
max_kyc_amount number Максиимальная сумма покупки если покупатель прошел идентификацию KYC
code string Код валюты в ISO-4217
name string Наименование валюты
symbol string Знак валюты
minor_unit string Количество знаков послезапятой

To

Parameter Type Description
amount number Цена в криптовалюте за количество валюты из from.amount
code string Код криптовалюты, аналогично ISO-4217
name string Наименование валюты
symbol string Знак валюты
minor_unit string Количество знаков послезапятой

Фиксация цены перед покупкой

https://api.itez.com/api/partner/exchange/calculate

 POST   https://api.itez.com/api/partner/exchange/calculate

Запрос

// Пример запроса
{
    "from_currency":"USD",
    "from_amount":100,
    "to_currency":"BTC",
    "partner_token":"c0aaee39-...",
    "signature":"2cc3acf3253065741..."
}
Параметр Тип Описание
from_currency string Исходная валюта. Указывается в верхнем регистре (USD).
to_currency string Результирующая валюта. Указывается в верхнем регистре (BTC).
from_amount number Количество денег для покупки. Указывается в минимальных единицах (центы).
to_amount number Количество полученных монет после покупки. Указывается в минимальных единицах (сатоши).
partner_token string Токен партнера в Itez.
signature string Подпись.

Ответ

// Пример ответа
{
    "from_currency":"USD",
    "to_currency":"BTC",
    "from_amount":100,
    "to_amount":4477,
    "calculation_id":"8dcecbc5-c272-4247-bbf5-b812e507ec9a",
    "expired_at":"2022-08-22T12:52:47.3181644Z",
    "signature":"17a310b7f40af89342e02e747..."
}
Параметр Тип Описание
calculation_id string Покупку по полученному курсу можно совершить в виджете если передать в него calculation_id.
expired_at string Время действия calculation_id. Дата возвращается в формате 2021-02-12T11:12:57.2695721Z
from_currency string Исходная валюта.
to_currency string Криптовалюта.
from_amount number Количество денег для покупки.
to_amount number Количество полученной криптовалюты за from_amount.
signature string Подпись.

Информация о транзакции

https://api.itez.com/api/partner/operation

 POST   https://api.itez.com/api/partner/operation

Запрос

// Пример запроса
{
  "partner_operation_id":"7076b531-...",
  "partner_token":"c0aaee39-...",
  "timestamp":1661164641882,
  "signature":"6c5f9a8e63a9e4e18b..."
}
Параметр Тип Описание
partner_operation_id string ID который был передан в виджет. Формируется при открытии виджета.
operation_id string ID транзакции сформированный сервером Itez.
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Ответ

// Пример ответа
{
  "operation_data": {
      "status": "pending",
      "status_code": 1,
      "operation_info": {
          "id": "ccb862f4-4a91-4840-98fd-302cb7282f46",
          "created_at": "2022-08-22T10:49:55.891Z",
          "from": {
              "payment_method": 1,
              "payment_method_info": {},
              "currency": {
                  "code": "USD",
                  "decimals": 2
              },
              "amount": 3000
          },
          "to": {
              "withdrawal_method": 1,
              "withdrawal_method_info": {
                  "blockchain_address": "0:cc98aec4730127..."
              },
              "currency": {
                  "code": "TON",
                  "decimals": 6
              },
              "amount": 312237799
          },
          "currency_rate": 10,
          "status_url": "https://pay.itez.com/status/ccb862f4-4a91-4840-98fd-302cb7282f46"
      },
      "partner_info": {
          "operation_id": "4af49ebd-...",
          "token": "1a13dc56-..."
      },
      "customer_info": {
          "id": 115372,
          "account": "[email protected]",
          "country": {
                "code": "IT",
                "name": "Italy"
          }
      }
  },
  "signature": "b3a9071f6e4292ec..."
}
Параметр Тип Описание
operation_data object Данные об операции.
signature string Подпись.

Подтвеждение транзакции

https://api.itez.com/api/partner/params/confirm

 POST   https://api.itez.com/api/partner/params/confirm

Запрос

// Пример запроса
{
  "partner_operation_id":"7076b531-...",
  "partner_token":"c0aaee39-...",
  "timestamp":1661164641882,
  "signature":"6c5f9a8e63a9e4e18b..."
}
Параметр Тип Описание
partner_operation_id string ID который был передан в виджет. Формируется при открытии виджета.
operation_id string ID транзакции сформированный сервером Itez.
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Ответ

Данных нет. Следует ориентироваться на HTTP код ответа.

Отмена транзакции

https://api.itez.com/api/partner/params/cancel

 POST   https://api.itez.com/api/partner/params/cancel

Запрос

// Пример запроса
{
  "partner_operation_id":"7076b531-...",
  "partner_token":"c0aaee39-...",
  "timestamp":1661164641882,
  "signature":"6c5f9a8e63a9e4e18b..."
}
Параметр Тип Описание
partner_operation_id string ID который был передан в виджет. Формируется при открытии виджета.
operation_id string ID транзакции сформированный сервером Itez.
partner_token string Токен партнера в Itez.
timestamp number Текущее время.
signature string Подпись.

Ответ

Данных нет. Следует ориентироваться на HTTP код ответа.

Параметры API

Подпись параметров API

// Пример для NodeJS.

const { createHmac } = require('crypto');
const flat = require('flat');

 // Itez Secret.
const itez_secret = '';

const jsonToString = (obj) => {
  obj = JSON.parse(JSON.stringify(obj));
  return Object
  .entries(flat(obj, {
      delimiter: ':'
  }))
  .sort()
  .map(items => {
      let val = items[1];
      if (val === true) val = 1;
      else if (val === false) val = 0;
      return `${items[0]}:${val}`;
  })
  .join(';');
}

// Проверка подписи.
// data - JSON ответ, подписанный полем "signature".
function checkSignature(data) {
  let data_copy = Object.assign({}, data);
  delete data_copy.signature;

  return (
    data.signature ===
    createHmac('sha512', itez_secret)
      .update(jsonToString(data_copy))
      .digest('hex')
  );
}
// Пример реализации flat. Убирает вложенность.
function flat(obj) {
  const flat_r = (res, key, val, p = '') => {
    const prefix = [p, key].filter((v) => v).join(':');
    return typeof val === 'object'
      ? Object.keys(val).reduce(
          (prev, curr) => flat_r(prev, curr, val[curr], prefix),
          res
        )
      : Object.assign(res, { [prefix]: val });
  };
  return Object.keys(obj).reduce(
    (prev, curr) => flat_r(prev, curr, obj[curr]),
    {}
  );
}

Signature - это строка которая формируется на основе остальных полей JSON-объекта и Itez Secret. Параметр signature не участвует в формировании подписи.

Алгоритм вычисления подписи JSON-объекта
Этот алгоритм является более общей версией алгоритма подписи параметров виджета, поэтому его можно также использовать для подписи параметров виджета.

  1. Данные должны быть представлены в кодировке UTF-8. Необходимо сконвертировать данные, если кодировка отличается от UTF-8.
  2. Убрать вложенность.
    • Для этого все параметры из вложенных объектов и массивов перемещаются в корневой объект. Имена таких параметров изменяются. Имя каждого параметра представляет собой путь этого параметра. В качестве разделителя используется двоеточие ":".
    • Элементы массивов записываются отдельными строками, с указанием номера каждого элемента, начиная с нуля. В примере countries.
    • Пустые массивы полностью игнорируются и не включаются в набор строк для создания подписи.
    • Параметры с нулевыми, а также пустыми значениями остаются в строке. Нельзя заменять значения пустых параметров на пробелы или null. В примере empty_value.
  3. Отсортировать параметры по алфавиту(ordinal).
  4. Преобразовать значения булевых параметров. False заменяется на 0, true на 1. В примере disabled. Внимание: это относится только к булевым значениям: в строковых параметрах, даже если они содержат значения false или true, замены на 0 или 1 не используются! В примере bool_str.
  5. Объеденить парамертры из объекта в строку. В качестве разделителя используется точка с запятой ";". Во время объединения не добавляются запятые между параметрами и убираются обрамляющие значения и имена параметров кавычки.
  6. Вычислить HMAC полученной строки с функцией хеширования SHA-512 и Itez Secret в качестве ключа.
  7. Результат кодирования преобразовать в HEX-строку.

Исходные данныеУбрана вложенностьСортировка
{
 "disabled": false,
 "bool_str": "false",
 "empty_value": "",
 "status": "success",
 "from": {
  "method": 1,
  "currency": {
   "code": "USD",
   "decimals": 2,
  }
 },
 "countries": [
  {
   "code": 10001,
   "name": "Abhazia"
  },
  {
   "code": 372,
   "name": "Ireland"
  },
  {
   "code": 833,
   "name": "Isle of Man",
  }
 ]
}
{
 "disabled": false,
 "bool_str": "false",
 "empty_value": "",
 "status": "success",
 "from:method": 1,
 "from:currency:code": "USD",
 "from:currency:decimals": 2,
 "countries:0:code": 10001,
 "countries:0:name": "Abhazia",
 "countries:1:code": 372,
 "countries:1:name": "Ireland",
 "countries:2:code": 833,
 "countries:2:name": "Isle of Man"
}
{
 "bool_str": "false",
 "countries:0:code": 10001,
 "countries:0:name": "Abhazia",
 "countries:1:code": 372,
 "countries:1:name": "Ireland",
 "countries:2:code": 833,
 "countries:2:name": "Isle of Man",
 "disabled": false,
 "empty_value": "",
 "from:currency:code": "USD",
 "from:currency:decimals": 2,
 "from:method": 1,
 "status": "success"
}
Объединение параметров в строку, преобразованы булевские значения, убраны лишние кавычки и запятые
bool_str:false;countries:0:code:10001;countries:0:name:Abhazia;countries:1:code:372;countries:1:name:Ireland;countries:2:code:833;countries:2:name:Isle of Man;disabled:0;empty_value:;from:currency:code:USD;from:currency:decimals:2;from:method:1;status:success

Результат. Вычислен HMAC(SHA-512), результат преобразован в HEX-строку
07e11c5e76314dd8647dc85248a0ecf43bc91140af27a23ba88fd37f4a29acc7cf0507ecae7be1a1a94f64e04cff24a204228e564ca1ed844d87e799d817dc43

Текущее время

// Получение текущего времени
const timestamp = Date.now();

Timestamp - Текущее время. Колличество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC.
Допускается отличие timestamp от реального времени не больше чем на 30 секунд в большую сторону и на 5 секунд в меньшую.

Данные об операции

{
    "operation_data":
    {
        "status": "success",
        "status_code": 0,
        "operation_info":
        {
            "id": "f4cef8f5-8bab-...",
            "created_at": "2020-07-21T11:45:01.235259",
            "paid_at": "2020-07-21T11:55:17",
            "from":
            {
                "payment_method": 1,
                "payment_method_info":
                {
                    "number": "535175******1234",
                    "type": "mastercard",
                    "card_holder": "CUSTOMER NAME",
                    "expiry_month": "02",
                    "expiry_year": "2025",
                    "country":
                    {
                        "code": "RO",
                        "name": "Romania"
                    }
                },
                "currency":
                {
                    "code": "EUR",
                    "decimals": 2
                },
                "amount": 3000
            },
            "to":
            {
                "withdrawal_method": 1,
                "withdrawal_method_info":
                {
                    "blockchain_address": "tb1q20gz7d35k...",
                    "blockchain_tx_id": "1baa1bf5962b570d...",
                    "blockchain_explorer_url": "https://blockchair.com/bitcoin/transaction/1baa1bf5962b570d69f7..."
                },
                "currency":
                {
                    "code": "BTC",
                    "decimals": 8
                },
                "amount": 348372
            },
            "currency_rate": 861148,
            "status_url": "https://pay.itez.com/status/f4cef8f5-..."
        },
        "partner_info":
        {
            "operation_id": "partnerOperationId",
            "token": "dddaf979-fe4c-46fb-934c-f052900a0abe",
            "fee_info":
            {
                "withdrawal_method": 1,
                "withdrawal_method_info":
                {
                    "blockchain_address": "tb1qglzn75m0d...",
                    "blockchain_tx_id": "1baa1bf5962b570...",
                    "blockchain_explorer_url": "https://blockchair.com/bitcoin/transaction/1baa1bf5962b57..."
                },
                "currency":
                {
                    "code": "BTC",
                    "decimals": 8
                },
                "amount": 3657
            }
        },
        "customer_info":
        {
            "id": 6,
            "account": "[email protected]main.com",
            "country":
            {
                "code": "RO",
                "name": "Romania"
            }
        }
    },
    "signature": "c1e5256c0636c2..."
}

Оperation_data - объект содержащий данные об операции. Он может быть получен в колбэках или некоторых обработчиках событий. Он является входным параметром в обработчиках событий: onOperationSuccess, onOperationPending, onOperationFail.

Описание

Статус операции

Статус Описание
success Создана блокчейн транзакция
pending Списаны деньги с карты клиента
declined Отказ
awaiting confirm Ожидание подтверждения партнером

Код статуса операции

Код Описание
0 Выполнена. Исполнена транзакция на вывод
1 Создана. Операция только создана
2 Пришли деньги от пользователя
3 Пользователь прошел проверку
4 Исполнен ордер на бирже
6 Создана транзакция на вывод
7 Создан запрос на вывод
8 Ожидание подтверждения партнером
9 Подтверждена партнером
101 Отказ при оплате
102 Отказ пользователя
103 Пользователь не прошел проверку
104 Карта пользователя не прошла проверку
105 Истекло время холда курса
106 Отказ партнером

Коды ошибок API

HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8

Wrong signature
HTTP/1.1 200 OK
Content-Type: application/json

{
    "service_fee": 0.05,
    "signature": "..."
}

Если код ответа на запрос не "200 OK", в теле содержится текст с описанием ошибки.
Возможны следующие коды ошибок:

Код Описание
400 Bad Request Недопустимые параметры запроса.
401 Unauthorized Неправильная подпись.
403 Forbidden Партнер заблокирован.
404 Not Found Партнер не найден.
429 Too Many Requests Слишком частые запросы.
500 Internal Server Error Ошибка обработки запросы.

Оповещения

Оповещения (коллбеки) отправляются сразу после операции конвертации (инициализации и оплаты)

Метод отправки

HTTP POST запрос с JSON содержимым, который отправляется после операции конвертации (инициализации и оплаты).

Все оповещения подписаны подписью и верифицированы

Условия отправки оповещений

Оповещения отправляются в следующих случаях:

Доставка оповещения

Мы фиксируем факт доставки оповещения после получения 200 OK ответа от вашей системы.

Если оповещение не было доставлено, то будут осуществляться повторные попытки доставки по следующей логике:

Адрес доставки оповещений

Оповещения отправляются на URL, который является уникальным для каждого партнера. URL указывается у технической поддержки ITEZ.

Обработка оповещений

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

Параметры оповещения

Входные параметры оповещения представлены структурой operation_data.

CMS интеграция

WordPress

Платежный способ для WooCommerce

Используя WooCommerce вы можете принимать оплату за заказы в BTC.

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

Скачать плагин можно по этой ссылке

Установка:

  1. Перейти в консоль (админ-панель сайта)
  2. Нажать "Плагины", выбрать пункт "Добавить новый"
  3. Нажать кнопку "Загрузить плагин" (сверху экрана) и выбрать скачанный ранее файл с плагином
  4. Нажать кнопку "Установить"
  5. Нажать кнопку "Активировать"

Настройка способа оплаты:

  1. Перейти в раздел "WooCommerce" -> "Настройки" -> "Оплата"
  2. Нажать на метод "Itez Pay"
  3. В открывшемся разделе вы увидите следующие поля:
    • Включить/выключить - переключатель, активирующий или деактивирующий платежный метод;
    • Заголовок - название способа оплаты, которое пользователь будет видеть при выборе методов оплаты в оформлении заказа;
    • Описание - описание способа оплаты, которое пользователь будет видеть при выборе методов оплаты в оформлении заказа;
    • Адрес BTC кошелька - ваш BTC кошелек, куда будут поступать средства от покупателей;
    • Валюта магазина - валюта, в которой будет оплачивать пользовтаель;
    • Itez Secret (Key) - уникальный ключ партнера, необходимо запросить у технической поддержки Itez;
    • Partner Token - токен партнера, необходимо запросить у технической поддержки Itez.

После внесения измений их необходимо сохранить, нажав на соответствующую кнопку ниже полей.

Плагин виджета

Плагин позволяет максимально быстро и просто внедрить виджет Itez в любое место на вашем WordPress сайте.

Скачать плагин можно по этой ссылке.

Установка:

  1. Перейти в консоль (админ-панель сайта)
  2. Нажать "Плагины", выбрать пункт "Добавить новый"
  3. Нажать кнопку "Загрузить плагин" (сверху экрана) и выбрать скачанный ранее файл с плагином
  4. Нажать кнопку "Установить"
  5. Нажать кнопку "Активировать"

Добавление в область виджетов:

  1. Перейти в "Внешний вид" -> "Виджеты"
  2. Выбрать виджет "Itez WIdget" и перетащить его в нужную область виджетов
  3. В настройках виджета доступны следующие поля:
    • Заголовок - заголовок виджета;
    • Токен и секретный ключ - необходимо получить у технической поддержки Itez;
    • Стандартная сумма - сумма, введенная в виджете по-умолчанию;
    • Валюта - фиатная валюта, выбранная по-умолчанию.

Лэндинг

Вы можете использовать платежный виджет Itez на лендинге. Для создания лэндинга обратитесь к вашему персональному менеджеру или в поддержку Itez.

На страницу могут быть переданы параметры виджета и набор URL-ов для перехода по завершению работы лендинга.

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

Параметры виджета

// Пример JSON с параметрами инициализацией лэндинга
{
    "params": { 
        "partner_token": "...",
        "target_element": "widget-container",
        "timestamp": 1604047440000,
        "from_currency": "USD",
        "from_amount": 30000,
        "partner_operation_id": "12345",
        "signature": "..."
    },
    "callbacks": {
        "success": "https://itez.com/?success",
        "fail": "https://itez.com/?fail"
    }
}

Параметры видже должны быть переданы в объекте params. Их описание можно посмотреть здесь.

Редирект

Можно установить переход по заданному URL для некоторых событий. Для этого в объекте callback следует указать URL для перехода в следующих полях:

Формирование GET-запроса

// пример формирования GET-запроса
const data = {
    params:{...},
    calbacks:{...}
}

const url = 'https://buy.itez.com/?i=' + 
            Buffer.from(JSON.stringify(data)).toString('base64');

JSON с параметрами нужно сконверировать в base64 и передать в качестве GET рараметра с именем i.

https://buy.itez.com/?i=ewogICAgInBhcmFtcyI6IHsKICAgICAgICAicGFydG5lcl90b2tlbiI6ICIyOWE0OGY0MC03ZGY3LTQ5ZDMtODMwZS1iZTY4NGQ3Yjg4NjEiLAogICAgICAgICJ0YXJnZXRfZWxlbWVudCI6ICJ3aWRnZXQtY29udGFpbmVyIiwKICAgICAgICAidGltZXN0YW1wIjogMTYwNDA0NzQ0MCwKICAgICAgICAiZnJvbV9jdXJyZW5jeSI6ICJVU0QiLAogICAgICAgICJmcm9tX2Ftb3VudCI6IDMwMDAwLAogICAgICAgICJwYXJ0bmVyX29wZXJhdGlvbl9pZCI6IDEyMzQ1LAogICAgICAgICJzaWduYXR1cmUiOiAiMzZkMTFkZWUwYmU5ZDIwM2RkNTBkZWU1MWQ0YTI4YjEwOTgzZmUwMTU0ZmI5OWMwMzM2ZjI0OTZmMDg3NDk4Mzc0OTFjZGQ5OWM2ZWI5Y2E0YzY0NDQ0NzliZDcxOGFlMjQxNzQ5NmMwNTA4NGRhNzFmYjljYTcxYTQ1NDVlMjciCiAgICB9LAogICAgImNhbGxiYWNrcyI6IHsKICAgICAgICAic3VjY2VzcyI6ICJodHRwczovL2l0ZXouY29tLz9zdWNjZXNzIiwKICAgICAgICAiZmFpbCI6ICJodHRwczovL2l0ZXouY29tLz9mYWlsIgogICAgfQp8Cg==

Кастомизация виджета

Чтобы платежный виджет лучше вписывался в дизайн, мы предусмотрели возможность кастомизации цветовой палитры некоторых элементов интерфейса виджета.

У каких элементов можно менять цвет?

Primary fill

Primary text

Secondary text

Form stroke color

Box shadow

Как это сделать?

// Пример CSS
.widgetColor {
  --primaryFill: #6a42e9;
  --primaryText: #28334e;
  --secondaryText: #a2a9b9;
  --successColor: #00d2a8;
  --warningColor: #df3e6f;
  --backgroundColor: #ffffff;
  --formStrokeColor: #e6e6eb;
  --boxShadow: rgba(40, 51, 78, 0.3);
}

Для этого нужно создать свой файл CSS, определяющий цвета элементов, и подключить его при помощи параметра partner_css. В partner_css можно указать адрес по которому располагается файл CSS. Цвета виджета задаются в классе widgetColor. Значения не заданных полей будут взяты по умолчанию. Если ничего не указать в partner_css или файл недоступен, значения всех полей будет взято по умолчанию.

Partner.Itez.com

Как получить доступ к Partner.Itez.com

В этом руководстве мы покажем вам как получить доступ к partner.itez.com.

Перейдите на itez.com и нажмите "BUY"

Введите адрес своей электронной почты в этом поле

Проверьте почту и введите шестизначный код.

Нажмите на эту кнопку.

Далее нажмите на "Verify identity".

Придумайте и введите новый пароль.

Готово! Теперь вы можете входить на partner.itez.com по этому адресу почты и паролю.

Правила установки и использования виджета на стороннем ресурсе

Отказ от ответственности правообладателя программного обеспечения Виджета ITEZ (далее - Виджет)

Виджет является продуктом программного обеспечения, правообладателем которого является DataBridge OÜ, Республика Эстония (номер регистрации компании 14515009) – далее Правообладатель. Правообладатель передаёт неисключительную отзывную свободную от роялти лицензию юридическому лицу, с которым Правообладатель заключает договор об оказании услуг – далее Пользователь Виджета. Пользователь Виджета осуществляет установку Виджета (интеграцию на свой сайт в сети Интернет, осуществляет загрузку, копирование установочных файлов и данных, получает от Правообладателем токены интеграции для целей оказания услуг по договору Правообладателя с Пользователем Виджета) и через свой сайт организует взаимодействие с Виджетом пользователей своего сайта, в том числе с использованием встроенных в него ссылок и интеграций с другим программным обеспечением сторонних правообладателей).

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

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

Виджет и его компоненты предоставляются Правообладателем Пользователю Виджета на условиях «как есть – «as is» без каких-либо гарантий, явных или подразумеваемых.

Кроме того, Правообладатель не даёт никаких гарантий, что:

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

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

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