API Crynova API Documentation

Introduction

The Crynova API lets you accept crypto payments programmatically. All requests use HTTPS and responses are JSON. Basic flow: create an invoice, redirect the customer to checkout, receive a payment webhook.

8+ cryptocurrencies and networks: BTC, ETH, LTC, DOGE, TRON, USDT (TRC20/ERC20/BEP20).

Invoices in 26 fiat currencies with automatic conversion to crypto at the live rate.

Signed webhooks for invoice.created/paid/expired and more.

Idempotency keys, per-key permissions and IP protection.

Base URL

All endpoints start with the base URL. Every response is JSON.

HTTP

https://crynova.io/api/v1

HTTPS only. HTTP requests are rejected.
All amounts are passed as strings with up to 18 decimals — no floats.

Authentication

Pass the API key in the Authorization header (Bearer) or X-Api-Key. Create a key in your project dashboard.

HTTP

Authorization: Bearer cryn_xxxxxxxxxxxxxxxx
# or via header
X-Api-Key: cryn_xxxxxxxxxxxxxxxx

Never pass the key in query parameters or the request body — it leaks into logs and Referer headers. Use the header only.

Setup

1
Sign up and create a project in the Crynova dashboard.
2
Enable the currencies you need in project settings.
3
Create an API key: Project, API keys, Create new key. Copy it immediately — shown only once.
4
Set a webhook URL in settings to receive payment notifications.

API key permissions

Permission	Access
currencies.read	Read currency list
invoices.create	Create invoices
invoices.read	Read invoices and statuses
invoices.cancel	Cancel invoices

If no permission is selected when creating a key, the key has full access.

GET /api/v1/currencies

Returns active cryptocurrencies (with networks, min/max, fees) and the list of fiat codes usable for invoices.

cURL

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

Response

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

Returns merchant balances per currency: available, locked and total. Requires the balance.read permission.

cURL

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

Response

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

Creates a payment invoice. In currency pass a crypto code (direct payment) or a fiat code (customer picks crypto at checkout).

Parameters

Field	Type	Required	Description
currency	string	yes	Crypto code from /currencies (e.g. USDT_TRC20) or a fiat code (USD, EUR, UAH).
amount	string\|number	yes	Amount in the given currency.
order_id	string	no	Your order identifier (up to 255).
description	string	no	Description (up to 1000).
expires_in	integer	no	Invoice TTL in minutes (5–1440).
metadata	object	no	Arbitrary string pairs, returned in the webhook.

Example: direct crypto invoice

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" }
  }'

Response

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": []
}

Fiat invoices

Pass a fiat code in currency — the invoice is priced in fiat and the customer chooses the crypto at checkout. The amount is converted at the live rate (official sources) and locked once chosen.

Supported fiat currencies:

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

Request

JSON

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

Response

JSON

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

1 Create an invoice with a fiat currency — you get a checkout_url.
2 Redirect the customer to checkout_url — they pick crypto and see the converted amount.
3 After payment the webhook includes pay_currency, amount, pay_address.

GET /api/v1/invoices/{invoice_id}

Returns full information about an invoice by its UUID.

cURL

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

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

A lightweight endpoint for polling the payment status.

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"
}

Possible statuses: pending, waiting_confirmations, paid, underpaid, overpaid, expired, refunded.

GET /api/v1/invoices

Returns a paginated, filterable list of your invoices.

cURL

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

Filters: status, order_id, currency, per_page (1–100).

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

Cancels an invoice. Only pending/waiting_confirmations with no received funds.

cURL

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

GET /api/v1/statistics

Aggregated invoice statistics for a period: created, paid, conversion and turnover. Filters: date_from, date_to, currency. Requires the statistics.read permission.

cURL

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

Response

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

Creates a withdrawal request. The amount is reserved on the balance. Requires the withdrawals.create permission.

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}'

Response

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"
}

Withdrawals are created as pending and executed after approval in the admin panel. List and details via the GET methods (withdrawals.read permission).

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

POST /api/v1/static-wallets

Issues a permanent (static) deposit address per currency — get-or-create. Confirmed transfers to it are credited to your balance automatically and trigger a wallet.deposit webhook. Requires the wallets.read / wallets.create permissions.

cURL

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

Response

JSON

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

H2H (host-to-host)

Direct crypto flow without a redirect: create an invoice with a crypto currency (e.g. BTC) and the response returns pay_address and pay_memo immediately, which you can show in your own UI. Payment confirmation arrives via webhook.

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"}'

Response

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"
}

Embedding checkout (iframe)

Render the Crynova checkout directly inside your own page — no redirect. Include the embed.js loader, mount an invoice, and your page is notified in real time when it is paid or expires. Framing is enabled on all /pay/* pages.

Inline embed

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>

Modal (popup) mode

JS

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

Events

The iframe posts messages to your page (ready, resize, status). The SDK turns them into onReady, onResize, onStatus, onPaid and onExpired callbacks. To listen manually, always verify event.origin equals your Crynova host.

JSON

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

onPaid in the browser is for UX only (redirect, receipt). Always fulfil the order from the signed webhook — it is the source of truth. Create the invoice server-side; never expose your API key in the browser.

Webhooks

Crynova sends a POST request to your webhook URL when an invoice status changes. Every request is HMAC-SHA256 signed.

Event	When
invoice.created	Invoice created.
invoice.waiting_confirmations	Transaction seen, waiting for confirmations.
invoice.paid	Fully paid.
invoice.underpaid	Received less than the amount.
invoice.overpaid	Received more than the amount.
invoice.expired	Time elapsed or canceled.
invoice.refunded	Refund issued.
wallet.deposit	Confirmed deposit to a static wallet (credited to balance).

Payload example

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" }
}

Verify the signature (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);

Delivery retries on failure: 5m, 30m, 2h, 8h, 24h. Respond with 2xx to acknowledge.

Error codes

HTTP	Meaning
200	OK — success.
401	Invalid or missing API key.
403	No permission / IP not allowed / merchant inactive.
404	Invoice not found.
422	Validation error or invalid action.
429	Rate limit exceeded.

Limits & security

Rate limit: 60 requests/min per key (X-RateLimit-* headers).

Idempotency-Key: header makes a repeated POST safe — returns the first response within 24 hours.

IP whitelist: restrict a key to a list of IPs/CIDRs in the key settings.

Permissions: grant a key only the scopes it needs.

Crynova API Documentation

Introduction

Base URL

Authentication

Setup

API key permissions

Parameters

Fiat invoices

H2H (host-to-host)

Embedding checkout (iframe)

Webhooks

Error codes

Limits & security

Ready to integrate?