Invoice API

Download OpenAPI · merchant core v1.1.0

Batch invoices

Use POST /invoice-batches/quote to preview 1–25 invoices, then POST /invoice-batches with a persisted Idempotency-Key. Send items and a decimal budgetCredits including creation and success fee reserves. Normal invoice pricing applies; no extra batch fee. Each invoice commits independently. Inspect every result and retry the identical batch to resume without duplicating successful invoices. Maximum 1,000 retained batch bindings per workspace; bindings do not expire automatically.

Recover missed notifications

GET /changes?after=0 returns events, nextCursor and hasMore. Save the cursor after durable processing; IDs are decimal strings. A 410 cursor_expired response requires reconciling retained receipts before restarting from restartCursor. Never fulfill from a browser redirect. Use GET /invoice-search?q=... for exact invoice number, order reference, checkout URL or transaction searches; follow nextCursor even on empty pages.

Responses include X-Request-ID and X-API-Version. Standard JSON errors include a stable code and requestId. Retry network errors and 429/502/503/504 with the same key and body and bounded backoff. A batch HTTP 200 can still contain individual failures.

Connect your application

The wallet used to sign in is the only receiving address for this workspace. Keys, invoices, renewals and buyer payment sessions cannot choose another wallet. A different payTo or key recipient returns 403. To receive at another address, sign in with that wallet in a separate workspace. Credit purchases pay the operator wallet.

Keys previously bound to another address are blocked: revoke and replace them. Old unpaid links to another address cannot accept new payments through this service. Paid records and already-submitted transactions keep their original recipient.

1. Open API in your workspace. Create a key with Create and read invoices permissions. The receiving address is fixed to your signed-in workspace wallet.
2. Save the secret on your server. It is shown only once. A workspace can have 5 active keys; creation is limited to 3 per hour and 10 per day. Copy your workspace's API base URL; it includes /w/<workspace-id>/v1.
3. Use the personalized curl example in the API tab. Replace YOUR_API_KEY with the corresponding secret in your server environment.

Never put API secrets in a website bundle, a mobile app, a URL or public logs. The only recipient is the wallet that owns the workspace. All API keys use this wallet. Omit payTo; an explicitly supplied different address is rejected. Read permissions cover the whole workspace, including invoices created through other keys.

Create an invoice

Send POST {API_BASE}/invoices with Authorization: Bearer YOUR_API_KEY, Content-Type: application/json and an Idempotency-Key of 8–128 characters.

{
  "amount": "10.00",
  "expiresIn": 3600,
  "externalId": "order-1001"
}

Amount inputs accept a dot or comma as the decimal separator, with up to six decimal places for USDC. Grouping separators and exponent notation are not supported. The portal blocks edits and pastes that exceed the amount limit or six decimal places; it never rounds a pasted amount. The portal normalizes the separator before sending the request. API clients must send a positive decimal string with a dot, such as "11.458991", within the limit returned by GET /billing (maxInvoiceAmount). The workspace description is limited to 500 characters (the API accepts up to 2048 UTF-8 bytes). Order references allow up to 128 UTF-8 bytes: 128 ASCII characters or 64 Cyrillic letters. Names also have server-enforced UTF-8 byte limits. The portal blocks edits and pastes that exceed these limits; non-ASCII characters can use several bytes.

The minimal invoice body is {"amount":"10.00"}: the workspace supplies its wallet as the recipient, currency defaults to USDC, the payer chooses a network, and the payment window defaults to one hour (1 credit). Workspace expiresIn must be 3600, 86400 or 432000 seconds. Omitting it defaults to one hour. These cost 1, 2 and 3 credits respectively. The payment deadline starts when the invoice is created, not when the payer first opens it. The checkout and workspace show the remaining time; the server enforces expiry. A pending verification may finish after the timer reaches zero—do not pay again. The amount is a decimal string denominated in USDC, not fiat USD. USDC is the only accepted payment currency. Omit currency to use USDC, or send "currency": "USDC" explicitly; other values are rejected. Omit network to let the payer choose. Keep the same idempotency key and request body when retrying after a timeout; use a new key for each new invoice. externalId helps you match an invoice to an order but does not replace idempotency.

Invoice numbers

Your workspace assigns permanent numbers such as INV-000001. Each workspace has its own sequence, shared by manual and API-created invoices. Omit number in workspace API requests; use externalId for your own order reference. Read the assigned number from the invoice response. Retries keep the same number; cancellation and payment-link renewal never reuse or replace it. Numbering does not reset each year.

Open checkout

A successful creation returns HTTP 201 and an invoice id. Build the browser link by removing the trailing /v1 from your API base URL and appending /i/{id}:

https://YOUR_HOST/w/YOUR_WORKSPACE_ID/i/INVOICE_ID

The invoice response's url is the protocol payment endpoint, not the browser checkout link. Treat payment links and invoice IDs as private links: anyone holding them can view the public payment details.

Useful endpoints

Revoke an exposed key and issue a replacement. Creating a replacement does not change existing invoices or the workspace credit balance.