Orders and server-side verification.
Use explicit orders:create and orders:read permissions. These scopes cannot send funds, approve a payment, cancel an order or change checkout branding.
01Create from trusted server data
Keep the secret in your backend. Derive title, asset and price from your own stored order or catalogue. POST /v1/merchant/orders accepts a decimal string and optional unique externalReference. Include a stable Idempotency-Key persisted with that order. Never trust the buyer to supply price or receiving address.
02Recover the same order
Retry the identical body with the original key after a timeout. A successful replay returns the original order. GET /orders/by-reference?externalReference=... provides private reference recovery with orders:read. A different creation key with a duplicate reference receives 409 and creates no extra wallet.
03Read current payment evidence
GET /v1/merchant/orders/{id} refreshes validated payment state. List pages return the latest stored projection, default 20 and maximum 50, with nextCursor/before pagination. Use an individual authenticated read before fulfillment and bind id, externalReference, assetId, amountAtomic and workspaceId to your own stored order.
04Search and reconcile recorded orders
GET /v1/merchant/orders supports literal search across title, reference and IDs; state; exact assetId; and from/to creation timestamps. from is inclusive and to exclusive. Send ISO 8601 timestamps with a timezone. Retain the same filters when following nextCursor with before. An order cursor outside those filters is rejected.
05Read history and download records
GET /v1/merchant/orders/{id}/history returns recorded state changes, newest revision first, with default 20 and maximum 50 events per page. Use its nextCursor as before for this order. History excludes private snapshots and cannot authorize fulfillment. The dashboard exports only loaded list rows as CSV and prepares a private payment request PDF from an individual order. Its status describes the document snapshot, not a tax invoice or a new payment confirmation.
06Separate price, revenue and customer funds
grossReceivedAtomic pays the quoted price; netReceivedAtomic is the merchant receipt after recorded processingFeesAtomic. heldGrossAtomic remains pending. A manual acceptance preserves the original price and records waivedAtomic. Moving money from an internal wallet cannot masquerade as an external buyer payment.
07Respect current key authority
Per-key quotas apply to creation and recovery. Revocation, expiry, creator demotion, expired website verification and scope changes are checked again inside the protected transaction. Old read keys do not acquire order permissions. Bound credentials can use only their bound website for a return URL.
POST /v1/merchant/orders
Authorization: Bearer <SERVER_ONLY_API_KEY>
Idempotency-Key: store-order-1042-v1
{ "title": "Membership", "assetId": "ethereum:sepolia:usdc", "amount": "10", "externalReference": "STORE-1042", "expiresInMinutes": 30 }
GET /v1/merchant/orders/{privateOrderUuid}
GET /v1/merchant/orders/by-reference?externalReference=STORE-1042
GET /v1/merchant/orders?limit=20&state=paid&assetId=ethereum:sepolia:usdc
GET /v1/merchant/orders?limit=20&state=paid&assetId=ethereum:sepolia:usdc&before={lastOrderUuid}
GET /v1/merchant/orders/{privateOrderUuid}/history?limit=20
// A browser return URL or ?paid=true cannot update payment status.Open your workspace