API reference

Base URL https://pay-api.chromia.com. Every request carries Authorization: Bearer <secret key>. Amounts are decimal strings.

Routes

The /v1/account routes below take an agent token instead, and refuse a secret key with 403.

Managing the account

Everything the dashboard can do, for an agent acting on your behalf. These need an Authorization: Bearer cpay_at_… token, minted under Developers → Agent tokens — a secret key authenticates and is then turned away, because widening one credential must not widen the other.

Minting a token is not here on purpose. A credential that can mint its own successors cannot be revoked — revoke it and the one it made keeps working — so that step stays with a person in the dashboard.

Payout addresses without proof

POST /v1/account/wallets requires unverified: true and refuses the call without it, because an agent cannot produce an ownership signature. The address is then recorded as asserted rather than proved, and GET /v1/account/wallets reports which it was.

That path exists because the proof is impossible for the address merchants most often want: you hold no key for an exchange deposit address, and you cannot send from it either, so both personal_sign and a self-transfer are unavailable. The address shape is still validated — skipping the proof is a decision about trust, while accepting a malformed address is a bug.

On the native Chromia rail, prefer an address you control. A payer's transfer carries Chromia Pay's own cpay:<REF> memo, so an exchange that needs its own memo to credit your deposit gets ours instead, and the funds are stranded inside the exchange. Exchange addresses are fine on BNB Smart Chain and Base.

Creating a payment

Headers: Idempotency-Key makes the create safely retryable — the same key returns the original payment, and the same key with a different amount — or a different settlement_asset — is refused with 409.

The payment object

{
  "id": "pi_01JQ...",
  "object": "payment",
  "status": "pending",
  "livemode": false,
  "currency": "CHR",
  "settlement_asset": "chr",
  "amount": "12.500000",
  "price": null,
  "price_currency": null,
  "rate": null,
  "rate_source": null,
  "amount_expected": "12.500431",
  "amount_paid": "0.000000",
  "amount_pending": "12.500431",
  "reference": "K7QP2M9XTB4C",
  "chain": "chromia",
  "description": "Order #1041 — two plushies",
  "metadata": { "order_id": "1041" },
  "deposits": [
    {
      "chain": "chromia",
      "tx_id": "9f2c...",
      "event_index": 0,
      "amount": "12.500431",
      "payer": "A82160...",
      "status": "seen",
      "memo": "cpay:K7QP2M9XTB4C"
    }
  ],
  "checkout_url": "https://pay-checkout.chromia.com/c/pay/ct_...",
  "expires_at": 1786712345,
  "created_at": 1786710545,
  "confirmed_at": null
}

amount is what you asked for. amount_expected is what the payer is told to send: the same figure, plus attribution dust when another open payment in the same environment already claims that exact total. Usually the two are equal; when they are not, amount_expected is the one that settles the payment. price, price_currency, rate and rate_source are set only for a payment created with currency: "usd", and the rate is the one locked at creation.

Statuses

created → pending → one of confirmed, overpaid, underpaid, expired, canceled. pending means funds are on chain but not final. Terminal states do not change afterwards, with one exception: an underpaid payment can be moved to confirmed or overpaid by an audited manual attach from the dashboard, which is how a memo-less exchange send gets matched to its order.

Deposits

Every transfer we attributed to the payment. payer is the FT4 account id or the 0x address the money came from — who to contact about a wrong payment. status is seen (on chain, not final), confirmed, orphaned (reorged away, EVM only), or simulated.

Errors

{ "error": { "type": "invalid_request", "message": "amount must have at most 6 decimals", "param": "amount" } }

Repo-layer scoping means a 404 on someone else's payment id, never a 403 — the id of a payment that is not yours is indistinguishable from an id that does not exist.