Pay API

Overview¶

Base URL: https://api.cherum.io/pay/v1. All request and response bodies are JSON. Amounts in USD are numbers; on-chain amounts are decimal strings in the token’s smallest unit (atoms) — never floats.

Watched coins. Cherum can only detect a payment for a coin and network it indexes: USDC on ethereum, base, arbitrum, optimism, polygon, bsc, and USDT on ethereum, arbitrum, polygon, bsc. Invoices for anything else are created, but nothing on-chain will move them — the create response tells you so via watched: false, and you settle them yourself with mark.

Confirmation depth per network, after which a payment counts as confirmed: ethereum 2, base 3, arbitrum 3, optimism 3, bsc 15, polygon 30 blocks. The chain scanner ticks every 30 seconds.

Authentication¶

Send your key in the Authorization header. Both spellings work:

Authorization: token chm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
Authorization: Bearer chm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys look like chm_live_ or chm_test_ followed by 32 alphanumeric characters. The full secret is shown once, at creation, in the dashboard — Cherum stores only its hash, so a lost key is rotated, not recovered. Create and revoke keys under Dashboard → Developers.

A new key is created with invoices.create and invoices.read only. webhooks.manage is a checkbox on the same screen — tick it when you create the key if your code will manage endpoints, or manage them in the dashboard instead. Permissions are fixed at creation: to change them, create a new key and revoke the old one.

A key sees only the invoices it created. Calling a route your key lacks the permission for returns 403 forbidden; if the account behind the key is blocked, every call returns 403 account_blocked.

Who am I? GET /me answers with the key's own passport — prefix, label, mode, permissions, creation and expiry — and needs no permission beyond authenticating. It is the first call to make on an unexpected 403. Keys can be issued with an expiry (a checkbox in the dashboard): an expired key stops authenticating by itself — hand one to a contractor without letting it outlive the contract. The same answer carries features: what the service is doing right now, so your code can read it instead of guessing. Today that is one field, buyerReceipt — whether Cherum e-mails the payer a receipt for the customerEmail you send. It is false in production at the time of writing, and false there means the address you hand over buys the payer nothing.

Errors & rate limits¶

Errors carry the same envelope: {"error":{"code":"…","message":"…"}}. Validation errors add details — an array of {path, message} straight from the schema. A refused refund adds detail — the numbers behind the refusal, so you can show them without parsing the sentence: {"error":{"code":"over_cap","message":"That is more than what is left refundable on this invoice. $3.20 is still refundable here.","detail":{"headroomUsd":3.2}}}. An amount under the accepted floor answers the same way: {"error":{"code":"below_minimum","message":"Minimum for USDC on base is $2. …","detail":{"minimumUsd":2,"asset":"USDC","network":"base"}}}. Read message for people and code for programs; detail is a convenience, never the only place a number appears.

Per-route limits, counted per IP per minute: create invoice 120, read one invoice 300, list invoices 120, mark 60, create webhook 30, list webhooks 120, rotate secret 30, ping 30, enable / disable / resend 60, deliveries 120. A global 600-per-minute ceiling applies on top. Exceeding a limit returns 429 from the rate limiter, whose body differs from the error envelope above:

{ "statusCode": 429, "error": "Too Many Requests", "message": "…" }

Create an invoice¶

POST /invoices · needs invoices.create

On a live key, coin and network are what make an invoice payable: pass them together and Cherum issues the payment address, the exact crypto amount and the decimals itself. Omit the pair and you get a valid invoice with no requisites — the payer then picks a payment method on the checkout page.

curl -X POST https://api.cherum.io/pay/v1/invoices \
  -H "Authorization: token $CHERUM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4417" \
  -d '{
    "amountUsd": 49.90,
    "orderId": "4417",
    "coin": "USDC",
    "network": "base",
    "expiresInMinutes": 30,
    "metadata": { "customer": "cus_812" }
  }'

{
  "invoice": {
    "id": "inv_2f5a91c0d4e7b8a3c1f0e2d4",
    "checkoutUrl": "https://pay.cherum.io/i/inv_2f5a91c0d4e7b8a3c1f0e2d4",
    "orderId": "4417",
    "mode": "live",
    "amountUsd": 49.9,
    "coin": "USDC",
    "network": "base",
    "address": "0xCherumIssuedDepositAddress",
    "memo": null,
    "amountCrypto": "49900000",
    "tokenDecimals": 6,
    "priceAtSeen": null,
    "status": "new",
    "anomaly": "none",
    "anomalyAmount": null,
    "metadata": { "customer": "cus_812" },
    "expiresAt": "2026-07-30T12:30:00.000Z",
    "seenAt": null,
    "confirmedAt": null,
    "createdAt": "2026-07-30T12:00:00.000Z"
  },
  "watched": true
}

memo is always null today, and that is not an omission: every network Cherum accepts issues a fresh address for each invoice, so a payment identifies itself by the address alone. The field is reserved for networks where one address serves everyone and a tag tells payments apart — XRP, Stellar, Cosmos. Do not branch on it; if it ever becomes non-null, it will be documented here first.

watched is the honest answer to “will Cherum see this payment by itself”: it is true only when the coin and network are indexed and the invoice carries exact requisites — on a live key that happens whenever you passed the pair; on a test key it also needs your amountAtomic.

Idempotency. Send Idempotency-Key (≤128 chars) on create. Replaying it with the same body returns the first response with header idempotency-replayed: true; with a different body, 400 idempotency_error; while the first call is still running, 409 idempotency_conflict. If creation fails, the key is released so you can honestly retry. Records are swept after 24 hours.

One open invoice per address. Live invoices each get their own one-time address, so they never collide. On test keys, where the address is yours, a second open invoice for the same address + coin + network returns 409 address_busy — two invoices on one address cannot be told apart on-chain. An amount below the floor for the coin and network is a different answer — 422 below_minimum, with the floor in detail — not a busy address.

Read an invoice¶

GET /invoices/:id · needs invoices.read. Returns the invoice, every payment matched to it, and credited — the money truth for accounting: grossUsd, feeUsd, creditedUsd, the settled asset/chain/atoms and creditedAt. It is the same record the invoice.credited webhook fires from, and null until settlement happens.

{
  "invoice": { "id": "inv_2f5a…", "status": "confirmed", "anomaly": "none", "…": "…" },
  "payments": [
    {
      "tx_hash": "0x9c1e…",
      "network": "base",
      "amount_atomic": "49900000",
      "confirmed": true,
      "seen_at": "2026-07-30T12:04:11.000Z",
      "confirmed_at": "2026-07-30T12:04:47.000Z"
    }
  ]
}

List invoices¶

GET /invoices · needs invoices.read. Query: limit (1…100, default 20), status (one of the statuses below), orderId (exact match on the orderId you set at creation — the way back to a payment when your webhook receiver was down and you only have your own order number), starting_after (an invoice id of this key). Newest first.

{
  "invoices": [ { "id": "inv_2f5a…", "…": "…" } ],
  "next": "inv_2f5a91c0d4e7b8a3c1f0e2d4"
}

next is the id to pass as starting_after for the following page, or null on the last page. The cursor walks the pair (created at, id), so invoices created in the same millisecond are never skipped. An unknown or foreign starting_after is rejected with 400 invalid_cursor rather than silently restarting from page one.

Mark an invoice¶

POST /invoices/:id/mark · needs invoices.create. Body: {"as":"confirmed"} or {"as":"invalid"}. This is your manual verdict for payments Cherum cannot see — an unwatched coin, an off-chain settlement, a dispute you resolved. The invoice moves to that status with anomaly: "marked"; marking it confirmed emits invoice.confirmed, marking it invalid emits nothing. Response: {"invoice": {…}}.

Cancel an invoice¶

POST /invoices/:id/cancel · needs invoices.create. No body required — if your HTTP client insists on Content-Type: application/json, send {}. Only a new invoice can be canceled: the payment page stops accepting and invoice.canceled is emitted in the same transaction. Canceling an already-canceled invoice is an idempotent 200 and emits nothing. Once a payment has been seen the answer is 409 not_cancelable — money in flight cannot be waved away, the way back is a refund. Response: {"invoice": {…}}.

Statuses & anomalies¶

An invoice carries two independent axes. status answers “where is this in its life”, anomaly answers “is anything off about the money”.

Rules that decide those transitions:

• Tolerance. A payment counts as sufficient at or above expected − tolerance. The tolerance is the LARGER of a percentage of the invoice (0.1% today) and a flat amount ($2 today), and the flat side is capped at 3% of the invoice so it cannot swallow a real underpayment on a small one. On a $500 invoice that is $2; on a $50 invoice it is $1.50 (the 3% cap, not the full $2); on a $5,000 invoice it is $5 (the percentage wins). Both values are policy settings, not constants — the numbers above are the ones in force.
• Late window. A payment arriving after expiry is accepted for another 24 hours by default and flagged repriced; later than that, nothing changes.
• Confirmed is sticky. Once confirmed, an unconfirmed trickle cannot drag the invoice back to seen.
• Extra money after confirmation. By default a duplicate payment is recorded but the invoice is not re-priced; the platform can be configured to re-price it into overpaid instead. Excess is always counted net of refunds you have already settled.
• Expiry never kills a paid invoice. An invoice paid above the floor but still maturing stays alive and confirms normally.
• Priority. repriced outranks overpaid; marked and repriced are never overwritten by a later duplicate.

Webhook endpoints¶

All routes below need webhooks.manage.

Omitting events subscribes the endpoint to all 15 events of the dictionary below. A URL that resolves to a private or loopback address is refused with 400 unsafe_url, at registration and again before every delivery. Redirects are not followed — a signed body never travels to a third host.

Events & payload¶

Subscribable events: invoice.created, invoice.seen, invoice.confirmed, invoice.expired, invoice.underpaid, invoice.overpaid, invoice.repriced, invoice.credited, invoice.late_inflow, invoice.canceled, refund.created, refund.completed, refund.failed, refund.canceled, refund.expired. For deposit-lane payments invoice.confirmed means the payer paid; invoice.credited fires later, when the funds have actually settled to your Cherum balance with the fee deducted — use it for accounting. Its data carries id, orderId, grossUsd, feeUsd, creditedUsd, asset, chain, amountAtomic and overpayCreditedUsd. overpayCreditedUsd appears only on an overpaid invoice whose excess ended up with you instead of going back to the payer — no refund claim was open and overpayments are set to settle to the merchant, which is not the default. It is the part of creditedUsd that came from that excess. On every other payment the field is absent from the JSON, not sent as zero, so test for its presence rather than its value. invoice.late_inflow fires when money lands after the invoice closed, or in an asset the invoice did not ask for: nothing is credited automatically — you decide in the dashboard whether to take it or send it back. Its data carries ledgerId, asset, chain, amountAtomic, usd, arrivedAt and decideBy. invoice.canceled fires when you cancel a still-unpaid invoice (API POST /invoices/:id/cancel); only new invoices can be canceled — once a payment is seen, the way back is a refund. Test pings arrive as webhook.ping; it is deliberately outside the dictionary, so you cannot subscribe to it and it is never broadcast.

data is the same invoice object the API returns.

{
  "id": "msg_7d2c4b1a9e8f0c3d5a6b7c8d",
  "type": "invoice.confirmed",
  "apiVersion": "2026-07-11",
  "createdAt": "2026-07-30T12:04:47.000Z",
  "data": { "id": "inv_2f5a…", "status": "confirmed", "…": "…" }
}

Every delivery gets its own id, unique per endpoint — use it to deduplicate. Events are queued inside the same database transaction that changes the invoice, so a confirmed payment cannot be committed without its event. Endpoints registered in the dashboard for your account receive events from your API keys too — so if one address is registered twice, once in the dashboard and once by an integration, it receives each event twice, with a different id and a different signature each time. Two endpoints on one URL is a duplicate, not a redundancy: keep one, or deduplicate on type together with createdAt and the invoice id, which are identical across the copies.

Verify a signature¶

Cherum signs with Standard Webhooks. Three headers travel with each delivery:

The signed string is {webhook-id}.{webhook-timestamp}.{raw body}, HMAC-SHA256 with your secret, base64. The secret’s whsec_ prefix is stripped and the rest is base64-decoded to get the key bytes. Sign the raw body — re-serialising JSON changes the bytes and breaks the check.

import { createHmac, timingSafeEqual } from 'crypto';

// rawBody: Buffer or string, exactly as received.
export function verify(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const ts = headers['webhook-timestamp'];
  const got = String(headers['webhook-signature'] || '').split(' ');

  // Reject stale deliveries — five minutes is a sane window.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const key = secret.startsWith('whsec_')
    ? Buffer.from(secret.slice(6), 'base64')
    : Buffer.from(secret);
  const mine = 'v1,' + createHmac('sha256', key)
    .update(`${id}.${ts}.${rawBody}`)
    .digest('base64');

  return got.some((sig) => sig.length === mine.length
    && timingSafeEqual(Buffer.from(sig), Buffer.from(mine)));
}

Accept the delivery if any of the supplied signatures matches — during a secret rotation there are two.

Retries & auto-disable¶

Answer 2xx and the delivery is done. Anything else is retried: network errors, timeouts, 429, 5xx — and 4xx too, 401 and 403 included, because a receiver that is redeploying or rotating a secret answers exactly like that and should not cost you an event.

404 and 410 mean the URL does not exist on your side. They go on the same ladder — but a short one: if the address is still missing on the fourth attempt (about 35 minutes after the first failure) we switch the endpoint off with that reason on it and email you, instead of knocking for 28 hours. The grace exists because a plugin update, a maintenance page or a restart answers 404 for a minute, and one such minute used to cost a store its notifications for good. The only answer never retried is our own refusal to call an unsafe URL (it must be public https) — that one is never called at all.

Retry schedule, up to 8 attempts over roughly 28 hours: immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h. Each attempt waits at most 10 seconds for your response and stores the first 2 KB of your body in the journal — a useful place to leave a reason.

An endpoint is switched off automatically in three cases: a missing address (above), five days of unbroken failures, or another endpoint of your account taking over the same URL. Each writes its reason into disabled_reason and sends you an email naming it.

Events that happen while an endpoint is off are not lost. They are queued as deferred and held for 3 days from the moment each happened; POST /webhooks/:id/enable puts them back in the queue and tells you how many (resent), and how many had aged out (expired). Anything older than the hold window is closed as undelivered, and the way to catch up on it is GET /v1/invoices. Delivery statuses you will see in the journal: pending, sending, delivered, deferred, exhausted.

Test pings are capped at 60 per hour per key; beyond that, 429 ping_budget_exceeded.

Rotating the secret¶

POST /webhooks/:id/rotate-secret issues a new secret and keeps the previous one valid for 24 hours. During that window every delivery carries two signatures, so deploy at your own pace: store the new secret, keep accepting the old one until you have rolled it out, and no delivery is lost. After 24 hours the old secret stops being signed with.

Delivery journal¶

Both delivery routes return the same fields: id, event_id, event_type, invoice_id, attempt, status, payload, response_code, response_body, next_retry_at, delivered_at, first_delivered_at, last_attempt_at, manual_retries, last_manual_retry_at, created_at; the single-delivery route adds endpoint_id. These are snake_case, like payment rows. first_delivered_at is the moment it first succeeded and is never overwritten — a manual retry adds an attempt, it does not rewrite history.

POST /deliveries/:id/resend puts a delivery back in the queue right away, counted in manual_retries. An already delivered one may be resent — it goes out with the same webhook-id, so a receiver that de-duplicates will recognise it. It refuses with 404 if the delivery is being sent at this very moment, if its endpoint is disabled, or if it is deferred — a held delivery is already waiting for the endpoint to come back, and switching the endpoint on is what releases it. The dashboard button and this route follow one and the same rule.

Balance & payouts¶

GET /balance · needs invoices.read. Your settled balances by asset and chain, in atoms, plus refundReserves — money already set aside for open refunds (it left the balance when the refund was filed, this is where it went).

GET /payouts · needs invoices.read. Query: limit (1…100, default 50). Payouts to your settlement address, newest first: amount and delivery fee in atoms, trigger (per_payment or threshold), status, txHash. Payouts are delivered in the asset and network of your settlement pair — USDC on Base by default, other registered pairs as configured in the dashboard.

Live keys only. Both routes answer a chm_test_ key with empty lists and "liveOnly": true — not an error, and not your live figures either. There is no such thing as a test balance: only live invoices settle into a balance, and payouts leave that same balance. The dashboard says the same thing on its own screens when you switch it to Test.

Refunds¶

Refunds are driven by the API since 26 Aug 2026 — the routes below need the refunds.manage permission (a checkbox at key issue time; existing keys need reissuing to gain it). Refunds pay out in USDC on Base to the wallet the payer names on the checkout page; the amount you name is what the payer receives, and our fee plus network cost is added on top and reserved against your balance.

The dashboard drives the very same pipeline — API and buttons cannot disagree.

The standard path. Payments land on a Cherum deposit address and settle into your balance with us — this lane is custodial — so refunds out of that balance are sent by Cherum on your instruction — you name the amount and the reason in the dashboard, the payer names the wallet on the checkout page, and we pay it in USDC on Base. The amount plus our fee and network cost is reserved against your balance when you file the request and released if it does not go through. The refund.* webhooks below report every outcome of this path.

Older direct invoices. Invoices issued back when they carried your own receiving address paid straight to your wallet — Cherum never held those funds, so only you can send them back. On an overpayment such an invoice turns overpaid with the excess in anomalyAmount, the payer leaves a return address on the hosted checkout page, the request appears in your dashboard, you send the excess from your own wallet and close the request there. Closing it lowers the recorded excess, so a later duplicate payment never shows a refund you already made.

Test mode¶

Invoices carry a mode of live or test, inherited from the key that created them. Test invoices are excluded from revenue figures and cannot use the exchange-friendly deposit lane.

Create a test key yourself: Dashboard → Developers → Create key → Mode: Test. Test keys start with chm_test_ and work against this same API — same endpoints, same webhook signatures. Invoices they create are sandbox invoices: no scanner watches them and no real money can settle them. Instead you drive them by hand from the Pay section of the dashboard — mark them paid, underpaid, overpaid or expired — and each transition runs through the same status machine and fires real webhooks to your endpoint, which is exactly what you want to test against. When you are ready, create a live key and change one string.

Drive it from CI. POST /invoices/:id/simulate with a chm_test_… key and {"event":"seen"|"confirmed"|"underpaid"|"overpaid"|"expired"|"credited"} pushes a test invoice through the same state machine production uses — statuses change and the webhooks fire for real. A live key gets 403 sandbox_key_required. Every event except expired needs requisites (coin/network/amountAtomic) on the invoice — without them there is no payment to move, and the call answers 409 no_amount. expired is the exception on purpose: an invoice with no coin on it is the ordinary shape when the payer picks the rail on the checkout page, and “the payer walked away without choosing” is the commonest way an invoice ends, so it has to be rehearsable. credited emits the accounting webhook with the production body shape (grossUsd/feeUsd/creditedUsd at your live rate) WITHOUT moving money — sandbox never touches real balances. The dashboard button drives the very same simulator.

Payer endpoints¶

The hosted checkout at pay.cherum.io reads these public, unauthenticated endpoints. The invoice id is the capability — treat it as a secret, and do not build merchant logic on them; use the key-authenticated routes above.

Payment links themselves are created in the dashboard, not through this API.

Pay with anything¶

The merchant fixes the coin and network on the invoice; the payer can settle it with a different token they already hold on the same network. The checkout swaps it in the payer’s own wallet — an exact-buy through an on-chain aggregator, with the invoice address as the receiver. The merchant receives exactly the invoiced amount; whatever the swap does not use returns to the payer’s address in the same transaction. Funds never touch a Cherum account.

• Conversion fee: 0.30%, shown on the quote card before signing and already included in the quoted amount. No hidden spread — the route is quoted at market and the fee is a separate, published number.
• Networks: Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain. Curated payer-side tokens: ETH, USDC, USDT, DAI, WETH, cbBTC, ARB, OP, POL, BNB (network-dependent).
• The lane is open while the invoice is unpaid. Once any payment is seen, the swap lane closes — a shortfall is topped up with a direct transfer of the invoice coin.
• Quotes are single-use and expire in about a minute; building the transaction consumes the quote.

Full route index¶

Every key-authenticated route that exists, so you can see there is nothing hidden. All are relative to https://api.cherum.io/pay/v1.

Questions, or something here that does not match what the server did? Write to [email protected] — a documentation bug is a bug.