API overview

Product 1 of 2

Crypto Billing API #

Issue invoices priced in crypto or fiat, let the payer choose one of the allowed assets on the hosted checkout (or in the widget on your site), and get your share settled to your balance or your wallets. Partial, late and over payments wait for your decision; refunds go back to the address that paid; payouts pay your customers from a separate payout wallet.

Share this section: https://cryptonera.com/developers#crypto-billing

https://cryptonera.com/api/v1

ck_<env>_<prefix>_<secret>

e.g. ck_sandbox_Ab12Cd34Ef56_<40–64 alphanumeric characters>

Authorization: Bearer ck_sandbox_Ab12Cd34Ef56_…

Idempotency-Key: 6f0b5c1e-2d4a-4b8e-9a37-1c5e8f2d7a90

{
  "object": "list",
  "data": [ … ],
  "next_cursor": "eyJpZCI6…",
  "has_more": true,
  "request_id": "req_…"
}

2. Create an invoice #

Headers #

Parameters #

Only pricing_mode, currency and amount are required; with the dashboard set up (simple integration) that and order_id are all you send. merchant_reference was renamed to order_id (sending it is a 422).

Asset identifiers (allowed_assets) #

Send these exact identifiers in allowed_assets (and in currency when the invoice is priced in crypto). An identifier names the coin and its network, so USDT alone is refused: say USDT_TRON or USDT_ETHEREUM. Upper or lower case both work, and the same identifier is used in sandbox and live. The list below is read from this platform as you open the page: when the operator switches an asset off it disappears here and POST /invoices answers 422 for it.

A store's payment assets, ticked once in the dashboard (Stores → Edit → Payment assets), are enforced on every invoice of that store that settles to a wallet, from the API and the dashboard: a fiat-priced invoice offers exactly those that can be paid in your key's environment, and any allowed_assets the request sends is ignored. A crypto-priced invoice must name one of them as its currency; another coin gets 422 with "reason": "asset_not_in_store". A splitter invoice is paid in the splitter's asset. For a store without payment assets each request chooses: send allowed_assets (a crypto-priced invoice uses its currency, a splitter invoice the splitter's asset). If no payment asset is left for the invoice, POST /invoices answers 422 with "reason": "allowed_assets_missing" and a link to the store page.

"allowed_assets": ["USDT_TRON", "USDC_BASE", "BTC_BITCOIN"]

• Decimals: the most digits after the point an amount may have for a crypto-priced invoice. Minimum: the smallest amount an option may ask for.
• The settlement_addresses key is the kind of network: one address per key covers every asset with that key (one 0x… for all evm assets), see where settlements go.
• Live also needs your account's live access. Fiat-priced invoices need the operator's price source. Contracts, confirmations and fees: supported assets. Your key's own view: GET /assets (assets:read), entries with capabilities.invoice_payment_option: true.

Fiat currencies (currency) #

For "pricing_mode": "fiat" send an ISO-4217 code in currency (USD, EUR, JPY …; upper or lower case). The amount is converted at a locked quote from the operator's price source, so the code must also be one that source quotes; any other code is refused with 422 on currency before a quote is taken.

• Sandbox: Coinbase, 149 of the 155 currencies below.
• Live: Coinbase, 149 of the 155 currencies below.

Duplicate protection: order_id #

Send your order number as order_id. Per store and environment, compared exactly (case-sensitive). Only the terms of the order are compared:

• pricing_mode;
• currency, in any case (usd = USD);
• amount, as a number (25 = 25.00);
• allowed_assets, as a set (order and case do not matter), and only when your request chose them. The store's payment assets and its default splitter are settings: changing them never refuses the same order.

On a repeat every other field is ignored: description, lines, metadata, customer ID and email, return and cancel URLs, expiry, checkout theme and settlement (type, splitter, addresses). You get the original invoice back unchanged, and its expiry is not extended. A splitter you name counts only when it decides the allowed assets (fiat pricing without allowed_assets): then its asset is compared. To change anything else, cancel the open invoice and create a new one.

So a timeout is harmless: send the same request again. Without order_id every request is a new invoice (an Idempotency-Key then protects the retry).

Example #

A 49.99 USD invoice for order 1042, payable in the store's payment assets and settled the way your settlement schedule says (into your balance on on_request, the default; to your settlement wallets on per_invoice and daily):

curl -X POST https://cryptonera.com/api/v1/invoices \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_mode": "fiat",
    "currency": "USD",
    "amount": "49.99",
    "order_id": "order-1042",
    "customer_email": "[email protected]",
    "expires_in_seconds": 3600
  }'

<?php
$body = [
    'pricing_mode' => 'fiat',
    'currency' => 'USD',
    'amount' => '49.99',            // a string, never a float
    'order_id' => 'order-1042',     // your order number
    'customer_email' => '[email protected]',
];
$ch = curl_init('https://cryptonera.com/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CRYPTONERA_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($raw === false) {
    // network error: send the same request again (order_id makes it safe)
}
$invoice = json_decode((string) $raw, true);
if ($status === 201 || $status === 200) {
    // 200: this order already has an open invoice with the same terms ("created": false)
    header('Location: '.$invoice['checkout_url']);
} else {
    error_log($invoice['error']['code'].': '.$invoice['error']['message']);
}

// Node.js 18+ (server side only: never put your API key in a browser)
const res = await fetch('https://cryptonera.com/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRYPTONERA_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pricing_mode: 'fiat',
    currency: 'USD',
    amount: '49.99', // a string, never a number
    order_id: 'order-1042',
    customer_email: '[email protected]',
  }),
});
const invoice = await res.json();
if (res.status === 201 || res.status === 200) {
  // send the payer to invoice.checkout_url; keep invoice.id and invoice.transaction_id
} else {
  console.error(invoice.error.code, invoice.error.message);
}

Response 201 Created:

{
  "id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
  "object": "invoice",
  "transaction_id": "TST-7K3M-9QX2-H4PD",
  "number": "INV-MAIN-000123",
  "order_id": "order-1042",
  "store_id": "01J9Z2K7QH4M8N3P5R6S7T8V9W",
  "environment": "sandbox",
  "status": "awaiting_payment",
  "settlement_status": "not_started",
  "pricing_mode": "fiat",
  "currency": "USD",
  "amount": "49.99",
  "amount_asset": null,
  "amount_paid": "0",
  "amount_pending": "0",
  "amount_due": null,
  "needs_decision": false,
  "decision": null,
  "description": null,
  "lines": null,
  "customer_id": null,
  "customer_email": "[email protected]",
  "allowed_assets": ["USDT_TRON", "USDC_BASE"],
  "settlement_type": "wallet",
  "rate_source": "coingecko",
  "payment_options": [
    {
      "id": "01J9Z3A1B2C3D4E5F6G7H8J9KN",
      "asset": "USDT_TRON",
      "status": "pending_address",
      "required_amount": "49.990000",
      "received_confirmed": "0.000000",
      "received_unconfirmed": "0.000000",
      "address": null,
      "quote_expires_at": "2026-10-12T11:00:00+00:00"
    },
    {
      "id": "01J9Z3A1B2C3D4E5F6G7H8J9KP",
      "asset": "USDC_BASE",
      "status": "pending_address",
      "required_amount": "49.990000",
      "received_confirmed": "0.000000",
      "received_unconfirmed": "0.000000",
      "address": null,
      "quote_expires_at": "2026-10-12T11:00:00+00:00"
    }
  ],
  "payer_addresses": [],
  "refund": null,
  "metadata": {},
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://cryptonera.com/pay/i/<public-token>",
  "checkout_theme": "modern",
  "expires_at": "2026-10-12T11:00:00+00:00",
  "paid_at": null,
  "cancelled_at": null,
  "created_at": "2026-10-12T10:00:00+00:00",
  "created": true,
  "request_id": "req_01J9Z3A1B2C3D4E5F6G7H8J9KQ"
}

The same order again while this invoice is open, with the same terms: 200, the same object and "created": false. With other terms:

{
  "error": {
    "code": "order_id_in_use",
    "message": "Order \"order-1042\" already has open invoice INV-MAIN-000123 (TST-7K3M-9QX2-H4PD) in this store with a different amount. Cancel it first, or use another order_id.",
    "retryable": false,
    "request_id": "req_01J9Z3A1B2C3D4E5F6G7H8J9KR",
    "order_id": "order-1042",
    "existing_invoice": {
      "id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
      "transaction_id": "TST-7K3M-9QX2-H4PD",
      "number": "INV-MAIN-000123",
      "status": "awaiting_payment",
      "amount": "49.99",
      "currency": "USD",
      "allowed_assets": ["USDT_TRON", "USDC_BASE"],
      "checkout_url": "https://cryptonera.com/pay/i/<public-token>",
      "created_at": "2026-10-12T10:00:00+00:00"
    },
    "differences": ["amount"]
  }
}

Send the payer to checkout_url (or show it in the widget); keep id and transaction_id with your order. A payment option's address is allocated when the payer chooses it, so payment_options[].address is null until then. To settle through a splitter instead of your wallets, send "settlement_type": "splitter" and "settlement_target_id".

Response: the invoice object #

Every key is always present (null when empty), in this order. POST /invoices adds created; every answer adds request_id.

The payment option object #

Which payment is which #

Every invoice is one customer payment. Keep these identifiers next to your order:

In the dashboard, Payments → Invoices and Money → Settlements, Refunds and Payouts find a payment by any of these.

Where settlements go (settlement wallets) #

A wallet-settled invoice ("settlement_type": "wallet") on the per_invoice and daily settlement schedules pays the confirmed amount, minus the platform fee, to your address on the network the customer paid on (daily: with the next daily settlement). On on_request, the default schedule, your share is credited to your balance instead and this address is not used: a withdrawal goes to the settlement wallet saved when you withdraw (or, while the lock is off, to the destination_address you send). Either way an invoice needs one address for every allowed asset. Save them once in the dashboard (Payments → Settlement wallets) and send none: with the settlement lock on (the default) those are the only addresses used. The address is the first of these that has one (1 and 2 only while the lock is off; on on_request an address sent in the request is used only if a payment has to be settled on its own because your collection address is not ready yet):

Settlement wallets are kept separately for sandbox and live: switch the dashboard to the environment of your API key (sidebar → Environment) before saving. The address is copied into the invoice when it is created, so on the per_invoice and daily schedules later changes never move that invoice's settlement; on on_request money already in your balance goes wherever your withdrawal goes. An address of this platform (a payment, collection or payout wallet address it holds the keys for) is never accepted as a settlement address, saved or sent: the money would stay in the platform's custody instead of reaching you. A request that sends no settlement_type (and no splitter or address) gets the store's default: its saved settlement wallets, or its splitter (Dashboard → Stores → Edit → Default settlement for invoices: "Settlement wallets" or "Splitter rule"). "settlement_type": "wallet" settles to the saved wallets even when the store's default is a splitter. "settlement_type": "splitter" without an id uses the store's default splitter (a store set to Settlement wallets has none: 422 store_settlement_invalid); naming one with "settlement_target_id" works only while the lock is off. Invoices created in the dashboard always use the saved settlement wallets (they never name an address, lock on or off), or a splitter chosen on the form.

When an allowed asset has no address from any of these, POST /invoices answers 422 with the fields and a hint saying exactly where to add it (the same in sandbox, plus a note about test networks there):

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "retryable": false,
    "request_id": "req_…",
    "fields": {
      "settlement_addresses.tron": [
        "No settlement wallet is saved for USDT_TRON: save a Tron (T…) address under Settlement wallets."
      ]
    },
    "reason": "settlement_destination_missing",
    "environment": "sandbox",
    "settlement_lock": true,
    "missing": [
      {
        "family": "tron",
        "label": "Tron (T…)",
        "assets": ["USDT_TRON"]
      }
    ],
    "hint": "This invoice has no settlement address for USDT_TRON … open Payments → Settlement wallets and save the address …",
    "dashboard_url": "https://cryptonera.com/dashboard/settlement-wallets",
    "docs_url": "https://cryptonera.com/developers#billing-settlement-lock"
  }
}

This error does not use up the Idempotency-Key: save the address, then retry the same request with the same key. (With the lock off the message also offers sending settlement_addresses, and docs_url ends in #billing-settlement.)

Settlement lock #

Every account starts with the settlement lock on, separately for sandbox and live (Dashboard → Payments → Settlement wallets). While it is on, invoices are settled only to the settlement wallets saved in the dashboard, and a request that names a settlement address or a splitter is refused. So if someone changes the code of your website, or gets hold of an API key, they still cannot send your payments to their own address. Only the account owner can turn the lock off (password confirmed; recorded in the audit log).

While the lock is on, POST /invoices refuses settlement_address, settlement_addresses and settlement_target_id (empty values count as not sent) with 422, before anything is created. missing lists the allowed assets that also have no saved wallet yet (never the saved addresses):

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "retryable": false,
    "request_id": "req_…",
    "fields": {
      "settlement_address": [
        "Not accepted: this account pays out only to its saved settlement wallets (Dashboard → Payments → Settlement wallets). Remove this field."
      ]
    },
    "reason": "settlement_address_locked",
    "environment": "live",
    "settlement_lock": true,
    "missing": [],
    "hint": "Settlements of this account are locked to the settlement wallets saved in the dashboard, so \"settlement_address\" cannot be sent. Remove it: …",
    "dashboard_url": "https://cryptonera.com/dashboard/settlement-wallets",
    "docs_url": "https://cryptonera.com/developers#billing-settlement-lock"
  }
}

Remove the field and retry; the Idempotency-Key is not used up. The lock covers invoices: PATCH /splitters/{id} is refused the same way (field recipients) for a splitter that settles invoices (a store's default settlement, or the target of an invoice not settled yet), and a store's default splitter is used only for invoices of its own environment. Withdrawals of your balance (POST /withdrawals) go only to the saved settlement wallets while the lock is on. Refunds created through the API go back only to an address that paid the invoice (another address only when no paying address is known and Refunds → Refund settings → "Allow a refund address from the API" is on), and they are sent at once unless "Refunds from the API need approval" is on. Payouts from the API go only to the destinations Payouts → Payout settings allow (by default, addresses that paid you before), and they wait for a finance member's approval only while "API payouts need approval" is on. Split sessions and new splitters created through the API name their own recipients: give an API key only the scopes it needs (an invoice integration needs invoices:write, not refunds:write, payouts:write, splitters:write or sessions:write).

Checkout designs (checkout_theme) #

The hosted checkout (checkout_url) comes in 5 designs. Only the look changes: every design shows the same amounts, address, QR code, warnings and live status. Choose one per invoice with "checkout_theme" when you create it; without it the invoice uses its store's default design (Dashboard → Stores), else modern. The invoice response echoes the design in checkout_theme.

List the designs with their preview links from the API (any key with invoices:read):

GET https://cryptonera.com/api/v1/checkout-themes
Authorization: Bearer ck_sandbox_Ab12Cd34Ef56_…

{
  "object": "list",
  "default": "modern",
  "data": [
    {
      "object": "checkout_theme",
      "key": "modern",
      "name": "Modern",
      "description": "Clean, centred payment card with a progress bar and steps. The default.",
      "default": true,
      "preview_url": "https://cryptonera.com/pay/preview/modern/pay",
      "preview_urls": {
        "choose": "…",
        "pay": "…",
        "confirming": "…",
        "paid": "…",
        "expired": "…"
      }
    },
    {
      "object": "checkout_theme",
      "key": "classic",
      "name": "Classic",
      "description": "Conservative and wide, with a solid header in your brand colour.",
      "default": false,
      "preview_url": "https://cryptonera.com/pay/preview/classic/pay",
      "preview_urls": {
        "choose": "…",
        "pay": "…",
        "confirming": "…",
        "paid": "…",
        "expired": "…"
      }
    },
    …
  ],
  "request_id": "req_…"
}

To show one invoice in another design without creating it again, add ?theme=<key> to its checkout_url (display only; an unknown key is ignored). The same designs are available in the embedded checkout widget.

3. Simple integration with the widget #

curl -X POST https://cryptonera.com/api/v1/invoices \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_mode": "fiat",
    "currency": "USD",
    "amount": "49.99",
    "order_id": "order-1042",
    "expires_in_seconds": 3600
  }'

{
  "id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
  "object": "invoice",
  "transaction_id": "TST-7K3M-9QX2-H4PD",
  "number": "INV-MAIN-000123",
  "order_id": "order-1042",
  "store_id": "YOUR_STORE_ID",
  "status": "awaiting_payment",
  "environment": "sandbox",
  "pricing_mode": "fiat",
  "currency": "USD",
  "amount": "49.99",
  "allowed_assets": ["USDT_TRON", "USDC_BASE"],
  "settlement_type": "wallet",
  "checkout_url": "https://cryptonera.com/pay/i/<token>",
  "expires_at": "2026-09-22T11:00:00+00:00",
  "created_at": "2026-09-22T10:00:00+00:00",
  "created": true,
  …
}

<script
  src="https://cryptonera.com/widget/v1.0.0/cryptonera.js"
  integrity="sha384-TAdsG7ASjU0jWvpWxxPDKatsUF4TLIjr3axGD3/yeIYi/rzHadjBioiah0olsZyX"
  crossorigin="anonymous"
  data-store="YOUR_STORE_ID"
  async></script>

<button
  data-cryptonera-checkout="CHECKOUT_URL"
  data-invoice-id="INVOICE_ID"
  data-cryptonera-button="dark">Pay with crypto</button>

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "retryable": false,
    "request_id": "req_…",
    "fields": {
      "allowed_assets": [
        "Send allowed_assets, or choose payment assets for store \"Main store\" (Stores → Edit → Payment assets)."
      ]
    },
    "reason": "allowed_assets_missing",
    "environment": "sandbox",
    "store_id": "YOUR_STORE_ID",
    "hint": "This invoice names no allowed_assets and store \"Main store\" has no payment assets chosen. Either send \"allowed_assets\" … or ask the account owner to tick the coins this store accepts: Dashboard → Stores → Edit \"Main store\" → Payment assets … retry with the same key.",
    "dashboard_url": "https://cryptonera.com/dashboard/stores/YOUR_STORE_ID/edit",
    "docs_url": "https://cryptonera.com/developers#allowed-assets"
  }
}

Embedded checkout widget #

curl -X POST https://cryptonera.com/api/v1/invoices \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_mode": "fiat",
    "currency": "USD",
    "amount": "49.99",
    "order_id": "order-1042",
    "expires_in_seconds": 3600,
    "checkout_theme": "midnight"
  }'

{
  "id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
  "object": "invoice",
  "status": "awaiting_payment",
  "checkout_url": "https://cryptonera.com/pay/i/<token>",
  "checkout_theme": "midnight",
  …
}

<script
  src="https://cryptonera.com/widget/v1.0.0/cryptonera.js"
  integrity="sha384-TAdsG7ASjU0jWvpWxxPDKatsUF4TLIjr3axGD3/yeIYi/rzHadjBioiah0olsZyX"
  crossorigin="anonymous"
  data-store="YOUR_STORE_ID"
  async></script>

<!-- or always the newest 1.x (no integrity):
     https://cryptonera.com/widget/v1/cryptonera.js -->

<button
  data-cryptonera-checkout="CHECKOUT_URL"
  data-invoice-id="INVOICE_ID"
  data-cryptonera-button="dark"
  data-layout="modal"
  data-theme="midnight">Pay with crypto</button>

<!-- inline, in the page -->
<div
  data-cryptonera-inline="CHECKOUT_URL"
  data-invoice-id="INVOICE_ID"
  data-theme="minimal"></div>

const pay = Cryptonera.open(invoice.checkout_url, {
  // the widget closes if the frame shows another invoice
  invoiceId: invoice.id,
  // auto (pop-up, bottom sheet on phones) · modal · drawer · sheet
  layout: 'auto',
  // modern · classic · minimal · midnight · vivid (omit: the invoice's design)
  theme: 'vivid',
  // close 4 s after the payment is confirmed (omit: stay open)
  closeOnPaid: 4000,
  // e: { id, invoice, status, livemode, preview, theme }
  onReady: (e) => {},
  onStatus: (e) => updateBadge(e.status),
  // a hint for your page only, see below
  onPaid: (e) => showThankYou(),
  onExpired: (e) => offerNewInvoice(),
  onClose: () => {},
});

// inline, grows with its content
Cryptonera.mount('#pay', invoice.checkout_url, {
  invoiceId: invoice.id,
  theme: 'minimal',
});

Cryptonera.close();

script-src … https://cryptonera.com;
frame-src  … https://cryptonera.com;

4. Other endpoints #

Every Crypto Billing endpoint and the ones both products share. The scope and the Idempotency-Key rule come from the platform's routes.

Find, cancel and accept invoices #

GET /invoices lists invoices newest first; GET /invoices/{id} and the actions take the Payment ID or the transaction_id (any case, dashes optional). Filters of the list:

POST /invoices/{id}/cancel cancels an open invoice (a partly paid one becomes underpaid, its confirmed money held for your decision):

Partial, late and extra payments. Only confirmed money counts. An invoice that closes with a partial payment becomes underpaid; money that arrives after it closed is held and the invoice becomes underpaid or paid_late; an excess, or a payment at a second option, is held too. Held money waits for your decision (needs_decision: true, decision.status: needed, webhooks invoice.underpaid, invoice.late_payment, invoice.paid_late, invoice.payment_held): accept it with POST /invoices/{id}/accept, or refund it. Accepting settles it like a payment with the invoice's fee (an underpaid or paid-late invoice becomes paid: invoice.accepted, then invoice.paid); it answers 202 and is planned within about a minute (invoice.accept_failed when it cannot be). An open, partly paid invoice can be accepted early (it closes at once). Body:

The decision object #

Refunds #

• Only to an address that paid the invoice (by default the payer of its largest confirmed payment); another address only when none is known and the owner allows it.
• Once per invoice, at most what was paid. A fiat-priced invoice is refunded in its currency, converted at the current rate (rounded down; the quote is stored); another token sent to its address (no payment option of the invoice) in that token.
• Paid from the invoice's held money when it covers the refund and its network fee, else from your balance (or, if you ask, your payout wallet). The customer receives the exact amount; the network fee is charged to you on top. No commission.
• Not enough in your balance: 202 with status queued (refund.queued and an email); it is sent automatically, oldest first, once the balance suffices. You may cancel it until then. If the invoice's confirmed payment no longer covers it by then (a payment reorganized away), it fails with paid_amount_changed and nothing is taken.
• With "Refunds from the API need approval" on, an API refund waits as pending_approval for a finance user in the dashboard.

# a new UUID for every refund; the same one only to retry it
curl -X POST https://cryptonera.com/api/v1/refunds \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c2a9e-8d4b-4c6f-9e21-7a5b0c3d4e6f" \
  -d '{
    "transaction_id": "TST-7K3M-9QX2-H4PD",
    "amount": "20.00",
    "reason": "Order 1042 returned"
  }'

Response 201 Created:

{
  "id": "01J9Z4B2C3D4E5F6G7H8J9KMNP",
  "object": "refund",
  "status": "processing",
  "status_reason": null,
  "environment": "sandbox",
  "invoice_id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
  "transaction_id": "TST-7K3M-9QX2-H4PD",
  "invoice_number": "INV-MAIN-000123",
  "order_id": "order-1042",
  "customer_id": null,
  "customer_email": "[email protected]",
  "asset": "USDT_TRON",
  "amount": "20.000000",
  "fiat_currency": "USD",
  "fiat_amount": "20.00",
  "quote": {
    "rate": "1.000000",
    "source": "coingecko",
    "fetched_at": "2026-10-14T09:00:00+00:00"
  },
  "network_fee": "1.100000",
  "network_fee_final": true,
  "total_charged": "21.100000",
  "funding_source": "balance",
  "destination": "<payer-tron-address>",
  "destination_memo": null,
  "destination_type": "payer_address",
  "reason": "Order 1042 returned",
  "created_via": "api",
  "settlement_id": "01J9Z4B2C3D4E5F6G7H8J9KMNQ",
  "tx_hash": null,
  "explorer_url": null,
  "funds_returned": false,
  "created_at": "2026-10-14T09:00:00+00:00",
  "approved_at": null,
  "funded_at": "2026-10-14T09:00:00+00:00",
  "completed_at": null,
  "failed_at": null,
  "cancelled_at": null,
  "request_id": "req_01J9Z4B2C3D4E5F6G7H8J9KMNR"
}

The refund object #

GET /refunds filters (exact):

POST /refunds/{id}/cancel cancels a refund that is still queued or pending_approval.

Payouts to your customers #

A payout pays one of your customers (a cashback, winnings, a refund outside an invoice) from your payout wallet: one address per chain family and environment (one for every EVM network), created with POST /payout-wallets and funded by sending money to it or with "Move from balance" in the dashboard. On EVM and Tron it holds tokens only: ETH, POL or TRX sent there fund your gas budget. Your settings (Payouts → Settings) decide where payouts may go: by default only addresses that paid you before; also customers with a paid invoice by customer_id or customer_email, or any address; payouts from the API on or off; approval in the dashboard. The customer receives the exact amount; the network fee is charged on top. Not enough in the payout wallet: 409 insufficient_balance and nothing is created (payouts are never queued).

# a new UUID for every payout; the same one only to retry it
curl -X POST https://cryptonera.com/api/v1/payouts \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2e4c71-5a3d-4f08-b6e2-1c7d9a0f3e54" \
  -d '{
    "asset": "USDT_TRON",
    "amount": "15.00",
    "destination": "<customer-tron-address>",
    "customer_id": "cust-77",
    "note": "Cashback October"
  }'

Response 201 Created:

{
  "id": "01J9Z5C3D4E5F6G7H8J9KMNPQR",
  "object": "payout",
  "status": "processing",
  "status_reason": null,
  "environment": "sandbox",
  "asset": "USDT_TRON",
  "amount": "15.000000",
  "network_fee": "1.100000",
  "network_fee_final": true,
  "total_charged": "16.100000",
  "destination": "<customer-tron-address>",
  "destination_memo": null,
  "destination_basis": "past_payer",
  "matched_invoice_id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
  "matched_transaction_id": "TST-7K3M-9QX2-H4PD",
  "customer_id": "cust-77",
  "customer_email": null,
  "order_id": null,
  "note": "Cashback October",
  "created_via": "api",
  "settlement_id": "01J9Z5C3D4E5F6G7H8J9KMNPQS",
  "tx_hash": null,
  "explorer_url": null,
  "funds_returned": false,
  "created_at": "2026-10-14T10:00:00+00:00",
  "approved_at": null,
  "funded_at": "2026-10-14T10:00:00+00:00",
  "completed_at": null,
  "failed_at": null,
  "cancelled_at": null,
  "request_id": "req_01J9Z5C3D4E5F6G7H8J9KMNPQT"
}

The payout object #

The payout wallet object #

GET /payout-wallets lists one per chain family with an enabled network; POST /payout-wallets with network_family creates one (202, allocating; 200 when it exists).

Settlements and withdrawals #

A settlement sends you your share of a payment. When depends on your settlement schedule (the platform's default, or your choice under Balances when the operator lets merchants choose):

The platform commission and the fixed fee per invoice are taken from every invoice whatever the schedule. On EVM and Tron, on request roughly halves the network cost per invoice (one transfer into your balance instead of two; commissions are collected in batches); a withdrawal is one more transfer. On Bitcoin and Bitcoin Cash it costs about the same as per invoice.

GET /settlements lists settlements with their transfers (refunds and payouts are listed under their own endpoints). Filters:

The settlement object #

The transfer object #

Withdrawals. POST /withdrawals takes an amount of one asset from your balance (default: everything available) for your saved settlement wallet; it answers 202 with a settlement of kind withdrawal, status requested, planned within about a minute (settlement.planned) and sent as one transfer. Its network cost comes out of the amount. Cancel it with POST /withdrawals/{id}/cancel while it is requested.

# a new UUID for every withdrawal; the same one only to retry it
curl -X POST https://cryptonera.com/api/v1/withdrawals \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5c8a1f3d-7e2b-4a96-8d10-2f6b9e4c7a31" \
  -d '{
    "asset": "USDT_TRON",
    "amount": "90.00"
  }'

Response 202 Accepted:

{
  "id": "01J9Z6D4E5F6G7H8J9KMNPQRST",
  "object": "settlement",
  "kind": "withdrawal",
  "status": "requested",
  "hold_reason": null,
  "environment": "sandbox",
  "asset": "USDT_TRON",
  "owner": {
    "type": "withdrawal",
    "id": "01J9Z6D4E5F6G7H8J9KMNPQRST"
  },
  "invoice_id": null,
  "invoice_number": null,
  "transaction_id": null,
  "order_id": null,
  "gross": "90.000000",
  "platform_fee": "0.000000",
  "fixed_fee": "0.000000",
  "network_fee": "0.000000",
  "network_fee_detail": null,
  "execution_cost_reserve": "0.000000",
  "actual_network_cost": null,
  "residual_retained": "0.000000",
  "distributable": "0.000000",
  "cost_funding": "separate_gas",
  "fee_snapshot_id": "01J9Z6D4E5F6G7H8J9KMNPQRSV",
  "gas_paid": null,
  "settlement_schedule": null,
  "settlement_batch_id": null,
  "withdrawal": {
    "requested_amount": "90.000000",
    "destination": {
      "address": "<your-tron-settlement-wallet>",
      "memo": null,
      "label": "Tron wallet",
      "source": "settlement_wallet"
    },
    "estimate": {
      "network_fee": "1.100000",
      "execution_cost_reserve": null,
      "net": "88.900000",
      "basis": "kept"
    },
    "channel": "api",
    "note": null,
    "cancellable": true,
    "cancel_reason": null
  },
  "transfers": [],
  "created_at": "2026-10-14T11:00:00+00:00",
  "completed_at": null,
  "request_id": "req_01J9Z6D4E5F6G7H8J9KMNPQRSW"
}

Balances #

GET /balances gives your money per asset, with a USD estimate at the rate the platform keeps (an estimate only: never used for any payment, and assets are never converted into each other). pending_detail says why pending waits, in parts that add up to it exactly (the codes).

{
  "object": "list",
  "environment": "sandbox",
  "data": [
    {
      "object": "balance",
      "asset": "USDT_TRON",
      "symbol": "USDT",
      "decimals": 6,
      "available": "128.400000",
      "pending": "24.250000",
      "pending_detail": [
        {
          "code": "on_its_way",
          "label": "On its way into your balance (network confirmations)",
          "amount": "18.500000",
          "amount_atomic": "18500000",
          "count": 1
        },
        {
          "code": "open_invoice",
          "label": "Waiting for the rest of the payment",
          "amount": "5.750000",
          "amount_atomic": "5750000",
          "count": 1
        }
      ],
      "held": "0.000000",
      "reserved": "0.000000",
      "payout_wallet": null,
      "retained": "0.000000",
      "deficit": "0.000000",
      "total": "152.650000",
      "minimum_withdrawal": "1.000000",
      "usd": {
        "rate": "1.00",
        "rate_source": "coingecko",
        "rate_at": "2026-10-14T11:50:00+00:00",
        "stale": false,
        "available": "128.40",
        "total": "152.65"
      }
    }
  ],
  "usd_totals": {
    "available": "128.40",
    "total": "152.65",
    "oldest_rate_at": "2026-10-14T11:50:00+00:00",
    "complete": true,
    "missing": [],
    "note": "Estimate at the listed rates; never used for any payment. Assets are never converted."
  },
  "request_id": "req_01J9Z7E5F6G7H8J9KMNPQRSTVW"
}

The balance object #

Deposits #

GET /deposits lists the payments seen on the network (both products). Filters:

The deposit object #

Assets, the fee policy and wallets: see the endpoint table above. Webhook endpoints are explained under webhooks.

6. Errors #

Every error has the same envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "retryable": false,
    "request_id": "req_01J9Z3A1B2C3D4E5F6G7H8J9KS",
    "fields": {
      "amount": ["The amount field must be a string."]
    }
  }
}

• retryable: true: retry later (honour Retry-After) with the same request.
• reason: a setting or a detail. hint explains it; dashboard_url and docs_url point to the fix.
• The Key column says what happens to your Idempotency-Key: stored (the same key replays this answer: fix the request and use a new key), free (nothing stored: send the same request with the same key once fixed), or — (answered before the key is read).

Ignore keys you do not know; new detail keys may be added.

7. Webhooks #

Endpoints and subscriptions #

Register an https endpoint with POST /webhook-endpoints (or Developers → Webhooks in the dashboard). event_types takes *, a prefix such as invoice.* (prefixes: invoice, deposit, settlement, fee, refund, split_session, splitter, payout ) or exact event names. The signing secret is shown once; PATCH with rotate_secret creates a new one (the old one keeps signing for a while). Sandbox and live endpoints are separate.

Payload #

Every delivery is a POST with this body (schema_version 2026-10-12):

{
  "id": "01J9Z8F6G7H8J9KMNPQRSTVWXY",
  "schema_version": "2026-10-12",
  "type": "invoice.paid",
  "occurred_at": "2026-10-12T10:07:12+00:00",
  "delivery_attempt_id": "01J9Z8F6G7H8J9KMNPQRSTVWXZ",
  "environment": "sandbox",
  "resource": {
    "type": "invoice",
    "id": "01J9Z3A1B2C3D4E5F6G7H8J9KM"
  },
  "data": {
    "number": "INV-MAIN-000123",
    "deposit_id": "01J9Z8F6G7H8J9KMNPQRSTVWY0",
    "excess": "0.000000",
    "excess_atomic": "0",
    "accepted": false,
    "accepted_kind": null,
    "acceptance_id": null,
    "status": "paid",
    "asset": "USDT_TRON",
    "amount_required": "49.990000",
    "amount_required_atomic": "49990000",
    "amount_paid": "49.990000",
    "amount_paid_atomic": "49990000",
    "amount_pending": "0.000000",
    "amount_pending_atomic": "0",
    "amount_due": "0.000000",
    "amount_due_atomic": "0",
    "amount_held": "0.000000",
    "amount_held_atomic": "0",
    "needs_decision": false,
    "invoice_id": "01J9Z3A1B2C3D4E5F6G7H8J9KM",
    "invoice_number": "INV-MAIN-000123",
    "transaction_id": "TST-7K3M-9QX2-H4PD",
    "order_id": "order-1042"
  }
}

data carries the references invoice_id, invoice_number, transaction_id and order_id whenever the event concerns a payment (unknown ones are left out). Every invoice.* event except invoice.settlement_* carries the invoice's amount block: status, asset, amount_required, amount_paid, amount_pending, amount_due, amount_held (decimal strings, each with an *_atomic sibling in the smallest unit) and needs_decision. Amounts are decimal strings everywhere. Events are small: read the object again before acting. For invoice, refund, payout, settlement, split_session and splitter events that is GET /invoices|refunds|payouts|settlements|split-sessions|splitters/{resource.id}; a settlement_transfer (settlement.transfer_*, fee.collected) has no endpoint of its own: read GET /settlements/{data.settlement_id} and its transfers[]; a deposit neither: GET /deposits?tx_hash={data.tx_hash} (deposit.held has no tx_hash: list the payment's deposits with ?invoice_id=, or ?owner_id= the split session) and pick the one whose id is resource.id. GET /webhook-events is also a polling feed.

Events #

Only confirmed money is reported as paid: invoice.partially_paid, invoice.underpaid, invoice.late_payment and invoice.paid_late are sent at confirmation, never at first sight.

Verify the signature #

<?php
// Verify a Cryptonera webhook. Use the RAW body — never re-encode JSON before hashing.
$secret   = getenv('CRYPTONERA_WEBHOOK_SECRET');           // whsec_...
$raw      = file_get_contents('php://input');
$sigHdr   = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$tsHdr    = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$eventId  = $_SERVER['HTTP_X_WEBHOOK_ID'] ?? '';

if (!ctype_digit($tsHdr) || abs(time() - (int) $tsHdr) > 300) {
    http_response_code(400); exit('stale timestamp');
}
$expected = 'v1=' . hash_hmac('sha256', $tsHdr . '.' . $raw, $secret);
$ok = false;
foreach (explode(',', $sigHdr) as $part) {   // two v1= values while a secret is rotated: compare each
    if (hash_equals($expected, trim($part))) { $ok = true; break; }
}
if (!$ok) { http_response_code(401); exit('bad signature'); }

// Dedupe on $eventId (retries and replays reuse it), then answer 2xx quickly.
$event = json_decode($raw, true, 64, JSON_THROW_ON_ERROR);
// $event['type'], $event['resource'], $event['data']
http_response_code(200);

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();
// Verify the raw body: never a re-serialised JSON object.
app.post('/webhooks/cryptonera', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Webhook-Timestamp') ?? '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const expected = Buffer.from('v1=' + createHmac('sha256', process.env.CRYPTONERA_WEBHOOK_SECRET)
    .update(ts + '.').update(req.body).digest('hex'));
  const ok = (req.get('X-Webhook-Signature') ?? '').split(',').some((s) => {
    const b = Buffer.from(s.trim());
    return b.length === expected.length && timingSafeEqual(b, expected);
  });
  if (!ok) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  // dedupe on req.get('X-Webhook-Id'), then handle event.type quickly
  res.sendStatus(200);
});

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ['CRYPTONERA_WEBHOOK_SECRET'].encode()


@app.post('/webhooks/cryptonera')
def cryptonera_webhook():
    raw = request.get_data()  # the raw body, before any JSON parsing
    ts = request.headers.get('X-Webhook-Timestamp', '')
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(400)
    expected = 'v1=' + hmac.new(SECRET, ts.encode() + b'.' + raw, hashlib.sha256).hexdigest()
    signatures = request.headers.get('X-Webhook-Signature', '').split(',')
    if not any(hmac.compare_digest(expected, s.strip()) for s in signatures):
        abort(401)
    event = request.get_json()
    # dedupe on request.headers['X-Webhook-Id'], then handle event['type'] quickly
    return '', 200

Hash the raw body, never a re-serialised object; reject timestamps older than 300 s; compare in constant time; dedupe on X-Webhook-Id, then answer quickly. Check your receiver with this test vector:

Test vector (check your receiver with it):
  secret     whsec_test
  timestamp  1760000000
  raw body   {"id":"evt_1"}
  signed     1760000000.{"id":"evt_1"}
  header     v1=66e880d7175fffb43ce10c4e14db1cfb230c8804b5aafb116affbc9a836c7690

Delivery and retries #

Answer any 2xx within 8 seconds. A failed delivery is retried with growing waits (30 s · 2ⁿ, at most 6 hours) up to 12 attempts, about 17 hours after the first; then it is dead. An endpoint that keeps failing is marked failing and still receives. A disabled endpoint receives nothing: its pending deliveries are cancelled, and replays to it are refused until you enable it. A replay keeps the event id, so a receiver that already handled the event ignores it.

Product 2 of 2

Crypto Splitter API #

Split incoming crypto between several recipients by percentage. Two shapes: a splitter is a persistent receiving wallet whose recipients are versioned (edits apply from the next block on), and a split session is a one-off fresh deposit address for a single order or request. Both settle confirmed deposits to the recipients through the custody provider; the platform commission is snapshotted when funds are accepted.

Share this section: https://cryptonera.com/developers#crypto-splitter

Base URL, keys, idempotency, errors and webhooks are shared with Crypto Billing: start with the quick start.

Endpoints #

Assets, the fee policy, deposits, settlements and webhooks are in the shared endpoint table.

Example: create a fresh-address split session #

Two recipients on Tron receive USDT 60/40. Each confirmed deposit is settled as soon as it is confirmed. Replace the placeholders with addresses valid on the target network; addresses are validated before the session is created.

# split sessions have no order check: a new UUID per session protects a retry
curl -X POST https://cryptonera.com/api/v1/split-sessions \
  -H "Authorization: Bearer $CRYPTONERA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d4e1b2c-9f6a-4e38-a5d1-3b8c0e2f6a97" \
  -d '{
    "asset": "USDT_TRON",
    "recipients": [
      {
        "address": "<valid-tron-recipient-A>",
        "percentage": "60.00",
        "label": "Studio"
      },
      {
        "address": "<valid-tron-recipient-B>",
        "percentage": "40.00",
        "label": "Producer"
      }
    ],
    "settlement_trigger": "each_confirmed_deposit",
    "order_id": "order-10021",
    "expires_in_seconds": 3600
  }'

Response (201 Created, or 202 Accepted with status allocating when no fresh address is available yet: poll status_url):

{
  "id": "01J9Z2K7M3N4P5Q6R7S8T9V0WX",
  "object": "split_session",
  "transaction_id": "TST-4Q8M-2ZK7-VN3D",
  "status": "awaiting_payment",
  "environment": "sandbox",
  "asset": "USDT_TRON",
  "network": "tron-nile",
  "deposit_address": "<fresh-tron-deposit-address>",
  "memo": null,
  "payment_uri": null,
  "order_id": "order-10021",
  "settlement_trigger": "each_confirmed_deposit",
  "expected_amount": null,
  "minimum_deposit": "1.000000",
  "received_confirmed": "0.000000",
  "settled_gross": "0.000000",
  "held": "0.000000",
  "recipients": [
    {
      "address": "<valid-tron-recipient-A>",
      "memo": null,
      "percentage": "60.00",
      "label": "Studio"
    },
    {
      "address": "<valid-tron-recipient-B>",
      "memo": null,
      "percentage": "40.00",
      "label": "Producer"
    }
  ],
  "fee_policy": {
    "snapshot_id": "01J9Z2K7M3N4P5Q6R7S8T9V0WY",
    "platform_percentage": "1.00",
    "recipient_basis": "after_platform_fee_and_disclosed_same_asset_costs",
    "network_cost_mode": "separate_native_gas_budget",
    "operator_fee_wallet_configured": true
  },
  "confirmation_policy": {
    "required_confirmations": 19,
    "finality": "solidified"
  },
  "freshness": {
    "never_previously_allocated": true,
    "prior_activity_observed": false,
    "checked_at": "2026-10-12T10:00:00+00:00",
    "provider": "trongrid"
  },
  "late_payment_policy": "hold_for_review",
  "metadata": null,
  "expires_at": "2026-10-12T11:00:00+00:00",
  "closed_at": null,
  "first_payment_at": null,
  "settled_at": null,
  "created_at": "2026-10-12T10:00:00+00:00",
  "status_url": "https://cryptonera.com/api/v1/split-sessions/01J9Z2K7M3N4P5Q6R7S8T9V0WX",
  "checkout_url": "https://cryptonera.com/pay/s/<public-token>",
  "request_id": "req_01J9Z2K7M3N4P5Q6R7S8T9V0WZ"
}

Field values above are illustrative; the exact fee_policy and freshness objects depend on operator configuration. A persistent splitter is created the same way with POST /splitters (no expiry; recipients can be replaced later with PATCH, which opens a new version from the next block).

Lifecycle & events #

Late or excess money after a session closed is held for you, never sent to the recipients. Events: split_session.*, splitter.*, deposit.* and settlement.*: see events.