From API call to payment status.

Quickstart: ten minutes to a confirmed payment

Five steps, one test key, no node to run. Every snippet here runs on your server — the browser never sees a secret.

1. 1

   Create a test key 2 min

   Developers → API keys → Create key with create_invoice and read. The secret is shown once: put it in your server's environment or secret manager. Test keys (ck_test_) are created the same way in the cabinet of the test environment — CryptoLike support gives you access and the test API URL (see below).

2. 2

   Create the payment on your server 3 min

   One call with the amount, your order id and where to return the customer. Send your order id as the Idempotency-Key: a retry returns the same payment, never a second one.

3. 3

   Let the customer pay 2 min

   Redirect to checkout_url, or embed the same page in your checkout with the widget. The page shows the address, the QR, the exact amount, the network warning and the live status.

4. 4

   Pay it on a test network 2 min

   Ask CryptoLike support for test coins — they have no value — and send the exact amount to the address on the page. The status turns pending when the transfer is detected, paid when the confirmations are in.

5. 5

   Receive the result 1 min

   Verify the webhook signature over the raw body, skip an event_id you have already stored, answer 2xx within 10 seconds, then fulfil the order. Polling GET /v1/invoices/{id} every few seconds works too.

Code language — The samples on this page follow your choice.

// Your server. The secret never reaches a browser.
import { CryptoLike } from "@cryptolike/sdk";

const api = new CryptoLike(); // CRYPTOLIKE_API_KEY_ID + CRYPTOLIKE_API_SECRET

const invoice = await api.invoices.create(
  {
    amount: "49.90",
    currency: "USD",                 // or a ticker: "BTC", "USDT"
    order_id: "A-1001",
    return_url: "https://shop.example/orders/A-1001",
  },
  "order-A-1001",                    // Idempotency-Key: a retry returns this same payment
);

res.redirect(invoice.checkout_url);  // invoice.status === "new"

The SDKs read CRYPTOLIKE_API_KEY_ID and CRYPTOLIKE_API_SECRET from the environment. For test networks set CRYPTOLIKE_API_URL to the test API URL that CryptoLike support gives you.

That is the whole integration. Everything below is the detail behind those five steps.

Create a payment

One signed POST /v1/invoices. You get back a payment with an id, a status and the page to send the customer to.

The response carries id, status: new, checkout_url and ttl_expires_at — the moment the payment stops waiting for a first transfer. Optional blocks are present as null, so one parser handles every response.

Repeat customers do not need an invoice each time: POST /v1/addresses issues a permanent deposit address for one customer and one asset. Every transfer to it is credited and announced by deposit.confirmed.

Customer payment: hosted page or embedded widget

The same payment page, two ways to show it. Both read public payment data only, and neither needs a secret in the browser.

<div id="pay"></div>
<script src="https://cryptolike.net/widget/v1/cryptolike.js"></script>
<script>
  CryptoLike.mount({
    container: "#pay",
    invoiceId: "4e2bc88c-cb79-4afc-b864-c1ba8e9d50c9", // from your server — the page gets nothing else
    theme: "dark",
    onStatus: function (m) { if (m.isFinal) showResult(m.status); },
  });
</script>

Status model

One status, shown the same way in the API, on the payment page and in webhooks. Terminal means the status does not change by itself.

Terminal states: paid, expired, cancelled — and underpaid once the TTL has passed. Everything else can still move.

Ship on paid.

If a chain reorganisation rolls a confirmation back, the amount is recomputed and you receive invoice.reverted. Stop fulfilment until a new invoice.paid arrives.

Late funds are still credited.

A transfer confirmed after the payment closed lands on your balance, the payment gets late_payment: true and you receive invoice.late_payment. The status does not change — decide with the customer.

Two amounts, one payment.

payer_amount is what the customer must send, amount_crypto is what you receive. They differ only when the platform fee is paid by the payer.

Webhooks: signature, retries, exactly once

We POST a signed JSON event to your endpoint on every change. Three rules make the handler correct.

1. 1

   Verify over the raw bytes

   X-Signature is "sha256=" plus the HMAC-SHA256 of X-Timestamp + "." + the raw body. Compare in constant time and reject a timestamp more than a few minutes off your clock, either way. Do not re-serialise the JSON first: key order is not guaranteed.

2. 2

   Act once per event_id

   Delivery is at least once. The same event can arrive again with the same event_id, the same body and a fresh signature. Store the id; acknowledge a repeat without touching the order twice.

3. 3

   Answer 2xx within 10 seconds

   Store the event, answer, process afterwards. Anything else — another status, a redirect, a timeout — is retried after 1 min, 5 min, 15 min, 1 h, 6 h and 24 h, then marked exhausted. You can resend any delivery from the cabinet.

import express from "express";
import { verifyWebhook, WebhookVerificationError } from "@cryptolike/sdk";

// express.raw: the signature covers the bytes as received, not re-serialised JSON.
app.post("/hooks/cryptolike", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = verifyWebhook(req.headers, req.body, process.env.CRYPTOLIKE_WEBHOOK_SECRET);
  } catch (e) {
    if (e instanceof WebhookVerificationError) return res.sendStatus(401);
    throw e;
  }
  res.sendStatus(200);              // answer first — 10 seconds is the budget
  if (seen(event.event_id)) return; // delivery is at least once: a repeat is normal
  remember(event.event_id);
  if (event.type === "invoice.paid") fulfil(event.data.invoice);
});

Every SDK ships this as one call — verifyWebhook(headers, rawBody, secret) — with the constant-time compare and the timestamp tolerance built in. The same test vectors every SDK is pinned to are in the webhook contract.

Deliveries are independent, so a retried invoice.pending can arrive after invoice.paid. Trust created_at and the status inside data, not the arrival order.

Errors: machine code, human message, recovery

One envelope for every error. Branch on code, show message to a person, read details for specifics — details.field names the bad field.

A 4xx is never worth retrying unchanged. The SDKs retry 429 and 5xx (except 501) up to three times with jittered backoff, and stop when Retry-After is longer than 30 seconds.

Sandbox: test keys and test networks

A ck_test_ key signs exactly like a live one and works only in the test environment, on test networks — there a live key, too, moves test coins only. Test coins have no value, and the flow is identical to production. Production runs on mainnets: it does not issue test keys and refuses them with 401 auth.test_key, so nothing is created.

1. 1

   Point the SDK at test networks

   Create the key with the same permissions and set CRYPTOLIKE_API_URL to the test API URL; ask CryptoLike support for it. Keep test and live keys in separate configurations.

2. 2

   Read what the test networks offer

   GET /v1/currencies lists the assets, their networks, their decimals and the confirmations each one needs — the same numbers the payment page shows the customer.

3. 3

   Get test coins

   Ask CryptoLike support for test coins; they have no value. Send the exact payer_amount to the address on the page, on the network named there.

4. 4

   Walk the whole path

   Underpay on purpose to see underpaid and a top-up; let one payment run out to see expired; cancel one from new. Developers → Webhooks → endpoint → Send test event exercises your handler with a signed ping, without a payment.

Go-live checklist

Ten checks before the first real payment.

After go-live: the cabinet shows every delivery with its attempts and response, and you can resend any of them.

Questions developers ask

Read next

• API overview — resources, conventions, versioning →
• Authentication — keys, permissions, request signing →
• Webhooks — event types, fields, test vector →
• SDKs — TypeScript, Python, Go, PHP →
• Checkout widget — embed the payment page →

Plain-text version of this page for AI assistants ↗