Invoices

Scope invoices:write to create, switch and cancel; invoices:read to list and read.

Create an invoice#

/invoices
Authorization: Bearer cv2_<mode>_<prefix>_<secret>
Content-Type: application/json
Idempotency-Key: order_8823

Idempotency-Key is required; without it the request is refused 400 VALIDATION_ERROR ("Idempotency-Key header is required"). See Idempotency.

100 USDC on Ethereum:

{
  "chainId": "1",
  "assetType": "erc20",
  "assetContract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "amountDecimal": "100",
  "expiresInSeconds": 900,
  "metadata": { "external_ref": "order_8824" }
}

Response 201:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantId": "uuid",
  "chainId": "11155111",
  "assetType": "native",
  "assetContract": null,
  "receiveType": "POOL",
  "receiveAddress": "0xabc...def",
  "receiving_address": "0xabc...def",
  "receiveTag": null,
  "external_ref": "order_8823",
  "expectedAmount": "10000000000000000",
  "status": "CREATED",
  "displayStatus": "pending",
  "expiresAt": "2026-05-30T12:30:00.000Z",
  "minConfirmations": 2,
  "createdAt": "2026-05-30T12:00:00.000Z",
  "metadata": { "external_ref": "order_8823" },
  "customerId": null,
  "instructions": {
    "chainId": "11155111",
    "to": "0xabc...def",
    "tag": null,
    "amount": "10000000000000000",
    "assetType": "native",
    "assetContract": null
  }
}

Why a create can be refused — each answer carries a code and a message saying what to do:

Other refusals you may meet, each with its own code: CHAIN_DISABLED / ASSET_DISABLED 422 (we paused it), XRPL_XPUB_MISSING 400, XRPL_DEPOSIT_UNAVAILABLE 422, ADDRESS_NOT_WATCHED 503 (the address could not be registered for watching — retry), EMAIL_NOT_VERIFIED and ACCOUNT_NOT_ACTIVE 403.

Get an invoice#

/invoices/:id
Authorization: Bearer cv2_<mode>_<prefix>_<secret>

Response 200:

{
  "id": "550e8400-...",
  "chainId": "11155111",
  "assetType": "native",
  "assetContract": null,
  "assetDecimals": 18,
  "assetSymbol": "ETH",
  "receiveAddress": "0xabc...def",
  "receiving_address": "0xabc...def",
  "receiveTag": null,
  "receiveType": "POOL",
  "external_ref": "order_8823",
  "expectedAmount": "10000000000000000",
  "switchQuote": null,
  "paidAmountTotal": "10000000000000000",
  "amountStatus": "PAID",
  "overpaidAmount": "0",
  "status": "PAID_CONFIRMED",
  "displayStatus": "paid",
  "expiresAt": "2026-05-30T12:30:00.000Z",
  "confirmedAt": "2026-05-30T12:12:00.000Z",
  "finalConfirmations": 20,
  "finalizedAt": null,
  "createdAt": "2026-05-30T12:00:00.000Z",
  "updatedAt": "2026-05-30T12:12:00.000Z",
  "metadata": { "external_ref": "order_8823" },
  "merchantId": "uuid",
  "firstPaymentSeenAt": "2026-05-30T12:10:05.000Z",
  "minConfirmations": 2,
  "matchedTxHash": "0x...",
  "paymentSummary": { "paymentCount": 1, "totalPaidFromEvents": "10000000000000000", "matches": true }
}

paidAmountTotal is what has been credited so far, in base units. confirmedAt is when the invoice was paid; finalizedAt when it reached the ship-safe depth. metadata holds only the keys you sent.

donation is present on every invoice read and is null unless the invoice was created from a donation page: then it is { "donorName", "message", "usdCents", "amountMode", "presetUsed", "hiddenAt" } — the name and message the donor typed (null when left blank; the page shows "Anonymous"), the donation's value in US cents at the moment it was chosen (null when the coin could not be priced), whether the page priced in dollars (usd) or in the coin (asset), whether a preset was pressed, and hiddenAt — when you hid this donation from your public donation page and stream overlays in the dashboard (null while it is shown). A hidden donation still counts toward the page's goal.

List invoices#

/invoices?status=PAID_CONFIRMED&limit=20&offset=0
Authorization: Bearer cv2_<mode>_<prefix>_<secret>

Only your current mode's invoices (Live or Test) are listed.

Response 200:

{
  "invoices": [ /* invoices — the Get shape without minConfirmations, matchedTxHash and paymentSummary */ ],
  "total": 42,
  "metrics": { "total": 120, "byStatus": { "CREATED": 3, "PAID_UNCONFIRMED": 0, "PAID_CONFIRMED": 100, "PAID_LATE": 0, "EXPIRED": 17, "CLOSED": 0 }, "byAsset": [ /* … */ ] },
  "limit": 10,
  "offset": 0
}

total counts the invoices matching your filters — use it to page. metrics summarises the same filters without status; it is null when the summary could not be computed, and the list is still served.

List an invoice's payments#

/invoices/:id/payments
Authorization: Bearer cv2_<mode>_<prefix>_<secret>

Every on-chain transfer matched to the invoice, on every network — useful when a payer sent the amount in several transfers. On Bitcoin, paymentEventId is null and a transfer still in the mempool is listed with no blockNumber but not counted in summary. A transfer undone by a chain reorganisation stays listed but is not counted either. simulated is true for a simulated payment.

{
  "invoiceId": "550e8400-...",
  "expectedAmount": "10000000000000000",
  "paidAmountTotal": "10000000000000000",
  "paymentCount": 1,
  "payments": [
    {
      "paymentEventId": "uuid",
      "txHash": "0x...",
      "amount": "10000000000000000",
      "blockNumber": "19000000",
      "confirmations": 12,
      "minConfirmations": 2,
      "state": "confirmed",
      "stateLabel": "Confirmed",
      "seenAt": "2026-05-30T12:10:05.000Z",
      "createdAt": "2026-05-30T12:10:05.000Z",
      "simulated": false
    }
  ],
  "summary": { "totalPaidFromEvents": "10000000000000000", "invoicePaidTotal": "10000000000000000", "matches": true }
}

Cancel an invoice#

/invoices/:id/cancel
Authorization: Bearer cv2_<mode>_<prefix>_<secret>

Only an open invoice that has seen no payment at all can be cancelled — not even a partial one, or a Bitcoin payment still waiting in the mempool. Cancelling expires the invoice exactly as its clock would: its address is released after the usual cooldown, and you receive invoice.expired.

Response 200: { "success": true }

Simulate a payment (Test mode)#

/invoices/:id/simulate-payment
Authorization: Bearer cv2_test_<prefix>_<secret>
Content-Type: application/json

Pays an open test-network invoice without sending coins, so you can watch your integration handle every step. The payment goes through the same steps a real one does, a few seconds apart, and each step sends its webhook:

1. Detected — invoice.receiving (the invoice is PAID_UNCONFIRMED, or stays CREATED if the amount is short)
2. Confirmed — invoice.paid, invoice.underpaid or invoice.overpaid, once it reaches the invoice's confirmation depth
3. Final — invoice.final

The body is optional. With no amount it pays exactly what is still owed; pass amount (base units, as a string) to test a short payment or an overpayment:

{ "amount": "500000" }

Response 202:

{
  "invoiceId": "550e8400-...",
  "simulated": true,
  "amount": "1000000",
  "txHash": "sim_3f2a9c0d4b7e4e1a9b6c2d8e5f1a0b7c",
  "stages": ["detect", "confirm", "finalize"]
}

A simulated payment is marked everywhere: every webhook body carries "simulated": true, its txHash starts with sim_ (no block explorer has it), and the payment list and the payment page label it Simulated. Use a Test key — a Live key cannot see test invoices.

Change an invoice's network or coin#

/invoices/:id
Authorization: Bearer cv2_<mode>_<prefix>_<secret>
Content-Type: application/json

{
  "chainId": "137",
  "assetType": "erc20",
  "assetContract": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359"
}

How the amount changes. The same coin on another network (USDC on Ethereum → USDC on Base) keeps its value, re-expressed in the new asset's base units and rounded up. A different coin (USDC → ETH) is converted through USD at two price quotes each at most 60 seconds old, always from the invoice's original amount and coin (an earlier switch is never compounded), rounded up. After any switch the invoice carries switchQuote — { method, quote, at }, where method is unchanged, rescaled or converted, and quote is { sourceSymbol, sourceUsd, targetSymbol, targetUsd, quotedAt } for a conversion (null otherwise) — so the figure can be checked. It is null on an invoice never switched. Read the new expectedAmount from the response.

What can be switched. An invoice in CREATED status that has seen no payment, paid to a receiving address or to an XRP Ledger destination tag. Switching to the XRP Ledger follows your XRP deposit mode, as creating an invoice there does: in tag mode the invoice gets a new destination tag (receiveTag); in address mode, its own address. Switching away from a tagged invoice retires its tag: a payment that still arrives with the old tag is not credited to this or any other invoice; it is held for review — contact support with the transaction hash. The new address is locked before the old one is released.

The target must also pass every rule a new invoice there would (ASSET_NOT_ACCEPTED, CHAIN_NOT_IN_PLAN, DETECTION_UNAVAILABLE, POOL_NOT_PROVISIONED… with the same statuses as on create).

Response 200: the updated invoice, in the Get shape without firstPaymentSeenAt, minConfirmations, matchedTxHash and paymentSummary.

Public invoice view#

These need no key — the invoice id is the only credential, so share it with the paying customer only. The hosted payment page for an invoice is https://app.unheld.io/invoice/<id>.

GET  /invoices/public/:id          # the payment page's data
GET  /invoices/:id/status          # the smallest view
POST /invoices/public/:id/cancel   # the payer cancels an unpaid invoice

/status returns id, status, expectedAmount, chainId, receiveAddress, receiving_address, receiveTag, assetContract and expiresAt. The payer's cancel follows the same rule as yours: no payment seen.