CryptoFlix API

The flow

Authentication

Each site gets its own API key (cf_live_…). Send it as Authorization: Bearer <key> on POST /api/invoices — server-side only, never in the browser. Reads (invoice, status, coins) are open (the id is unguessable). Every invoice is attributed to its key, so the dashboard shows sales per site.

Endpoints

Base URL https://crypto.flixdrama.xyz · POST /api/invoices needs your key; reads are open.

1 · Create an invoice

curl -X POST https://crypto.flixdrama.xyz/api/invoices \
  -H 'authorization: Bearer cf_live_your_site_key' \
  -H 'content-type: application/json' \
  -d '{
    "ticker": "trc20/usdt",
    "amount": "5",
    "reference": "order-1042",
    "successUrl": "https://yourstore.com/thanks",
    "notifyUrl":  "https://yourstore.com/cryptoflix-webhook",
    "metadata":   { "orderId": 1042 }
  }'

Response:

{
  "id": "99d36aee-4e7a-4220-8225-70d4ed942a45",
  "ticker": "trc20/usdt",
  "symbol": "USDT",
  "chain": "TRON",
  "amount": "5",
  "address": "TPaymentAddress…",      // show this to the customer
  "payUri": "TPaymentAddress…",        // or BIP21 for btc/ltc
  "qr": "data:image/png;base64,…",     // ready-to-render QR
  "status": "new",
  "requiredConfirmations": 1,
  "expiresAt": "2026-06-01T12:00:00Z"
}

Price in fiat

Send a fiat amount instead of a coin amount and CryptoFlix converts it at creation:

# Price in fiat — CryptoFlix converts to the coin amount at creation time
-d '{ "ticker": "btc", "fiatAmount": "19.99", "fiatCurrency": "USD" }'

2 · Show your own checkout (recommended)

Keep the customer on your domain. The create response gives you everything to render a checkout in your own design — address, payUri, a ready-to-show qr (data-URL), amount and expiresAt. Funds still forward straight to your wallet.

// 1) your server creates the invoice (never the browser)
const invoice = await fetch('https://crypto.flixdrama.xyz/api/invoices', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    authorization: 'Bearer ' + process.env.CRYPTOFLIX_KEY,  // this site's key
  },
  body: JSON.stringify({ ticker, amount, successUrl, metadata })
}).then((r) => r.json())

// 2) redirect to YOUR OWN checkout page — the customer never leaves your site.
//    Render invoice.address + invoice.qr there, styled however you like.
return Response.redirect('/checkout/' + invoice.id, 303)

Then poll for status. The browser can’t hit the API directly (it’s CORS-locked), so proxy a tiny status route through your own server and poll that — exactly what this sandbox’s /checkout/<id> page does:

// 3) the browser can't call the API directly (it's CORS-locked), so poll a
//    thin proxy on YOUR server from the checkout page every few seconds:
// GET /checkout/:id/status  →
const s = await fetch('https://crypto.flixdrama.xyz/api/invoices/' + id + '/status')
return Response.json(await s.json())   // same-origin to the browser ✓

Prefer zero frontend work? There’s also a hosted checkout at /pay/<id> you can redirect to instead — same flow, but on the CryptoFlix domain. This sandbox uses the embedded approach so you stay on-brand.

3 · Confirm the payment

Poll status from your server (don’t trust the browser redirect alone for fulfilment):

curl https://crypto.flixdrama.xyz/api/invoices/<id>/status

{
  "id": "99d36aee…",
  "status": "confirmed",        // new → pending → confirmed | underpaid | expired
  "confirmations": 1,
  "requiredConfirmations": 1,
  "paid": "5",
  "amount": "5"
}

Reliability: a reconcile worker re-checks every open invoice against the chain, so even if a confirmation is missed in real time, status becomes correct within ~a minute. Build fulfilment around confirmed.

4 · Webhooks (best for fulfilment)

Prefer push over poll: pass a notifyUrl when creating the invoice and CryptoFlix POSTs it on every status change — so fulfilment never depends on the customer’s browser finishing the redirect. Each event is sent once and retried with backoff (~1m → 12h) until your endpoint returns 2xx.

{
  "event": "invoice.confirmed",       // .pending .confirmed .underpaid .expired
  "timestamp": "2026-06-01T12:00:00Z",
  "invoice": {
    "id": "99d36aee…", "reference": "order-1042",
    "ticker": "trc20/usdt", "symbol": "USDT", "chain": "TRON",
    "amount": "5", "paid": "5", "status": "confirmed",
    "confirmations": 1, "requiredConfirmations": 1,
    "txidIn": "…", "metadata": { "orderId": 1042 }
  }
}

Every request carries X-CryptoFlix-Signature: sha256=<hex> — an HMAC of the raw body with your signing secret. Always verify it and reply 2xx (a non-2xx triggers a retry):

// your webhook endpoint — verify the signature, then mark the order paid
import { createHmac, timingSafeEqual } from 'node:crypto'
const raw = await readRawBody(req)                 // the EXACT bytes received
const sig = req.headers['x-cryptoflix-signature']  // "sha256=<hex>"
const expected = 'sha256=' + createHmac('sha256', SECRET).update(raw).digest('hex')
if (sig !== expected) return res.status(401).end() // reject forgeries → we retry
const { event, invoice } = JSON.parse(raw)
if (event === 'invoice.confirmed') fulfilOrder(invoice.reference)
return res.status(200).end()                        // 2xx = acknowledged

This sandbox eats its own dog food: it passes notifyUrl to its own /api/cryptoflix-webhook receiver, verifies the signature, and shows “Server webhook received ✓” on the success page after you pay.

Coins & health

GET /api/coins — render a picker; only ready: true coins can take payments.

[
  { "ticker": "trc20/usdt", "symbol": "USDT", "chain": "TRON",
    "decimals": 6, "icon": "usdt", "ready": true },
  …
]

GET /health — 200 when healthy, 503 when down. Wire it into uptime monitoring.

{ "status": "ok", "checks": { "database": {…}, "cryptapi": {…},
  "reconcile": {…} }, "invoices": { "open": 3, "pendingOverdue": 0 } }