inv_ tokens. Internal UUIDs are never returned.
Authentication
Create invoice
POST /v1/invoices
| Scope | invoices:write |
| Idempotency | Not supported on this route |
| Rate limit | Write bucket (enforce) |
Request body
| Field | Required | Validation |
|---|---|---|
amount | Yes | Decimal string, settlement amount |
currency | Yes | ISO currency code |
external_order_id | No | Merchant reference |
callback_url | No | HTTPS webhook target (developer keys) |
return_url | No | Buyer redirect after payment |
metadata | No | JSON object; sensitive keys stripped in responses |
Response 201
Returns id (inv_...), status, checkout_url, amount, currency, output_asset, expires_at.
Errors
| Code | HTTP | When |
|---|---|---|
INSUFFICIENT_SCOPE | 403 | Missing invoices:write |
payout_wallet_not_configured | 400 | Store payout not set |
store_mismatch | 403 | store_id does not match key |
Webhooks
invoice.created when the invoice is persisted.
Examples
Security
Never log full API keys.checkout_url is buyer-facing; do not embed secrets in metadata.
List invoices
GET /v1/invoices
| Scope | invoices:read |
| Pagination | Cursor (limit, starting_after, ending_before) |
| Rate limit | Read bucket (observe) |
status, external_order_id, payment_link_id (plink_...).
Retrieve invoice
GET /v1/invoices/{id}
| Scope | invoices:read |
Path id | inv_... public token |
Poll status
GET /v1/invoices/{id}/status
Lightweight status for hosted checkout polling. May include deposit_address, swap_status, and return_url when applicable.
Cancel invoice
POST /v1/invoices/{id}/cancel
| Scope | invoices:write |
awaiting_payment, quoted, etc.) can be cancelled. Emits invoice.cancelled webhook.