Интеграция по API

REST API, JSON, HTTPS. Базовый URL:

https://zoltopay.com/gw

Быстрый старт

1. Зарегистрируйтесь — API-ключ (формат gw_…) покажется сразу после регистрации. Потерянный ключ можно перевыпустить в кабинете.
2. В кабинете → Настройки: укажите адрес выплат, правила выплат и Callback URL, затем нажмите «Создать новый секрет» для подписи вебхуков.
3. Ваш сервер создаёт инвойс → перенаправляет клиента на pay_url (готовая форма оплаты) → ждёт вебхук invoice.paid → проверяет подпись и статус → выдаёт товар.

Авторизация

Каждый запрос — с заголовком:

Authorization: Bearer gw_ваш_ключ

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

Сети и монеты

Список доступных монет — GET /v1/currencies:

{"currencies":[{"currency_id":"USDT.Tron","coin":"USDT","network":"TRON (TRC-20)",
   "min_payment_usd":"10","payout_fee_usd":"2.99","decimals":6,"confirmations":20,"native":false,"payout":true}],
 "fiat":["USD","EUR","RUB","UAH","KZT","TRY","GBP","AED","CNY","INR"]}

Все монеты

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

Приём и вывод

• Приём — во всех монетах из таблицы.
• USDT и USDC в любой сети зачисляются на USD-баланс 1:1. Вывод USD-баланса — только в USDT TRC-20 (USDT.Tron) или USDT BEP-20 (USDT.BNBSmartChain).
• Титульные монеты (TRX, BNB, ETH, POL, BTC, LTC, DOGE, BCH) зачисляются на баланс в этой монете и выводятся в ней же, в своей сети.
• Прочие токены (DAI и др.) только принимаются. Их баланс можно обменять в кабинете на USDT или титульную монету сети, либо включить автоконвертацию при получении.

Форматы адресов

Мемо и destination tag не нужны: каждый инвойс получает свой адрес или уникальную сумму.

Газ платит Zoltopay: держать TRX, BNB или ETH на своём адресе для приёма или вывода не нужно. Сетевые расходы на вывод покрывает payout_fee_usd.

Создание инвойса

POST /v1/invoices

curl -X POST https://zoltopay.com/gw/v1/invoices \
  -H "Authorization: Bearer gw_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"ORDER-1001","amount":"25","currency":"USDT.Tron","return_url":"https://shop.example/order/1001"}'

Ответ 201 Created (или 200 OK, если инвойс с таким order_id уже есть):

{
  "id": 42,
  "order_id": "ORDER-1001",
  "amount": "25",
  "currency": "USDT.Tron",
  "amount_usd": "25.01",
  "status": "NEW",
  "pay_url": "https://zoltopay.com/checkout/42-9f3c1a7be0d24c55e1aa",
  "pay_address": "TXyz...abc",
  "amount_to_pay": "25.01",
  "addresses": [{"address": "TXyz...abc", "currency_id": "USDT.Tron"}],
  "expires_at": "2026-10-20T12:00:00Z",
  "created_at": "2026-10-20T11:00:00Z"
}

Счёт в фиате

Передайте в currency код фиатной валюты: USD, EUR, RUB, UAH, KZT, TRY, GBP, AED, CNY, INR. Счёт создаётся без монеты — покупатель выбирает её на странице оплаты (pay_url), сумма в монете считается по текущему курсу.

curl -X POST https://zoltopay.com/gw/v1/invoices   -H "Authorization: Bearer gw_ваш_ключ"   -H "Content-Type: application/json"   -d '{"order_id":"ORDER-1002","amount":"50","currency":"EUR"}'

{
  "id": 43,
  "order_id": "ORDER-1002",
  "amount": "50",
  "currency": "EUR",
  "amount_usd": "54.12",
  "status": "NEW",
  "pay_url": "https://zoltopay.com/checkout/43-…",
  "expires_at": "2026-10-21T12:00:00Z",
  "created_at": "2026-10-21T11:00:00Z"
}

• До выбора монеты в ответе нет pay_address; после выбора GET /v1/invoices/{id} вернёт coin, pay_address, amount_to_pay.
• amount_usd — оценка по курсу; после выбора монеты — точная сумма к оплате в USD.
• Курсы обновляются каждые 10 минут. Если курс валюты недоступен, создание счёта вернёт 503 — повторите позже.
• Покупатель выбирает сеть, затем монету: USDT, USDC, BTC, ETH, TRX, BNB, LTC, DOGE и другие. Для USDT/USDC сумма равна сумме в USD; для остальных монет курс фиксируется на 20 минут, потом сумма пересчитывается.
• Оплата в BTC, ETH и других монетах (не USDT/USDC) зачисляется на баланс в этой монете — см. balances в GET /v1/balance. В вебхуке invoice.paid есть currency и amount — монета и сумма платежа.

Форма оплаты (самый быстрый способ)

В ответе на создание инвойса всегда есть pay_url — ссылка на готовую страницу оплаты Zoltopay. Достаточно перенаправить на неё покупателя:

// после POST /v1/invoices
header('Location: ' . $invoice['pay_url']);   // PHP
res.redirect(invoice.pay_url);                // Node.js / Express

На странице покупатель видит название вашего магазина и номер заказа, точную сумму, монету и сеть, адрес с QR-кодом и кнопками «Копировать», таймер до истечения инвойса. Статус обновляется сам: после поступления платежа страница показывает «Оплата получена» и через 5 секунд возвращает покупателя на return_url (если вы его передали).

• Ссылку можно открыть в той же вкладке, в новой или во фрейме, отправить письмом или в мессенджер.
• Страница истёкшего инвойса предупреждает не платить и предлагает вернуться в магазин.
• Возврат на return_url — только для удобства покупателя. Факт оплаты подтверждайте вебхуком invoice.paid или запросом GET /v1/invoices/{id}, а не по факту возврата.

Своя форма оплаты

Если хотите показывать оплату в своём дизайне — используйте pay_address и amount_to_pay из ответа:

• покажите клиенту адрес, сеть (из currency) и точную сумму amount_to_pay (всегда 2 знака после запятой; может быть больше суммы заказа на 0,01–0,99) — с копированием в один клик и QR-кодом адреса;
• предупредите: «переведите ровно эту сумму одним платежом». По сумме платёж находит ваш заказ — если клиент округлит её, платёж уйдёт на ручной разбор;
• покажите таймер до expires_at.

H2H: своя форма с выбором монеты

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

1. Список монет. GET /v1/currencies → покажите выбор: сначала сеть (network), затем монету (coin). Значение для запроса — currency_id.
2. Счёт в фиате. POST /v1/invoices с "currency": "EUR" (или другой фиат). В ответе пока нет адреса.
3. Покупатель выбрал монету → ваш сервер вызывает:

   POST /v1/invoices/{id}/quote

   Поле	Тип		Описание
   currency	string	обязательно	currency_id из GET /v1/currencies, напр. USDT.Tron, BTC.Bitcoin.

   curl -X POST https://zoltopay.com/gw/v1/invoices/43/quote \
     -H "Authorization: Bearer gw_ваш_ключ" \
     -H "Content-Type: application/json" \
     -d '{"currency":"USDT.Tron"}'

   Ответ 200 OK — инвойс с адресом и суммой:

   {
     "id": 43,
     "order_id": "ORDER-1002",
     "amount": "50",
     "currency": "EUR",
     "coin": "USDT.Tron",
     "amount_usd": "54.12",
     "status": "NEW",
     "pay_url": "https://zoltopay.com/checkout/43-…",
     "pay_address": "TXyz...abc",
     "amount_to_pay": "54.12",
     "addresses": [{"address": "TXyz...abc", "currency_id": "USDT.Tron"}],
     "expires_at": "2026-10-21T12:00:00Z",
     "quote_expires_at": "2026-10-21T11:20:00Z",
     "created_at": "2026-10-21T11:00:00Z"
   }

4. Форма оплаты. Покажите pay_address (с QR и копированием), сеть, точную amount_to_pay в монете coin и таймер до quote_expires_at.
5. Статус. Вебхук invoice.paid или опрос GET /v1/invoices/{id} (не чаще раза в 5–10 секунд).

• Курс. Для USDT/USDC сумма = сумме в USD и действует до expires_at. Для BTC, ETH и других монет курс фиксируется на 20 минут (quote_expires_at); после этого вызовите quote ещё раз с той же монетой — сумма пересчитается.
• Смена монеты. Пока инвойс NEW, можно вызвать quote с другой монетой (всего до 10 вызовов quote на инвойс, включая пересчёт курса). Покажите покупателю новый адрес и сумму, старые больше не используйте.
• Ошибки quote: 400 — монета недоступна, инвойс не фиатный, оплачен/истёк или исчерпан лимит смен; 403 — H2H не включён; 404 — инвойс не найден; 503 — курс временно недоступен, повторите.

Статус инвойса

GET /v1/invoices/{id}
GET /v1/invoices?limit=50

Возвращает тот же объект, что и при создании, с актуальными status, paid_at. Используйте как основной способ проверки перед выдачей товара и как запасной, если вебхук не дошёл.

Статусы инвойса

Вебхуки

На ваш Callback URL приходит POST с JSON-телом и заголовками:

Content-Type: application/json
X-Event: invoice.paid
X-Signature: 5f2c…  (hex HMAC-SHA256 тела запроса вашим секретом)

Ответьте любым 2xx в течение 15 секунд. Иначе повторим доставку с нарастающей паузой (до 1 часа между попытками, всего 15 попыток). Обработчик должен быть идемпотентным: одно событие может прийти дважды.

Проверка подписи

Считайте HMAC-SHA256 от сырого тела запроса (до разбора JSON) и сравните с X-Signature в постоянном времени.

PHP

$body = file_get_contents('php://input');
$sig  = hash_hmac('sha256', $body, getenv('ZOLTOPAY_WEBHOOK_SECRET'));
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($body, true);
// дополнительно: GET /v1/invoices/{invoice_id} и проверить status
http_response_code(200);

Node.js (Express)

app.post('/zoltopay/callback', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = crypto.createHmac('sha256', process.env.ZOLTOPAY_WEBHOOK_SECRET)
                    .update(req.body).digest('hex');
  const got = req.get('X-Signature') || '';
  if (sig.length !== got.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(got)))
    return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Python

import hmac, hashlib
sig = hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, request.headers.get("X-Signature", "")):
    abort(401)

Баланс

GET /v1/balance

{"balance_usd": "152.37", "currency": "USD", "mode": "DIRECT_PAYOUT",
 "balances": [{"currency": "USD", "amount": "152.37"}, {"currency": "BTC.Bitcoin", "amount": "0.0012"}]}

balance_usd — баланс в USD (USDT/USDC); balances — все валюты, включая монеты, принятые по фиат-счетам.

Выплаты

Автоматические выплаты (сразу или по порогу) и ручной вывод настраиваются в кабинете. Вывод баланса по API — для автоматизации на вашем сервере. Он выключен по умолчанию и защищён сильнее остального API: даже если ваш API-ключ утечёт, вывести деньги по нему нельзя.

Подключение

1. Попросите поддержку включить выплаты по API и согласуйте лимиты.
2. Кабинет → «API и вебхуки» → «Выплаты по API» (для каждого действия нужен пароль входа):
   • Секрет выплат — отдельный от API-ключа и секрета вебхуков. Показывается один раз, храните его только на сервере.
   • Разрешённые IP вашего сервера, через запятую. Подсеть — не шире /24. Если список пуст, выплаты по API запрещены.
   • Белый список адресов. Выплата возможна только на адрес из списка, а новый адрес начинает работать через 24 часа.

При каждом изменении придёт вебхук security.* (см. «Вебхуки»). Если вы его не ожидали, сразу удалите адрес в кабинете (без пароля) и напишите в поддержку.

Запрос

POST /v1/payouts
Authorization: Bearer gw_ваш_ключ
X-Timestamp: 1792580000        (unix-секунды, допуск ±5 минут)
X-Signature: hex(HMAC-SHA256(секрет_выплат, X-Timestamp + "." + тело))

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

Node.js

const crypto = require('crypto');
const ts   = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({ request_id: 'wd-1001', address: 'TAbc...', amount: '150', currency: 'USDT.Tron' });
const sig  = crypto.createHmac('sha256', process.env.ZOLTOPAY_PAYOUT_SECRET).update(ts + '.' + body).digest('hex');
const res  = await fetch('https://zoltopay.com/gw/v1/payouts', { method: 'POST', body, headers: {
  'Authorization': 'Bearer ' + process.env.ZOLTOPAY_API_KEY, 'Content-Type': 'application/json',
  'X-Timestamp': ts, 'X-Signature': sig } });

PHP

$ts   = (string) time();
$body = json_encode(['request_id' => 'wd-1001', 'address' => 'TAbc...', 'amount' => '150', 'currency' => 'USDT.Tron']);
$sig  = hash_hmac('sha256', $ts . '.' . $body, getenv('ZOLTOPAY_PAYOUT_SECRET'));
$ch = curl_init('https://zoltopay.com/gw/v1/payouts');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ZOLTOPAY_API_KEY'), 'Content-Type: application/json',
                         'X-Timestamp: ' . $ts, 'X-Signature: ' . $sig]]);
$resp = curl_exec($ch);

Python

import hmac, hashlib, json, time, requests
ts   = str(int(time.time()))
body = json.dumps({"request_id": "wd-1001", "address": "TAbc...", "amount": "150", "currency": "USDT.Tron"})
sig  = hmac.new(PAYOUT_SECRET.encode(), (ts + "." + body).encode(), hashlib.sha256).hexdigest()
requests.post("https://zoltopay.com/gw/v1/payouts", data=body, headers={"Authorization": "Bearer " + API_KEY,
    "Content-Type": "application/json", "X-Timestamp": ts, "X-Signature": sig})

Ответ и статусы

202 Accepted — выплата создана; 200 — повтор того же request_id:

{"id":7,"request_id":"wd-1001","address":"TAbc...","amount":"150","currency":"USDT.Tron","status":"SENT"}

Проверка статуса: GET /v1/payouts/{id} (подпись не нужна).

Лимиты

Действуют лимиты на одну выплату и на сумму за 24 часа, а также порог ручной проверки. Текущие значения показаны в кабинете. При превышении вернётся 422.

Ошибки выплат

Ошибки

Тело ошибки: {"error": "описание"}.

Чек-лист перед запуском

• API-ключ хранится только на сервере.
• Задан Callback URL (https) и секрет; подпись проверяется на каждом вебхуке.
• Перед выдачей товара статус проверяется через GET /v1/invoices/{id}.
• Обработчик вебхуков идемпотентен (повтор события не выдаёт товар дважды).
• Клиенту показывается точная сумма amount_to_pay и сеть.
• Указан адрес выплат и настроены правила выплат.
• Для выплат по API: заданы секрет выплат и IP, адреса в белом списке активны, вебхуки security.* кто-то читает.
• Проведён тестовый платёж на минимальную сумму.