Crynova API v1

Документація API Crynova

REST API для приймання криптоплатежів. Створюйте рахунки у крипті або фіаті, отримуйте вебхуки про оплату, перевіряйте статуси — за лічені хвилини.

Отримати API-ключ Швидкий старт SDK — Завантажити SDK https://crynova.io/api/v1

Безпечно

HMAC-підпис вебхуків, права ключа, IP-whitelist.

Крипто + фіат

Рахунок у фіаті — клієнт обере крипту на оплаті.

Вебхуки

Миттєві сповіщення про статуси з ретраями.

Вступ

Crynova API дозволяє приймати криптоплатежі програмно. Усі запити — через HTTPS, відповіді — у форматі JSON. Базова інтеграція: створити рахунок, перенаправити клієнта на checkout, отримати вебхук про оплату.

Понад 8 криптовалют і мереж: BTC, ETH, LTC, DOGE, TRON, USDT (TRC20/ERC20/BEP20).

Рахунки у 26 фіатних валютах з автоконвертацією в крипту за курсом.

Підписані вебхуки на події invoice.created/paid/expired та інші.

Idempotency-ключі, права на ключ і захист за IP.

Базовий URL

Усі ендпоінти починаються з базового URL. Усі відповіді — JSON.

HTTP

https://crynova.io/api/v1

Лише HTTPS. HTTP-запити відхиляються.
Усі суми передаються як рядки (string) з точністю до 18 знаків — без float.

Аутентифікація

Передавайте API-ключ у заголовку Authorization (Bearer) або X-Api-Key. Ключ створюється у кабінеті проєкту.

HTTP

Authorization: Bearer cryn_xxxxxxxxxxxxxxxx
# або через заголовок
X-Api-Key: cryn_xxxxxxxxxxxxxxxx

Ніколи не передавайте ключ у query-параметрах чи тілі запиту — він потрапляє в логи й заголовки Referer. Лише заголовок.

Налаштування

1
Зареєструйтесь і створіть проєкт у кабінеті Crynova.
2
Увімкніть потрібні валюти у налаштуваннях проєкту.
3
Створіть API-ключ: Проєкт, API ключі, Create new key. Скопіюйте ключ одразу — він показується лише раз.
4
Вкажіть webhook URL у налаштуваннях, щоб отримувати сповіщення про оплату.

Права API-ключа

Permission	Доступ
currencies.read	Читати список валют
invoices.create	Створювати рахунки
invoices.read	Читати рахунки та статуси
invoices.cancel	Скасовувати рахунки

Якщо при створенні ключа не обрано жодного права — ключ має повний доступ.

GET /api/v1/currencies

Повертає активні криптовалюти (з мережами, мін/макс, комісією) та список фіатних кодів, доступних для рахунків.

cURL

curl https://crynova.io/api/v1/currencies \
  -H "Authorization: Bearer cryn_xxx"

Відповідь

JSON

{
  "data": [
    {
      "code": "USDT_TRC20",
      "name": "Tether USD (TRC-20)",
      "network": "tron",
      "contract_address": "TR7NHq...",
      "decimals": 6,
      "confirmations_required": 20,
      "min_amount": "1",
      "max_amount": null,
      "estimated_fee": "1.4",
      "supports_memo": false
    }
  ],
  "fiat": ["USD","EUR","GBP","JPY","CNY","RUB", ...]
}

GET /api/v1/balance

Повертає баланси мерчанта по кожній валюті: доступно (available), у блокуванні (locked) та загалом (total). Потрібен дозвіл balance.read.

cURL

curl https://crynova.io/api/v1/balance \
  -H "Authorization: Bearer cryn_xxx"

Відповідь

JSON

{
  "data": [
    {
      "currency": "USDT_TRC20",
      "network": "tron",
      "available": "152.40",
      "locked": "0",
      "total": "152.40"
    },
    {
      "currency": "BTC",
      "network": "bitcoin",
      "available": "0.0123",
      "locked": "0",
      "total": "0.0123"
    }
  ]
}

POST /api/v1/invoices

Створює рахунок на оплату. У полі currency передайте крипто-код (пряма оплата) або фіат-код (клієнт обере крипту на checkout).

Параметри

Поле	Тип	Обов`язк.	Опис
currency	string	так	Крипто-код з /currencies (напр. USDT_TRC20) або фіат-код (USD, EUR, UAH).
amount	string\|number	так	Сума у вказаній валюті.
order_id	string	ні	Ваш ідентифікатор замовлення (до 255).
description	string	ні	Опис (до 1000).
expires_in	integer	ні	TTL рахунку у хвилинах (5–1440).
metadata	object	ні	Довільні рядкові пари, повертаються у вебхуку.

Приклад: прямий крипто-рахунок

cURL

curl -X POST https://crynova.io/api/v1/invoices \
  -H "Authorization: Bearer cryn_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1048" \
  -d '{
    "currency": "USDT_TRC20",
    "amount": "25.00",
    "order_id": "ORD-1048",
    "description": "Order #1048",
    "expires_in": 30,
    "metadata": { "customer_id": "42" }
  }'

Відповідь

JSON

{
  "invoice_id": "9ae4cd13-...",
  "order_id": "ORD-1048",
  "status": "pending",
  "price_amount": "25",
  "price_currency": "USDT_TRC20",
  "pay_currency": "USDT_TRC20",
  "currency": "USDT_TRC20",
  "amount": "25.000000000000000000",
  "amount_received": "0",
  "pay_address": "TR7NHq...",
  "pay_memo": null,
  "expires_at": "2026-06-11T12:30:00+00:00",
  "checkout_url": "https://crynova.io/pay/9ae4cd13-...",
  "transactions": []
}

Рахунки у фіаті

Передайте у currency фіатний код — рахунок створюється у фіаті, а клієнт сам обирає криптовалюту на сторінці оплати. Сума конвертується за поточним курсом (офіційні джерела) і фіксується після вибору.

Підтримувані фіатні валюти:

USD, EUR, GBP, JPY, CNY, RUB, INR, AUD, CAD, SGD, HKD, TRY, AED, THB, MYR, PHP, IDR, VND, KZT, UAH, BYN, UZS, KGS, AMD, AZN, PLN

Запит

JSON

{
  "currency": "UAH",
  "amount": "499.00",
  "order_id": "ORD-1001"
}

Відповідь

JSON

{
  "status": "pending",
  "price_amount": "499",
  "price_currency": "UAH",
  "pay_currency": null,
  "amount": null,
  "pay_address": null,
  "checkout_url": "https://crynova.io/pay/..."
}

1 Створіть рахунок з фіатним currency — отримаєте checkout_url.
2 Перенаправте клієнта на checkout_url — він обере крипту, побачить суму за курсом.
3 Після оплати у вебхуку зявляться pay_currency, amount, pay_address.

GET /api/v1/invoices/{invoice_id}

Повертає повну інформацію про рахунок за його UUID.

cURL

curl https://crynova.io/api/v1/invoices/9ae4cd13-... \
  -H "Authorization: Bearer cryn_xxx"

GET /api/v1/invoices/{invoice_id}/status

Легкий ендпоінт для опитування статусу оплати (polling).

JSON

{
  "invoice_id": "9ae4cd13-...",
  "status": "paid",
  "is_final": true,
  "amount": "25.0",
  "amount_received": "25.0",
  "currency": "USDT_TRC20",
  "confirmations": 20,
  "confirmations_required": 20,
  "paid_at": "2026-06-11T12:31:00+00:00"
}

Можливі статуси: pending, waiting_confirmations, paid, underpaid, overpaid, expired, refunded.

GET /api/v1/invoices

Повертає список ваших рахунків з пагінацією та фільтрами.

cURL

curl "https://crynova.io/api/v1/invoices?status=paid&per_page=50" \
  -H "Authorization: Bearer cryn_xxx"

Фільтри: status, order_id, currency, per_page (1–100).

POST /api/v1/invoices/{invoice_id}/cancel

Скасовує рахунок. Можна лише для pending/waiting_confirmations без отриманих коштів.

cURL

curl -X POST https://crynova.io/api/v1/invoices/9ae4cd13-.../cancel \
  -H "Authorization: Bearer cryn_xxx"

GET /api/v1/statistics

Агрегована статистика по рахунках за період: створено, оплачено, конверсія та оборот. Фільтри: date_from, date_to, currency. Потрібен дозвіл statistics.read.

cURL

curl "https://crynova.io/api/v1/statistics?date_from=2026-01-01&date_to=2026-06-30" \
  -H "Authorization: Bearer cryn_xxx"

Відповідь

JSON

{
  "data": {
    "invoices_total": 1280,
    "invoices_paid": 1190,
    "invoices_pending": 14,
    "invoices_expired": 76,
    "conversion": 92.97,
    "paid_volume": [{ "currency": "USD", "amount": "84210.50" }],
    "period": { "from": "2026-01-01", "to": "2026-06-30" }
  }
}

POST /api/v1/withdrawals

Створює запит на виведення коштів. Сума резервується на балансі. Потрібен дозвіл withdrawals.create.

cURL

curl -X POST https://crynova.io/api/v1/withdrawals \
  -H "Authorization: Bearer cryn_xxx" \
  -H "Content-Type: application/json" \
  -d '{"currency":"USDT_TRC20","amount":"50","to_address":"TR7NHq...","memo":null}'

Відповідь

JSON

{
  "withdrawal_id": "0c3f...",
  "status": "pending",
  "currency": "USDT_TRC20",
  "amount": "50",
  "to_address": "TR7NHq...",
  "tx_hash": null,
  "created_at": "2026-06-19T10:00:00+00:00"
}

Виведення створюється зі статусом pending і виконується після підтвердження в адмінпанелі. Список і деталі — через GET-методи (дозвіл withdrawals.read).

GET /api/v1/withdrawals · GET /api/v1/withdrawals/{id}

POST /api/v1/static-wallets

Видає постійну (статичну) адресу для поповнень по валюті — отримай-або-створи. Підтверджені перекази на цю адресу автоматично зараховуються на баланс і надсилають вебхук wallet.deposit. Потрібні дозволи wallets.read / wallets.create.

cURL

curl -X POST https://crynova.io/api/v1/static-wallets \
  -H "Authorization: Bearer cryn_xxx" \
  -H "Content-Type: application/json" \
  -d '{"currency":"BTC"}'

Відповідь

JSON

{
  "currency": "BTC",
  "network": "bitcoin",
  "address": "bc1q...",
  "memo": null
}

H2H (host-to-host)

Прямий крипто-флоу без редіректу: створіть рахунок із крипто-валютою (наприклад BTC) — у відповіді одразу повертаються pay_address і pay_memo, які можна показати клієнту у власному інтерфейсі. Підтвердження оплати приходить вебхуком.

cURL

curl -X POST https://crynova.io/api/v1/invoices \
  -H "Authorization: Bearer cryn_xxx" \
  -H "Content-Type: application/json" \
  -d '{"currency":"BTC","amount":"0.0025","order_id":"H2H-1"}'

Відповідь

JSON

{
  "invoice_id": "8a1c...",
  "status": "pending",
  "pay_currency": "BTC",
  "amount": "0.0025",
  "pay_address": "bc1q...",
  "pay_memo": null,
  "expires_at": "2026-06-19T10:30:00+00:00"
}

Вбудовування чекаута (iframe)

Показуйте чекаут Crynova прямо на своїй сторінці — без редіректу. Підключіть завантажувач embed.js, змонтуйте інвойс, і ваша сторінка отримає сповіщення в реальному часі, щойно його оплачено або він прострочився. Вбудовування дозволено на всіх сторінках /pay/*.

Вбудований блок

HTML

<div id="crynova-checkout"></div>
<script src="https://crynova.io/embed.js"></script>
<script>
  Crynova.checkout({
    uuid: 'INVOICE_UUID',
    mount: '#crynova-checkout',
    onPaid:    function () { window.location = '/thank-you'; },
    onExpired: function () { alert('Payment expired'); }
  });
</script>

Модальне (спливне) вікно

Crynova.open({ uuid: 'INVOICE_UUID', onPaid: fn });

Події

Iframe надсилає вашій сторінці повідомлення (ready, resize, status). SDK перетворює їх на колбеки onReady, onResize, onStatus, onPaid та onExpired. Якщо слухаєте вручну — завжди перевіряйте, що event.origin дорівнює вашому хосту Crynova.

JSON

{ "source": "crynova", "type": "status", "uuid": "9ae4...", "status": "paid", "is_final": true }

onPaid у браузері — лише для UX (редірект, чек). Завжди виконуйте замовлення за підписаним вебхуком — саме він є джерелом правди. Створюйте інвойс на сервері; ніколи не показуйте свій API-ключ у браузері.

Вебхуки

Crynova надсилає POST-запит на ваш webhook URL при зміні статусу рахунку. Кожен запит підписаний HMAC-SHA256.

Подія	Коли
invoice.created	Рахунок створено.
invoice.waiting_confirmations	Транзакція у мемпулі/блоці, очікує підтверджень.
invoice.paid	Оплачено повністю.
invoice.underpaid	Отримано менше суми.
invoice.overpaid	Отримано більше суми.
invoice.expired	Час вийшов або скасовано.
invoice.refunded	Виконано повернення.
wallet.deposit	Підтверджений депозит на статичний гаманець (зараховано на баланс).

Приклад payload

HTTP

POST {your_webhook_url}
X-Crynova-Event: invoice.paid
X-Crynova-Sig: sha256=hmac(secret, body)
X-Crynova-Delivery: 123

{
  "event": "invoice.paid",
  "invoice_id": "9ae4cd13-...",
  "order_id": "ORD-1048",
  "status": "paid",
  "price_amount": "499",
  "price_currency": "UAH",
  "pay_currency": "USDT_TRC20",
  "amount": "12.5",
  "received": "12.5",
  "metadata": { "customer_id": "42" }
}

Перевірка підпису (PHP)

PHP

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CRYNOVA_SIG'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $YOUR_WEBHOOK_SECRET);

if (! hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}
// trusted — process the event
http_response_code(200);

Повтори у разі помилки доставки: 5хв, 30хв, 2г, 8г, 24г. Відповідайте кодом 2xx для підтвердження отримання.

Коди помилок

HTTP	Значення
200	OK — успіх.
401	Невірний або відсутній API-ключ.
403	Немає прав / IP не дозволений / мерчант неактивний.
404	Рахунок не знайдено.
422	Помилка валідації або недопустима дія.
429	Перевищено ліміт запитів.

Ліміти та безпека

Rate limit: 60 запитів/хв на ключ (заголовки X-RateLimit-*).

Idempotency-Key: заголовок робить повторний POST безпечним — повернеться перша відповідь протягом 24 годин.

IP-whitelist: можна обмежити ключ списком IP/CIDR у налаштуваннях ключа.

Права: видавайте ключу лише необхідні дозволи.

Готові інтегруватися?

Створіть проєкт, отримайте API-ключ і прийміть перший платіж за лічені хвилини.

Отримати API-ключ Підтримка