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.

It costs one thing, and it is the same fact stated from the other side: an asserted address cannot refund. Sending money back needs a key, so the dashboard marks such an address receive only and declines to offer the button. Nothing about receiving is affected. If the address is a wallet you do hold, proving it with a signature turns refunds on for it.

On the native Chromia rail, prefer an address you control — and it must require transfer memos.

A payer's Chromia transfer carries Chromia Pay's own cpay:<REF> memo, and on that rail the memo is the only thing that says which order was paid. FT4 memos are decided by the receiving account, and they are never merely optional: until you run enable_transfer_memo a memo cannot be attached at all, and afterwards a transfer without one is refused by the chain. Rather than take money it cannot attribute, the checkout withholds the Chromia option entirely until the payout account requires memos; your other chains are unaffected. Turn it on once, from the wallet that controls the account, in Settings → Wallets → Transfer memos.

Know the trade before you do. Once memos are required, any sender that cannot attach ours can no longer pay you in CHR — an exchange withdrawal is the common case, since it overwrites the memo with its own. Those transfers are refused on chain and the sender keeps their funds, which is the better outcome: the alternative is money arriving with nothing to identify it, and no keys here to return it with.

The same memo is why an exchange address is a poor payout address here: 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, which carry no memo at all.

What this store can be paid in

GET /v1/assets — with a secret key, because the caller is an application server building a payment form.

{
  "object": "list",
  "data": [
    { "object": "asset", "id": "chr", "label": "CHR", "chains": ["chromia", "bsc"] },
    { "object": "asset", "id": "usdc", "label": "USDC", "chains": ["bsc"] }
  ],
  "livemode": false
}

id is what goes in settlement_asset, label is what to print for a customer, and chains are the rails a payment in it can be made on, in the order the checkout will offer them.

Ask this instead of shipping a list. Which assets a store accepts is the merchant's own setting, so a copy in your app is one that goes stale silently: the merchant switches USDT off, your picker keeps offering it, and the first thing anybody notices is a 400 at creation — after the customer chose it. That is not a hypothetical, it is what the first integration built against this did.

The answer is exactly what POST /v1/payments will accept: the store's selection intersected with what this gateway offers, and narrowed to assets with a verified payout wallet on a chain that carries them. Reporting the merchant's switches without the wallet check would trade one wrong list for another. An empty data means this store cannot be paid at all yet — say so rather than opening a checkout.

Cache it for a minute or so if you render it often; it changes when a merchant changes a setting.

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.

Two refusals here are about the store rather than the request, so retrying the same body will not fix either. 403 means the store is paused or closed and is taking no new payments; the message says which. 400 on settlement_asset can mean the store has switched that asset off in Settings → Assets you accept, which reads differently from no rail carrying it and is fixed in a different place. Both are worth surfacing to whoever runs the store rather than retrying — nobody watching a queue can tell them apart from an outage.

Neither affects a payment that already exists. A payment created before a store paused stays payable, its transfer is still detected and credited, and its webhooks still fire — pausing stops the inflow, not the work already in motion.

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.

Rates

GET /v1/rates/chr_usd is the rate a USD-priced payment would be quoted at right now, so a cart page can show "≈ 1323 CHR" before anything is created. Pairs are chr_usd, usdc_usd and usdt_usd — GET /v1/rates lists them. Anything else is a 404.

Pass one or neither — both is a 400. With neither, quote comes back null and you get the rate alone.

{
  "object": "rate",
  "pair": "chr/usd",
  "base": "chr",
  "rate": "0.0151",
  "rate_micro_usd": 15100,
  "source": "binance:CHRUSDT",
  "as_of": 1787508014,
  "age_ms": 0,
  "max_age_ms": 300000,
  "quote": { "usd": "19.99", "base": "1323.850000" }
}

rate is USD per 1 unit of the base asset, in the same format payment.rate carries. source is the venue it came from, as_of when it was read, and max_age_ms the age past which this gateway refuses to quote with a rate at all — a reading older than that is a dead feed, not a price.

usdc_usd and usdt_usd return "source": "peg:usdc" and a rate of 1. That is the same 1:1 assumption a USD-priced stablecoin payment already makes; it is not a market reading, and if a peg breaks this endpoint will not be the thing that tells you.

503 if no rate can be obtained, the same as a USD-priced create: no price is ever invented.

History

GET /v1/rates/chr_usd/history returns what the feed said, newest first. The watcher samples every five minutes and keeps a year, so nothing before this gateway started recording exists, and a gap means the feed was unreachable then — no point is interpolated.

{
  "object": "list",
  "pair": "chr/usd",
  "base": "chr",
  "from": 1787421614,
  "to": 1787508014,
  "data": [{ "at": 1787507900, "rate": "0.0151", "rate_micro_usd": 15100, "source": "binance:CHRUSDT" }]
}

A stablecoin pair is a 400: a peg is an assumption, not an observation, so there is no series to read.

Without a key, from a browser

GET /rates, GET /rates/:pair and GET /rates/:pair/history are the same three routes, unauthenticated, any origin, and limited per IP — plus a cap on the public surface as a whole, since a caller reaching the origin directly can write its own X-Forwarded-For. A cart page showing an approximate CHR figure is browser code with no business holding a secret key, and the number is one the venues we read publish to anyone.

const { quote } = await fetch("https://pay-api.chromia.com/rates/chr_usd?usd=19.99").then((r) => r.json())
// quote.base — the CHR to show next to the button

Responses carry cache-control, so a CDN or the browser itself answers most of this traffic. Everything else about the payload is identical to the authenticated form.

Refunds

There is no route here to trigger one, and there will not be: a refund moves money out of the merchant's own wallet and needs a signature only a person holding that key can give. So refunds start in the dashboard — open a payment, or the Reconcile queue, and press Refund — and are signed in the merchant's wallet on a page the gateway prepares.

What an integration sees of it is one event, payment.refunded, described in Webhooks. The payment object itself does not change: a refunded payment is still confirmed, and amount_paid still reports what arrived, because a refund is a transfer in the other direction rather than a reversal of the first one. Anything you need to net off, net off from the refund event.

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.