Skip to main content
All invoice IDs use opaque inv_ tokens. Internal UUIDs are never returned.

Authentication

Authorization: Bearer sk_live_...

Create invoice

POST /v1/invoices
Scopeinvoices:write
IdempotencyNot supported on this route
Rate limitWrite bucket (enforce)

Request body

FieldRequiredValidation
amountYesDecimal string, settlement amount
currencyYesISO currency code
external_order_idNoMerchant reference
callback_urlNoHTTPS webhook target (developer keys)
return_urlNoBuyer redirect after payment
metadataNoJSON object; sensitive keys stripped in responses

Response 201

Returns id (inv_...), status, checkout_url, amount, currency, output_asset, expires_at.

Errors

CodeHTTPWhen
INSUFFICIENT_SCOPE403Missing invoices:write
payout_wallet_not_configured400Store payout not set
store_mismatch403store_id does not match key

Webhooks

invoice.created when the invoice is persisted.

Examples

curl -X POST https://api.meum.io/v1/invoices \
  -H "Authorization: Bearer sk_live_EXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"amount":"99.00","currency":"USD","external_order_id":"order-1001"}'
const res = await fetch("https://api.meum.io/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "99.00", currency: "USD" }),
});
$ch = curl_init("https://api.meum.io/v1/invoices");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_live_EXAMPLE",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["amount" => "99.00", "currency" => "USD"]),
  CURLOPT_RETURNTRANSFER => true,
]);

Security

Never log full API keys. checkout_url is buyer-facing; do not embed secrets in metadata.

List invoices

GET /v1/invoices
Scopeinvoices:read
PaginationCursor (limit, starting_after, ending_before)
Rate limitRead bucket (observe)
Query: status, external_order_id, payment_link_id (plink_...).

Retrieve invoice

GET /v1/invoices/{id}
Scopeinvoices:read
Path idinv_... public token
Response uses snake_case. Money fields are strings.

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
Scopeinvoices:write
Only open invoices (awaiting_payment, quoted, etc.) can be cancelled. Emits invoice.cancelled webhook.