API documentation & developer guide

Quickstart

Accepting crypto on your site takes three steps: create an API key, register your settlement wallet addresses, and open your first invoice. Because nothing is custodial, settlements move straight to a wallet you control.

• Dashboard → API keys — Sign in and generate your key pair (KeyId and Secret) there. The secret is shown once, at creation.
• Panel → Settings or POST /v1/static-addresses — registers the static wallet address for token settlements such as USDT (one per network and asset).
• Panel → Settings or POST /v1/sweep-addresses — registers the main wallet (sweep address) that native coin settlements such as TRX, BNB and GRAM are collected into.
• POST /v1/webhooks — registers the URL we notify the moment a payment completes.

Request signing (HMAC)

Every HTTP request is signed with HMAC-SHA256. The signature is computed over the raw request body, so it stays valid even if the JSON key order changes.

METHOD \n PATH \n TIMESTAMP \n NONCE \n SHA256(raw_body)

X-Api-Key

API key id (pk_…)

X-Timestamp

Unix timestamp in seconds (server clock tolerant)

X-Nonce

Unique random string (max 128 characters, single use)

X-Signature

hex(hmac_sha256(secret, canonical))

Two layers protect the request: the timestamp must fall inside the tolerance window, and each nonce may be used only once. Replaying the same request is rejected automatically (HTTP 401).

X-Timestamp is Unix epoch seconds and may deviate from server time by at most 300 seconds. X-Nonce is unique per request; a used nonce is rejected for 600 seconds.

1import hashlib, hmac, os, time, json, urllib.request
2 
3KEY_ID  = os.environ["COINZEN_KEY_ID"]
4SECRET  = os.environ["COINZEN_SECRET"]
5BASE    = "https://coinzen.cerceyn.com"
6 
7def request(method: str, path: str, payload: dict | None = None) -> bytes:
8    body = json.dumps(payload).encode() if payload is not None else b""
9    ts = str(int(time.time()))
10    nonce = os.urandom(16).hex()
11    canonical = "\n".join(
12        [method.upper(), path, ts, nonce, hashlib.sha256(body).hexdigest()]
13    )
14    signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
15 
16    req = urllib.request.Request(
17        BASE + path,
18        data=body or None,
19        method=method.upper(),
20        headers={
21            "X-Api-Key": KEY_ID,
22            "X-Timestamp": ts,
23            "X-Nonce": nonce,
24            "X-Signature": signature,
25            "Content-Type": "application/json",
26        },
27    )
28    with urllib.request.urlopen(req) as resp:
29        return resp.read()

Scopes

A key may only call endpoints covered by the scopes granted to it; a missing scope returns 403. You pick the scopes when you generate the key in the panel.

Rate limits

Limits apply per merchant over a one-minute sliding window. When exceeded you get 429 along with a Retry-After header.

• General endpoints — 120 requests / minute
• Invoice creation — 30 requests / minute

Idempotency

The Idempotency-Key header is required on POST /v1/invoices. Without it the request is rejected with 422. Generate a fresh, unique value for each request.

Idempotency-Key: 7f3c1e9a4b8d42f0a1c6e5b3d9074a2e

Resending the same body with the same key does not open a second invoice: the first response is replayed verbatim, with its original status code. You can safely retry after a dropped connection.

Invoice lifecycle

Creating an invoice starts a state machine. If no network and asset were given, the invoice opens as selecting. When the customer picks a network and coin on the payment page it moves to pending and a payment address is allocated.

• selecting → pending, expired, cancelled
• pending → confirming, partially_paid, expired, cancelled
• confirming → paid, overpaid, failed
• paid ⇄ overpaid — if the customer sends another transfer against a paid invoice, the amount updates automatically.

paid, overpaid, expired, cancelled and failed are terminal. On a chain reorg or a late payment the system updates the state itself and tells your system over a webhook.

Balance Payment

If you sell balance or credit, a fixed amount is the wrong model: the payer rounds 5.188 down to 5 and the invoice stays short. Open the invoice with balance_payment: true and whatever arrives closes it — the displayed amount is only a suggestion, and the payment page says so to the payer.

Credit from the webhook's received_amount and the received_fiat_amount computed at the locked rate, not from fiat_amount. If the invoice asked for 250 TRY and 5 USDT arrived, what you credit is the value of those 5 USDT. The fee accrues on the amount that arrived too.

For token collection the address is shared, and what binds a payment to an invoice is the amount. If several balance invoices are open at once on the same network/asset, a rounded payment can't be attributed; we don't guess — it lands in unmatched deposits and a deposit.unmatched webhook fires. You attach it to the right invoice from the panel. Can't be combined with a credit-funding invoice.

Webhook notifications

Every payment status change is pushed to your registered webhook endpoint. Each payload is signed with HMAC-SHA256, so you can verify that the data is intact and really came from Coinzen.

The webhook secret used for verification (whsec_…) is issued once, when you register the endpoint: on the dashboard's Webhooks page, or in the secret field of the POST /v1/webhooks response. It is not your API key's Secret; that one only signs the requests you send. Registering the same URL again issues a new webhook secret and disables the old entry.

X-Coinzen-Signature

t=<unix>,v1=<hex hmac_sha256(secret, "<t>.<raw_body>")>

X-Coinzen-Delivery

Unique delivery id (UUID)

X-Coinzen-Event

Event name that fired (e.g. invoice.paid)

1import hashlib, hmac, time
2 
3def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
4    """X-Coinzen-Signature: t=<unix>,v1=<hex>"""
5    parts = dict(p.split("=", 1) for p in header.split(","))
6    t, v1 = parts["t"], parts["v1"]
7    if abs(time.time() - int(t)) > tolerance:
8        return False
9    expected = hmac.new(
10        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
11    ).hexdigest()
12    return hmac.compare_digest(expected, v1)

Supported webhook events

• invoice.pending
• invoice.confirming
• invoice.partially_paid
• invoice.paid
• invoice.overpaid
• invoice.expired
• invoice.cancelled
• payment.reverted
• deposit.unmatched
• credit.low
• credit.exhausted

Retry schedule

The first attempt fires immediately after the payment. If your server doesn't answer 200 OK, we retry across seven steps at 30 · 120 · 600 · 3600 · 21600 · 86400 second intervals. If every attempt fails the record moves to dead_letter and can be re-queued from the dashboard in one click.

Error contract

Every error uses the same envelope. The code field is stable and meant for programmatic matching; message is for humans and may change.

1{
2  "error": {
3    "code": "conflict",
4    "subcode": "order_id_exists",
5    "message": "bu order_id zaten kullanılmış",
6    "details": { "order_id": "A-1042" }
7  }
8}

The subcode field narrows the class code — order_id_exists instead of plain conflict. Check subcode first and fall back to code; the contract only widens, never narrows.

When a request fails schema validation (missing field, wrong type, out-of-range value), code is validation_error and details maps each field path to an error type: {"body.url": "url_scheme"}. The type is meant for programmatic matching (missing, greater_than, …); the explanation is in message.

Fees and credit

Coinzen never takes its fee out of the customer's payment. USDT and every other crypto payment goes straight to your address, and only you hold that wallet's keys. The platform fee comes out of credit you topped up beforehand, so what you collect stays whole.

• The standard rate is 1%. New accounts get 0.1% for their first 45 days. Your current rate is in the fee_bps field of the GET /v1/credit response (basis points: 10 = 0.1%, 100 = 1%).
• The fee is charged only on invoices that complete successfully (paid and overpaid).
• Cancelled, expired and underpaid invoices are never charged.
• When your credit runs out, open invoices keep settling normally; only new invoice requests get a balance warning (HTTP 402).

Two-step charging

When an invoice is paid, the fee entry opens immediately as pending so chain tracking isn't slowed down, and it settles without waiting on any external service. The rate conversion happens in the background and the net amount comes off your balance.

If a chain reorg pulls the payment back, the fee is voided at once; if it had already been deducted, a reversal entry refunds it.

Topping up credit

POST /v1/credit/deposit-addresses returns a permanent USDT top-up address of your own. Anything you send there is added to your credit the moment it confirms on chain — no manual approval, no waiting.

Automatic top-up

With this on, your sales keep running even if your credit hits zero. The proceeds of your next small invoice are routed into your credit balance instead, and service continues uninterrupted.

• No separate fee is charged on an invoice routed into credit.
• A cap applies for your protection (25 USD by default). Invoices above the cap are never routed, so large orders aren't put at risk.
• Toggle it and set your own cap at any time through PUT /v1/credit/auto or the dashboard.

Balance alerts

When your credit drops below the threshold a credit.low event fires, and credit.exhausted when it runs out — so you hear about it before it bites.

Supported networks and assets

The table below summarises the live mainnet registry. For the runtime list, call GET /v1/networks.

API endpoints

Request schemas

Below are the bodies for the endpoints you call on day one. The complete schema for every endpoint is published in machine-readable form at GET /openapi.json — import it into Postman or generate a client from it.

Query parameters