API quickstart

Before you beginCopy Anchor Link

Use an active merchant and its API key. Set CRYPTIUM_API_URL to your deployment's public API origin, CRYPTIUM_MERCHANT_ID to its ID, and CRYPTIUM_API_KEY to its secret. These variables belong on your server.

Prepare a public HTTPS webhook endpoint and read signature verification.

Create an invoiceCopy Anchor Link

This Node.js example deliberately sends amount as a string and uses a stable order reference.

import { createHmac } from 'node:crypto';

// Створює інвойс з ідентичністю замовлення, щоб повтор після timeout не дублював платіж.
export async function createInvoice(orderId, webhookUrl) {
  const body = { currency: 'USD', amount: '19.95', order_id: orderId, webhook_url: webhookUrl };
  const json = JSON.stringify(body);
  const signature = createHmac('sha256', process.env.CRYPTIUM_API_KEY).update(json).digest('hex');
  const response = await fetch(new URL('/api/invoices', process.env.CRYPTIUM_API_URL), {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'merchant-id': process.env.CRYPTIUM_MERCHANT_ID,
      signature,
    },
    body: json,
  });
  if (!response.ok) throw new Error(`Invoice creation returned HTTP ${response.status}`);
  return response.json();
}

Store the returned invoice id against your order, then redirect the customer to the returned url. Use that URL unchanged. See the full creation contract.

Explicitly pass webhook_url for every invoice that needs events. A saved merchant webhook URL is not automatically inherited by this API call.

Handle the customer paymentCopy Anchor Link

The customer completes payment on the hosted checkout. Token and network choice, exact transfer amount, address, and confirmation progress are handled there.

Receiving an invoice URL is not a successful payment. The customer can close the page, send too little, or pay after expiration.

Confirm and fulfil onceCopy Anchor Link

1. Receive an invoice.updated webhook.
2. Verify the signature against the raw body and check its timestamp.
3. Validate the merchant, invoice, and order against your saved records.
4. Deduplicate by event_id and prevent an older sequence from replacing newer state.
5. Apply your fulfilment policy for PAID or OVERPAID once.

Persist the accepted event and order update transactionally before acknowledging it. If processing is asynchronous, durably queue the verified event before returning a successful response.

The customer returning to success_url must not trigger fulfilment by itself. You can read the public invoice to reconcile its current status.

Handle an uncertain responseCopy Anchor Link

If invoice creation times out, retry with the same order_id and the same business fields. A new order ID creates a different request. Read errors and retries, then complete the testing checklist.