CryptoWay API Documentation

Введение

API интеграции

Endpoint: https://api.cryptoway.com

CryptoWay API подписывается по схеме HMAC-SHA256. Документация состоит из четырёх разделов:

• Подпись
• Депозиты
• Выводы
• Справочные эндпоинты

Подпись

Подпись

Ключи

Для webhook используйте callback_key, не secret API key.

Получение ключей API

Один API key можно использовать для всех методов API, если при создании включены нужные разрешения.

Параметры при создании ключа

Если allowed_ips пуст, первый успешный запрос с API автоматически добавит текущий IP в список.

Инструкция

1. Зарегистрируйтесь в сервисе.
2. Перейдите во вкладку «API ключи».
3. Нажмите «Создать API ключ».
4. Укажите название, разрешения и IP в форме создания.
5. После сохранения сразу запишите ключи из модального окна. Secret показывается один раз.
6. Готово.

В запросах используйте id ключа как X-API-Key-ID, secret — для подписи.

callback_key

Ключ для проверки webhook находится в профиле личного кабинета. Он не совпадает с secret API key.

Заголовки запроса к API

Подпись обязательна для всех публичных эндпоинтов (метод GET, POST и др.).

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

1. Соберите объект:

{
  "params": "url_encoded_query_string",
  "body": {},
  "path": "/user/balance/"
}

• params — query string как в URL (search_query=foo, без ?)
• body — JSON тела запроса; {} если тела нет
• path — путь запроса, например /user/balance/

1. Сериализуйте объект: json.dumps(data, separators=(",", ":"), sort_keys=True)
2. Подпись:

signature = HMAC-SHA256(key=API_KEY_SECRET, message=timestamp + json_string)

1. Timestamp должен быть в пределах ±15 секунд от серверного времени.

Если allowlist ключа пуст, при первом успешном запросе текущий IP записывается в allowlist. Дальнейшие запросы принимаются только с IP из списка.

Пример: GET баланс

# params пустые, body {}
# path = /user/balance/
# data = {"body":{},"params":"","path":"/user/balance/"}

curl "https://api.cryptoway.com/user/balance/" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>"

Пример: POST адрес

curl "https://api.cryptoway.com/user/address/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>" \
  -d '{"symbol_id":"USDTBEP20","callback_url":"https://example.com/cb","description":"shop"}'

Генерация подписи

:::tabs

import hashlib, hmac, json, time

def sign(key: str, timestamp: int, data: dict) -> str:
    s = json.dumps(data, separators=(",", ":"), sort_keys=True)
    return hmac.new(key.encode(), f"{timestamp}{s}".encode(), hashlib.sha256).hexdigest()

data = {"params": "", "body": {"symbol_id": "USDTBEP20"}, "path": "/user/address/"}
ts = int(time.time())
signature = sign(API_KEY_SECRET, ts, data)

$data = ["params" => "", "body" => ["symbol_id" => "USDTBEP20"], "path" => "/user/address/"];
ksort($data);
$json = json_encode($data, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", time() . $json, $API_KEY_SECRET);

:::

Webhook: проверка подписи

На ваш callback_url приходит POST.

Заголовки:

Данные для подписи:

{
  "params": "",
  "body": { }
}

• params — query string вашего endpoint
• body — распарсенное JSON тело POST
• поле path не используется
• для подписи используется callback_key

Допустимое отклонение timestamp: ±15 секунд.

Webhook депозита / вывода

В теле POST передаётся JSON-объект транзакции (поля описаны ниже). Для проверки подписи этот объект помещается в поле body, поле params оставляют пустым.

Webhook счёта (invoice)

{
  "params": "",
  "body": {
    "type": "invoice",
    "id": "5ca38db1-00c5-4aba-91e5-6a57bed60aee",
    "status": "executed"
  }
}

Тело POST совпадает с объектом подписи: на верхнем уровне поля params и body. Для проверки подписи используйте распарсенное тело запроса целиком, без дополнительной обёртки.

Python: проверка webhook

Webhook депозита и вывода:

body = await request.json()
data = {"params": request.url.query, "body": body}
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Webhook счёта:

data = await request.json()
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Общая функция verify:

def verify(signature: str, key: str, timestamp: int, data: dict) -> bool:
    if abs(int(time.time()) - timestamp) > 15:
        return False
    expected = sign(key, timestamp, data)
    return hmac.compare_digest(expected, signature)

Депозиты

Депозиты

Депозит регистрируется после on-chain перевода на адрес, полученный через API. Сканер блокчейна создаёт транзакцию с типом deposit.

Начало работы

Перед интеграцией создайте API key (раздел «Подпись»). Без ключа запросы к API не проходят.

Выбор типа интеграции

Доступны два способа приёма депозитов.

Счёт на оплату (Invoice)

Подходит для оплаты товара или услуги на фиксированную сумму.

Создание: POST /invoice/. Укажите сумму в фиате (target_value_fiat) или в крипте (target_value_symbol).

Символ и адрес

• Если при создании указан symbol_id, сразу генерируется адрес и ссылка pay_url.
• Если symbol_id не указан, плательщик выбирает символ и сеть на странице оплаты. Адрес появится после выбора.

Уведомления

Статусы счёта: active, executed, expired, cancelled. Промежуточных статусов частичной оплаты (paid_over, wrong_amount и т.п.) нет. Частичные переводы приходят как отдельные webhook депозита; счёт переходит в executed, когда сумма депозитов достигает цели, или в expired по deadline_at.

Постоянный адрес

Подходит для пополнения баланса без фиксированной суммы.

Создание: POST /user/address/. Укажите symbol_id и при необходимости external_id (ваш идентификатор адреса).

На адрес можно отправлять переводы любой суммы выше min_deposit_amount. Каждый перевод создаёт депозит и отдельный webhook.

Общий порядок

1. Создайте счёт или постоянный адрес.
2. Плательщик отправляет перевод on-chain.
3. Сканер фиксирует депозит. Если указан callback_url, отправляется webhook.

Эндпоинты

POST /user/address/

Запрос

Виртуальные символы (USDT) не принимаются. Указывайте символ с привязкой к сети.

Ответ

POST /invoice/

Запрос

Нужно указать target_value_fiat или target_value_symbol.

Ответ

Адрес оплаты в target_wallet.value, текущий status, ссылка на оплату в pay_url.

GET /user/transaction/

Фильтры для депозитов:

Webhook депозита

POST на callback_url, указанный при создании адреса. Для депозита по счёту используется callback_url счёта.

Тело (основные поля):

Пример

{
  "user_id": 1,
  "type": "deposit",
  "created_at": "2025-11-20T16:08:10.180830+00:00",
  "symbol_id": "USDTBEP20",
  "status": "executed",
  "amount": "4.696700000000000000",
  "service_fee": "0.803300000000000000",
  "net_amount": "5.500000000000000000",
  "blockchain_data": {
    "hash": "0xabc...",
    "from_address": "0x123",
    "to_address": "0x456"
  },
  "external_id": null,
  "callback_url": "https://example.com/cb"
}

Webhook счёта

Отдельный callback при смене статуса счёта (executed, expired). Формат тела и проверка подписи описаны в разделе «Webhook счёта (invoice)».

Статусы депозита

Статусы счёта

Доставка webhook

При неуспешном ответе вашего сервера webhook повторяется автоматически.

Если сервер уже ответил 2xx на первый webhook, повтор при смене статуса на executed не отправляется. При AML или ожидании подтверждений первый webhook может прийти со статусом pending.

Актуальный статус транзакции запрашивайте через GET /user/transaction/ или GET /user/transaction/{encoded_id}/.

Минимальная сумма

Депозиты ниже min_deposit_amount игнорируются. Актуальное значение: GET /setting/fees/ (раздел 4).

Выводы

Выводы

Эндпоинты

Отдельного GET /withdrawal/{id} нет. Используйте transaction API.

POST /user/balance/withdrawal/

Query

Запрос

Виртуальные символы не принимаются.

Комиссия списывается сверх amount. С баланса уходит amount + service_fee.

Ответ

JSON-объект транзакции: "type": "withdrawal", текущий статус вывода в status, идентификатор в encoded_id.

Ошибки

Rate limit: 15 запросов за 15 секунд.

GET /user/transaction/

Webhook вывода

Отправляется один раз при переходе вывода в статус executed.

Тело

JSON-объект транзакции с "type": "withdrawal". Поля совпадают с объектом в webhook депозита.

Подпись проверяется ключом callback_key по заголовкам X-Signature, X-Timestamp и структуре данных с полями params и body.

Статусы вывода

Фильтр in_processing=true возвращает все статусы, кроме executed, cancelled, cancelled_by_risk, failed.

Ограничения

Повтор запроса с тем же external_id не является идемпотентным.

Справочные эндпоинты

Справочные эндпоинты

Вспомогательные методы, на которые ссылаются операции из других разделов.

Эндпоинты

GET /symbol/

Используйте для получения допустимых значений symbol_id при создании адреса, счёта или вывода.

Query

Ответ

Пагинированный список. Каждый элемент:

Для запросов с symbol_id выбирайте записи с is_virtual: false и is_active: true.

GET /symbol/fiat/

Список кодов фиатных валют для поля target_currency_fiat при создании счёта.

Ответ

Массив строк, например ["USD", "EUR", ...].

GET /user/balance/

Текущий баланс аккаунта. Удобно перед созданием вывода.

Query

Ответ

Массив объектов:

Rate limit: 30 запросов в минуту.

GET /setting/fees/

Комиссии и минимальные суммы по символам.

Query

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

Ответ

Массив объектов по символам:

GET /currency/rate/

Курсы валютных пар.

Query

Ответ

Массив объектов:

Примеры пар

GET /currency/rate/hedge/

Только курсы from_symbol_id → USDT из источника aster_dex. Формат ответа совпадает с GET /currency/rate/.

Premium Exchange

Как подключить к

Подключение CryptoWay к обменному пункту на скрипте Premium Exchanger (v 2.7) — двумя модулями:

• Мерчант (приём средств) — принимает средства от клиента на ваши счета и автоматически переводит заявку в статус «Оплаченная заявка».
• Автовыплата — выплачивает средства клиенту с ваших счетов.

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

Полная документация Premium Exchanger: Модули мерчантов и автовыплат

Что понадобится

• Обменник на Premium Exchanger 2.7.x. Модули несовместимы между версиями: на скрипте 2.7 нужны модули 2.7.*, иначе сайт не откроется.
• Доступ к серверу через ISP Manager из-под пользователя сайта (не root).
• API-ключ CryptoWay с разрешениями на депозиты и выводы — API key ID и secret (см. Подпись).

Шаг 1. Файлы модулей

Версия модуля должна совпадать с версией вашего скрипта Premium Exchanger (например, 271 — под 2.7.\*).

Шаг 2. Загрузка на сервер

Перед изменением файлов сделайте бэкап корневой папки сайта. Работайте через ISP Manager из-под пользователя сайта (не root).

1. Папку cryptoway из m_cryptoway_271.zip загрузите в /wp-content/plugins/premiumbox/merchants.
2. Папку cryptoway из pay_cryptoway_271.zip загрузите в /wp-content/plugins/premiumbox/paymerchants.
3. При окне о совпадении файлов — нажмите «Заменить».

Шаг 3. Добавление и настройка мерчанта

В разделе «Мерчанты» → «Мерчанты» нажмите «Добавить» (часть мерчантов создана по умолчанию). Заполните форму:

• Заголовок — название мерчанта в панели управления.
• Модуль — выберите CryptoWay из выпадающего списка.
• Статус — «активный мерчант».

В настройках модуля укажите ключи из личного кабинета CryptoWay:

• API ключ — API key ID.
• Секретный ключ — secret вашего API-ключа.

Шаг 4. Автовыплаты

Модуль автовыплат подключается так же: раздел «Автовыплаты» → «Добавить», статус «активный», те же ключи CryptoWay (API key ID + secret). Привязывается на вкладке «Мерчанты и выплаты» направления — для валюты «Получаю». Перед включением ознакомьтесь с разделом «Предупреждение о рисках» в документации Premium Exchanger.

Шаг 5. Режимы работы

Изначально обменник работает в ручном режиме. С модулями:

• Только мерчант на приём — автоматизируется приём: при поступлении средств заявка переходит в «Оплаченная заявка», выплату вы делаете вручную и меняете статус на «Выполненная заявка».
• Мерчант + автовыплата — полная автоматизация: «Оплаченная заявка» → «Ожидание подтверждения от модуля автовыплат» → «Выполненная заявка».
• Можно включить кнопку «Перевести» в заявке даже для автоматизированного направления — оператор сможет выплатить вручную, если автовыплата не прошла.

Шаг 6. Проверка

Проверьте подключение встроенной «Диагностикой мерчанта» (Мерчанты → Мерчанты → диагностика):

• Убедитесь, что на сервере настроен планировщик задач (cron) — без него статусы заявок не меняются автоматически.
• Если в логе ошибка вида «your IP … not in whitelist» — добавьте IP вашего сервера в whitelist API-ключа CryptoWay (параметр allowed_ips).

iEXExchanger

Как подключить к iEXExchanger

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

Модуль поддерживает:

• создание адресов для оплаты;
• автоматическую проверку поступлений;
• webhook-уведомления;
• ручную и автоматическую проверку платежей;
• работу с несколькими блокчейн-сетями.

Важно. Перед включением мерчанта в рабочем направлении обязательно выполните тестовую оплату на небольшую сумму. Если неправильно указать API-ключ, Callback Key или сеть, адрес для оплаты может не создаться, а автоматическая обработка платежей работать не будет.

Полная документация iEXExchanger: Мерчант Cryptoway.

Что понадобится

Перед настройкой подготовьте данные из личного кабинета CryptoWay:

• API Key ID
• API Key Secret

Для приёма криптовалюты API-ключ должен иметь разрешение Deposits. Разрешение Withdrawal предназначено для автоматических выплат — для работы мерчанта на приём оно не требуется (см. Подпись и Депозиты).

Шаг 1. Регистрация и API-ключ в CryptoWay

Создайте аккаунт или войдите в существующий на cryptoway.com. После входа:

1. Перейдите в раздел «API ключи».
2. Нажмите «Создать API ключ».
3. Укажите произвольное название ключа.
4. При необходимости укажите публичный IP-адрес вашего сервера.
5. Включите разрешение Deposits.
6. Подтвердите создание ключа.
7. Скопируйте Key ID и Key Secret.

Важно. Key Secret показывается только при создании ключа — повторно посмотреть его не получится. Если ключ не был сохранён, создайте новую пару ключей. Сохраните данные в безопасном месте и не передавайте их третьим лицам.

Если список разрешённых IP-адресов оставить пустым, CryptoWay может автоматически сохранить IP-адрес первого успешного API-запроса — последующие запросы будут приниматься только с этого IP.

Шаг 2. Добавление мерчанта

В админке iEXExchanger откройте «Мерчанты и API» → «Список мерчантов» и нажмите «Добавить». В списке модулей выберите Cryptoway.

Шаг 3. Настройка мерчанта

Заполните поля мерчанта:

• API Key ID — идентификатор API-ключа из кабинета CryptoWay (формат xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Обязательное поле.
• API Key Secret — секретная часть API-ключа. Используется для подписи запросов создания адресов оплаты, проверки поступления средств и получения списка доступных валют и сетей. Обязательное поле, без пробелов в начале и конце значения.
• API Base URL — оставьте стандартное значение https://api.cryptoway.com. Изменяйте только по рекомендации техподдержки CryptoWay; не указывайте здесь адрес личного кабинета или домен вашего обменного пункта.
• Callback Key — оставьте поле пустым.

Код валюты. Выберите код валюты и блокчейн-сети, который используется в CryptoWay, например USDTTRC20, USDTBEP20 или BNBBEP20. Использовать общий код без сети (например USDT) нельзя — CryptoWay принимает код, привязанный к конкретной блокчейн-сети. Если выбрано значение «Автоматически», система берёт код сети из настроек валюты; заранее убедитесь, что он совпадает с идентификатором валюты в CryptoWay.

Макс. время регистрации в блокчейне — задаётся в минутах, рекомендуемое значение 30. В течение этого времени система ожидает регистрацию транзакции в блокчейне.

Макс. время получения первого подтверждения — задаётся в часах, рекомендуемое значение 2. В течение этого времени система ожидает первое подтверждение транзакции.

Шаг 4. Привязка мерчанта к валюте

После сохранения мерчанта назначьте его нужной валюте. Откройте «Основное» → «Валюты» → «Список валют», выберите валюту, перейдите в раздел автоматизации и в качестве мерчанта выберите Cryptoway.

Убедитесь, что выбранная сеть соответствует сети, указанной в настройках мерчанта. Например:

• Валюта: USDT
• Сеть: TRC20
• Код CryptoWay: USDTTRC20
• Мерчант: Cryptoway

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

Как работает приём платежей

После создания заявки iEXExchanger автоматически отправляет запрос в API CryptoWay. CryptoWay создаёт постоянный адрес и возвращает его системе, клиент переводит средства на этот адрес. Когда платёж получает статус executed, iEXExchanger автоматически переводит заявку в следующий статус. Для связи платежа с заявкой iEXExchanger передаёт в CryptoWay идентификатор заявки.

Фактически поступившая сумма считается по значению amount — это сумма, зачисленная на баланс CryptoWay после учёта комиссии сервиса. Учитывайте комиссию CryptoWay при настройке направления обмена: сумма перевода в блокчейне может отличаться от суммы, фактически зачисленной на баланс.

Что проверить перед запуском

• API Key ID и API Key Secret заполнены правильно;
• для API-ключа включено разрешение Deposits;
• API Base URL имеет значение https://api.cryptoway.com;
• код валюты и сеть указаны без ошибок, не используется код без сети (например USDT);
• backend обменника доступен по HTTPS;
• публичный IP сервера разрешён в настройках API-ключа;
• мерчант привязан к нужной валюте или направлению;
• учтены минимальная сумма и комиссия CryptoWay;
• на время тестирования включено логирование запросов.

Проверка работы

1. Создайте тестовую заявку.
2. Убедитесь, что появился адрес оплаты.
3. Проверьте, что адрес соответствует выбранной сети.
4. Отправьте небольшую сумму.
5. Дождитесь обработки платежа.
6. Проверьте изменение статуса заявки.
7. Убедитесь, что платёж получил статус executed.
8. Проверьте сохранение хеша транзакции.
9. Сверьте сумму заявки с суммой, зачисленной на баланс CryptoWay.
10. Проверьте журнал запросов: «Журнал событий» → «Мерчанты и API» → «Лог запросов мерчантов».

Рекомендации

• Используйте отдельный API-ключ CryptoWay для каждого обменного пункта.
• Для приёма и автоматических выплат используйте разные API-ключи.
• Не публикуйте API Key ID и API Key Secret в переписках и на скриншотах.
• Перед включением мерчанта в рабочих направлениях всегда выполняйте тестовую оплату.
• Проверяйте актуальную минимальную сумму депозита и комиссию для выбранной валюты.
• После успешной проверки можно отключить расширенное логирование запросов.

WooCommerce

Плагин Cryptoway Payments для WooCommerce

Плагин Cryptoway Payments добавляет приём криптоплатежей в WooCommerce. Покупатель оформляет заказ в стандартном checkout магазина, оплачивает счёт на стороне Cryptoway, а статус заказа обновляется через подписанный webhook.

Плагин поддерживает WooCommerce Checkout Blocks и High-Performance Order Storage.

Что понадобится

Перед установкой подготовьте:

• WordPress 6.0 или новее;
• PHP 8.1 или новее;
• WooCommerce 7.0 или новее;
• аккаунт Cryptoway;
• API Key ID, API Key Secret и Callback Key Secret.

Получите ключи Cryptoway

1. Войдите в личный кабинет Cryptoway.
2. Откройте раздел API ключи и создайте ключ.
3. Для приёма платежей включите разрешение на операции с депозитами.
4. Сохраните API Key ID и API Key Secret. Secret показывается только один раз.
5. В профиле личного кабинета скопируйте Callback Key Secret для проверки webhook.

Важно. Для webhook используется Callback Key Secret, а не API Key Secret. Алгоритм проверки описан в разделе Подпись.

Установка

Через WordPress

1. Откройте Плагины → Добавить новый.
2. Найдите Cryptoway Payments.
3. Установите и активируйте плагин.
4. Убедитесь, что WooCommerce установлен и активен.

Вручную

Загрузите файлы плагина в каталог:

/wp-content/plugins/cryptoway-payments

После этого активируйте плагин в WordPress.

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

Откройте WooCommerce → Настройки → Платежи → Cryptoway и заполните параметры.

Сохраните изменения.

Как проходит оплата

1. Покупатель выбирает Cryptoway при оформлении заказа.
2. Плагин создаёт счёт Cryptoway на сумму заказа и сохраняет его ID в WooCommerce.
3. Покупатель переходит на страницу оплаты Cryptoway.
4. После оплаты Cryptoway отправляет подписанный webhook в магазин.
5. Плагин проверяет подпись webhook и обновляет заказ.

Статусы счёта

Webhook

Плагин передаёт Cryptoway следующий endpoint при создании счёта:

https://ваш-домен/wp-json/cryptoway/v1/webhook

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

• в настройках заполнен Callback Key Secret;
• WordPress REST API доступен по адресу /wp-json/cryptoway/v1/webhook;
• хостинг, WAF или другие правила сайта не блокируют входящие webhook.

Проверка после настройки

1. Создайте тестовый заказ в магазине.
2. На checkout выберите Cryptoway.
3. Убедитесь, что открывается страница оплаты Cryptoway.
4. Проверьте, что после смены статуса счёта обновляется заказ в WooCommerce.
5. Если статус не обновился, откройте карточку заказа и запустите ручную проверку статуса платежа.

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

Доступный список зависит от настроек мерчанта и подключённых способов оплаты. Среди популярных активов: BTC, ETH, USDT, BNB, LTC, TON, TRX.

Для USDT доступны сети ERC-20, TRC-20 и TON. Полный актуальный список — на странице Supported Coins.

Безопасность

• Храните API Key Secret только в настройках магазина и не передавайте третьим лицам.
• Callback Key Secret используется для проверки подписи webhook. Без него плагин не обновит заказ по входящему уведомлению.
• Покупатель оплачивает заказ на странице Cryptoway. Плагин не запрашивает и не хранит учётные данные кошелька покупателя.

Диагностика

Комиссии и поддержка

Текущие тарифы Cryptoway начинаются от 0,3% за успешную входящую транзакцию. Актуальные условия — на странице Pricing.

Если нужна помощь с настройкой:

• Документация API;
• @cryptoway_support_bot;
• Контакты Cryptoway.

Introduction

API Integration

Endpoint: https://api.cryptoway.com

The CryptoWay API is signed with HMAC-SHA256. The documentation is split into four sections:

• Signing
• Deposits
• Withdrawals
• Reference

Signing

Signing

Keys

For webhooks, use callback_key — not the secret API key.

Getting API keys

A single API key works for every API method, as long as you enable the permissions it needs when you create it.

Key creation parameters

If allowed_ips is empty, the first successful API request automatically adds the current IP to the list.

Steps

1. Sign up for the service.
2. Open the API keys tab.
3. Click Create API key.
4. Set the name, permissions, and IPs in the form.
5. Copy the keys from the modal right away — the secret is shown only once.
6. Done.

In your requests, use the key id as X-API-Key-ID and the secret for signing.

callback_key

The webhook verification key lives in your dashboard profile. It is not the same as the secret API key.

Request headers

A signature is required for every public endpoint (GET, POST, and others).

Signing algorithm

1. Build the object:

{
  "params": "url_encoded_query_string",
  "body": {},
  "path": "/user/balance/"
}

• params — the query string exactly as it appears in the URL (search_query=foo, without the ?)
• body — the JSON request body; {} when there is no body
• path — the request path, e.g. /user/balance/

1. Serialize the object: json.dumps(data, separators=(",", ":"), sort_keys=True)
2. Sign it:

signature = HMAC-SHA256(key=API_KEY_SECRET, message=timestamp + json_string)

1. The timestamp must be within ±15 seconds of server time.

If the key's allowlist is empty, the first successful request records the current IP in the allowlist. After that, only requests from a listed IP are accepted.

Example: GET balance

# empty params, body {}
# path = /user/balance/
# data = {"body":{},"params":"","path":"/user/balance/"}

curl "https://api.cryptoway.com/user/balance/" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>"

Example: POST address

curl "https://api.cryptoway.com/user/address/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>" \
  -d '{"symbol_id":"USDTBEP20","callback_url":"https://example.com/cb","description":"shop"}'

Generating a signature

:::tabs

import hashlib, hmac, json, time

def sign(key: str, timestamp: int, data: dict) -> str:
    s = json.dumps(data, separators=(",", ":"), sort_keys=True)
    return hmac.new(key.encode(), f"{timestamp}{s}".encode(), hashlib.sha256).hexdigest()

data = {"params": "", "body": {"symbol_id": "USDTBEP20"}, "path": "/user/address/"}
ts = int(time.time())
signature = sign(API_KEY_SECRET, ts, data)

$data = ["params" => "", "body" => ["symbol_id" => "USDTBEP20"], "path" => "/user/address/"];
ksort($data);
$json = json_encode($data, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", time() . $json, $API_KEY_SECRET);

:::

Verifying a webhook signature

A POST is sent to your callback_url.

Headers:

Data to sign:

{
  "params": "",
  "body": { }
}

• params — the query string of your endpoint
• body — the parsed JSON POST body
• the path field is not used
• the signature uses callback_key

Allowed timestamp drift: ±15 seconds.

Deposit / withdrawal webhook

The POST body is the transaction object as JSON (fields are described below). To verify the signature, place this object in the body field and leave params empty.

Invoice webhook

{
  "params": "",
  "body": {
    "type": "invoice",
    "id": "5ca38db1-00c5-4aba-91e5-6a57bed60aee",
    "status": "executed"
  }
}

The POST body is identical to the object you sign: params and body at the top level. To verify the signature, use the entire parsed request body as-is, with no extra wrapper.

Verifying webhooks in Python

Deposit and withdrawal webhooks:

body = await request.json()
data = {"params": request.url.query, "body": body}
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Invoice webhook:

data = await request.json()
verify(request.headers["X-Signature"], CALLBACK_KEY, int(request.headers["X-Timestamp"]), data)

Shared verify helper:

def verify(signature: str, key: str, timestamp: int, data: dict) -> bool:
    if abs(int(time.time()) - timestamp) > 15:
        return False
    expected = sign(key, timestamp, data)
    return hmac.compare_digest(expected, signature)

Deposits

Deposits

A deposit is registered after an on-chain transfer to an address you obtained through the API. The blockchain scanner creates a transaction with the deposit type.

Getting started

Before you integrate, create an API key (see the Signing section). Without a key, API requests won't go through.

Choosing an integration type

There are two ways to accept deposits.

Invoice

Best for charging a fixed amount for a product or service.

Create one with POST /invoice/. Set the amount in fiat (target_value_fiat) or in crypto (target_value_symbol).

Symbol and address

• If you pass symbol_id at creation, an address and a pay_url are generated right away.
• If you omit symbol_id, the payer picks the symbol and network on the payment page. The address appears once they choose.

Notifications

Invoice statuses: active, executed, expired, cancelled. There are no intermediate partial-payment statuses (paid_over, wrong_amount, etc.). Partial transfers arrive as separate deposit webhooks; the invoice moves to executed once the deposits add up to the target, or to expired at deadline_at.

Permanent address

Best for topping up a balance with no fixed amount.

Create one with POST /user/address/. Pass symbol_id and, optionally, external_id (your own identifier for the address).

You can send transfers of any amount above min_deposit_amount to the address. Each transfer creates a deposit and its own webhook.

Overall flow

1. Create an invoice or a permanent address.
2. The payer sends an on-chain transfer.
3. The scanner registers the deposit. If a callback_url is set, a webhook is sent.

Endpoints

POST /user/address/

Request

Virtual symbols (USDT) are not accepted. Always pass a network-bound symbol.

Response

POST /invoice/

Request

You must set either target_value_fiat or target_value_symbol.

Response

The payment address is in target_wallet.value, the current status, and the payment link in pay_url.

GET /user/transaction/

Filters for deposits:

Deposit webhook

A POST to the callback_url you set when creating the address. For invoice deposits, the invoice's callback_url is used.

Body (main fields):

Example

{
  "user_id": 1,
  "type": "deposit",
  "created_at": "2025-11-20T16:08:10.180830+00:00",
  "symbol_id": "USDTBEP20",
  "status": "executed",
  "amount": "4.696700000000000000",
  "service_fee": "0.803300000000000000",
  "net_amount": "5.500000000000000000",
  "blockchain_data": {
    "hash": "0xabc...",
    "from_address": "0x123",
    "to_address": "0x456"
  },
  "external_id": null,
  "callback_url": "https://example.com/cb"
}

Invoice webhook

A separate callback fires when the invoice status changes (executed, expired). The body format and signature verification are covered under Invoice webhook in the Signing section.

Deposit statuses

Invoice statuses

Webhook delivery

If your server responds with an error, the webhook is retried automatically.

If your server already returned 2xx to the first webhook, no retry is sent when the status later changes to executed. With AML or pending confirmations, the first webhook may arrive with the pending status.

Query the current transaction status via GET /user/transaction/ or GET /user/transaction/{encoded_id}/.

Minimum amount

Deposits below min_deposit_amount are ignored. For the current value, see GET /setting/fees/ (Reference).

Withdrawals

Withdrawals

Endpoints

There is no separate GET /withdrawal/{id}. Use the transaction API.

POST /user/balance/withdrawal/

Query

Request

Virtual symbols are not accepted.

The fee is charged on top of amount. Your balance is debited by amount + service_fee.

Response

A transaction object as JSON: "type": "withdrawal", the current withdrawal status in status, and the identifier in encoded_id.

Errors

Rate limit: 15 requests per 15 seconds.

GET /user/transaction/

Withdrawal webhook

Sent once, when the withdrawal moves to the executed status.

Body

A transaction object as JSON with "type": "withdrawal". The fields match the deposit webhook object.

The signature is verified with callback_key, using the X-Signature and X-Timestamp headers and the data structure with params and body.

Withdrawal statuses

The in_processing=true filter returns every status except executed, cancelled, cancelled_by_risk, and failed.

Limits

Repeating a request with the same external_id is not idempotent.

Reference

Reference

Helper methods that the operations in the other sections rely on.

Endpoints

GET /symbol/

Use it to get valid symbol_id values when creating an address, invoice, or withdrawal.

Query

Response

A paginated list. Each item:

For symbol_id requests, pick records with is_virtual: false and is_active: true.

GET /symbol/fiat/

A list of fiat currency codes for the target_currency_fiat field when creating an invoice.

Response

An array of strings, e.g. ["USD", "EUR", ...].

GET /user/balance/

The account's current balance. Handy before creating a withdrawal.

Query

Response

An array of objects:

Rate limit: 30 requests per minute.

GET /setting/fees/

Fees and minimum amounts by symbol.

Query

Without parameters, global values are returned. Pass your user_id to get your actual limits and fees.

Response

An array of objects by symbol:

GET /currency/rate/

Currency pair rates.

Query

Response

An array of objects:

Example pairs

GET /currency/rate/hedge/

Only from_symbol_id → USDT rates from the aster_dex source. The response format matches GET /currency/rate/.

Premium Exchange

How to connect to

Connect CryptoWay to an exchange running the Premium Exchanger (v 2.7) script via two modules:

• Merchant (incoming payments) — receives the client's funds into your accounts and automatically moves the order to the “Paid order” status.
• Auto-payout — pays the client out from your accounts.

Together they fully automate the exchange. You can connect just one module to automate only the accept side or only the payout side.

Full Premium Exchanger documentation: Merchant and auto-payout modules

What you need

• An exchanger on Premium Exchanger 2.7.x. Modules are version-locked: a 2.7 script needs 2.7.* modules, otherwise the site won't load.
• Server access via ISP Manager as the site user (not root).
• A CryptoWay API key with deposit + withdrawal permissions — the API key ID and secret (see Signing).

Step 1. Module files

The module version must match your Premium Exchanger script version (e.g. 271 for 2.7.\*).

Step 2. Upload to the server

Back up the site root folder first. Work through ISP Manager as the site user (not root).

1. Upload the cryptoway folder from m_cryptoway_271.zip to /wp-content/plugins/premiumbox/merchants.
2. Upload the cryptoway folder from pay_cryptoway_271.zip to /wp-content/plugins/premiumbox/paymerchants.
3. If a file-conflict dialog appears, click “Replace”.

Step 3. Add and configure the merchant

In “Merchants” → “Merchants” click “Add” (some merchants exist by default). Fill the form:

• Title — the merchant name shown in the admin panel.
• Module — pick CryptoWay from the dropdown.
• Status — set “active merchant”.

In the module settings, enter the keys from your CryptoWay dashboard:

• API key — API key ID.
• Secret key — your API key's secret.

Step 4. Auto-payouts

The auto-payout module is connected the same way: the “Auto-payouts” section → “Add”, status “active”, the same CryptoWay keys (API key ID + secret). It is bound on the “Merchants and payouts” tab of the direction — for the “You get” currency. Before enabling it, read the “Risk warning” section of the Premium Exchanger docs.

Step 5. Operation modes

The exchanger starts in manual mode. With the modules:

• Merchant only (accept) — accepting is automated: when funds arrive the order moves to “Paid order”, and you pay out manually and set the status to “Completed order”.
• Merchant + auto-payout — full automation: “Paid order” → “Awaiting confirmation from the auto-payout module” → “Completed order”.
• You can enable the “Transfer” button on an order even for an automated direction, so an operator can pay out manually if an auto-payout fails.

Step 6. Verify

Check the connection with the built-in “Merchant diagnostics” (Merchants → Merchants → diagnostics):

• Make sure the server's task scheduler (cron) is configured — without it order statuses won't change automatically.
• If the log shows a “your IP … not in whitelist” error, add your server's IP to the CryptoWay API key whitelist (the allowed_ips parameter).

iEXExchanger

How to connect to iEXExchanger

Connect CryptoWay to an exchange running the iEXExchanger script via the built-in Cryptoway merchant. Once connected, iEXExchanger creates the payment address itself, watches for incoming funds and automatically moves the order to the next status after the payment is confirmed.

The module supports:

• creating payment addresses;
• automatic detection of incoming funds;
• webhook notifications;
• manual and automatic payment checks;
• working with several blockchain networks.

Important. Before enabling the merchant on a live direction, always run a test payment for a small amount. If the API key, Callback Key or network is set incorrectly, the payment address may not be created and automatic processing won't work.

Full iEXExchanger documentation: Cryptoway merchant.

What you need

Before configuring, prepare the data from your CryptoWay dashboard:

• API Key ID
• API Key Secret

To accept crypto, the API key must have the Deposits permission. The Withdrawal permission is for automatic payouts and is not required for an accept-only merchant (see Signing and Deposits).

Step 1. Register and create an API key in CryptoWay

Create an account or sign in at cryptoway.com. Then:

1. Open the “API keys” section.
2. Click “Create API key”.
3. Enter any name for the key.
4. Optionally specify your server's public IP address.
5. Enable the Deposits permission.
6. Confirm the key creation.
7. Copy the Key ID and Key Secret.

Important. The Key Secret is shown only once, at creation — you can't view it again. If you didn't save it, create a new key pair. Store the data securely and never share it with third parties.

If you leave the allowed-IP list empty, CryptoWay may automatically save the IP of the first successful API request — subsequent requests will only be accepted from that IP.

Step 2. Add the merchant

In the iEXExchanger admin, open “Merchants and API” → “Merchant list” and click “Add”. Pick Cryptoway from the module list.

Step 3. Configure the merchant

Fill in the merchant fields:

• API Key ID — the API key identifier from your CryptoWay dashboard (format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Required.
• API Key Secret — the secret part of the API key. It signs the requests that create payment addresses, check incoming funds and fetch the list of available currencies and networks. Required, with no leading or trailing spaces.
• API Base URL — leave the default value https://api.cryptoway.com. Change it only if CryptoWay technical support tells you to; don't put your dashboard address or your exchanger domain here.
• Callback Key — leave empty.

Currency code. Pick the currency-and-network code used in CryptoWay, e.g. USDTTRC20, USDTBEP20 or BNBBEP20. A bare currency code without a network (e.g. USDT) is not allowed — CryptoWay accepts a code bound to a specific blockchain network. If “Automatic” is selected, the system uses the network code from the currency settings; make sure in advance that it matches the currency identifier in CryptoWay.

Max blockchain registration time — set in minutes, recommended value 30. This is how long the system waits for the transaction to register on the blockchain.

Max time to first confirmation — set in hours, recommended value 2. This is how long the system waits for the first transaction confirmation.

Step 4. Bind the merchant to a currency

After saving the merchant, assign it to the right currency. Open “Main” → “Currencies” → “Currency list”, pick the currency, go to the automation section and select Cryptoway as the merchant.

Make sure the selected network matches the network set in the merchant settings. For example:

• Currency: USDT
• Network: TRC20
• CryptoWay code: USDTTRC20
• Merchant: Cryptoway

If one currency is used on several networks, create a separate copy of the merchant for each network.

How payment acceptance works

When an order is created, iEXExchanger sends a request to the CryptoWay API. CryptoWay creates a permanent address and returns it to the system, and the client transfers funds to that address. When the payment reaches the executed status, iEXExchanger automatically moves the order to the next status. To link the payment to the order, iEXExchanger passes the order identifier to CryptoWay.

The amount actually received is taken from the amount value — the sum credited to the CryptoWay balance after the service fee. Account for the CryptoWay fee when configuring the exchange direction: the on-chain transfer amount may differ from the amount actually credited to the balance.

What to check before launch

• API Key ID and API Key Secret are entered correctly;
• the Deposits permission is enabled for the API key;
• API Base URL is https://api.cryptoway.com;
• the currency code and network are set without errors, and no network-less code (e.g. USDT) is used;
• the exchanger backend is reachable over HTTPS;
• the server's public IP is allowed in the API key settings;
• the merchant is bound to the right currency or direction;
• the CryptoWay minimum amount and fee are accounted for;
• request logging is enabled during testing.

Verifying the setup

1. Create a test order.
2. Make sure a payment address appears.
3. Check that the address matches the selected network.
4. Send a small amount.
5. Wait for the payment to be processed.
6. Check that the order status changes.
7. Make sure the payment reaches the executed status.
8. Check that the transaction hash is saved.
9. Reconcile the order amount with the amount credited to the CryptoWay balance.
10. Check the request log: “Event log” → “Merchants and API” → “Merchant request log”.

Recommendations

• Use a separate CryptoWay API key for each exchanger.
• Use different API keys for accepting payments and for automatic payouts.
• Never publish API Key ID and API Key Secret in chats or screenshots.
• Always run a test payment before enabling the merchant on live directions.
• Check the current minimum deposit amount and fee for the selected currency.
• Once verified, you can turn off verbose request logging.

WooCommerce

Cryptoway Payments plugin for WooCommerce

The Cryptoway Payments plugin adds crypto payments to WooCommerce. The customer places an order in the store's standard checkout, pays the invoice on the Cryptoway side, and the order status is updated via a signed webhook.

The plugin supports WooCommerce Checkout Blocks and High-Performance Order Storage.

What you need

Before installing, prepare:

• WordPress 6.0 or newer;
• PHP 8.1 or newer;
• WooCommerce 7.0 or newer;
• a Cryptoway account;
• API Key ID, API Key Secret and Callback Key Secret.

Get your Cryptoway keys

1. Sign in to your Cryptoway dashboard.
2. Open the API keys section and create a key.
3. To accept payments, enable the deposit-operations permission.
4. Save the API Key ID and API Key Secret. The secret is shown only once.
5. In your dashboard profile, copy the Callback Key Secret used to verify webhooks.

Important. Webhooks are verified with the Callback Key Secret, not the API Key Secret. The verification algorithm is described in Signing.

Installation

From WordPress

1. Open Plugins → Add New.
2. Search for Cryptoway Payments.
3. Install and activate the plugin.
4. Make sure WooCommerce is installed and active.

Manually

Upload the plugin files to the directory:

/wp-content/plugins/cryptoway-payments

Then activate the plugin in WordPress.

Configuring the payment method

Open WooCommerce → Settings → Payments → Cryptoway and fill in the parameters.

Save the changes.

How a payment flows

1. The customer selects Cryptoway at checkout.
2. The plugin creates a Cryptoway invoice for the order amount and stores its ID in WooCommerce.
3. The customer goes to the Cryptoway payment page.
4. After payment, Cryptoway sends a signed webhook to the store.
5. The plugin verifies the webhook signature and updates the order.

Invoice statuses

Webhook

The plugin passes the following endpoint to Cryptoway when creating an invoice:

https://your-domain/wp-json/cryptoway/v1/webhook

You don't need to enter this address manually in the plugin settings. For the order to update after payment, these conditions must hold:

• the Callback Key Secret is filled in the settings;
• the WordPress REST API is reachable at /wp-json/cryptoway/v1/webhook;
• hosting, a WAF or other site rules don't block incoming webhooks.

Verifying after setup

1. Create a test order in the store.
2. Select Cryptoway at checkout.
3. Make sure the Cryptoway payment page opens.
4. Check that the order in WooCommerce updates after the invoice status changes.
5. If the status didn't update, open the order and run a manual payment-status check.

Supported assets

The available list depends on the merchant settings and the connected payment methods. Popular assets include: BTC, ETH, USDT, BNB, LTC, TON, TRX.

For USDT, the ERC-20, TRC-20 and TON networks are available. The full up-to-date list is on the Supported Coins page.

Security

• Keep the API Key Secret only in the store settings and never share it with third parties.
• The Callback Key Secret is used to verify the webhook signature. Without it, the plugin won't update the order from an incoming notification.
• The customer pays on the Cryptoway page. The plugin does not request or store the customer's wallet credentials.

Troubleshooting

Fees and support

Current Cryptoway rates start at 0.3% per successful incoming transaction. See the Pricing page for the up-to-date terms.

If you need help with setup:

• API documentation;
• @cryptoway_support_bot;
• Cryptoway contacts.