Overview

All invoice IDs use opaque inv_ tokens. Internal UUIDs are never returned.

Authentication

Authorization: Bearer sk_live_...

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

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


Scope	`invoices:read`
Pagination	Cursor (`limit`, `starting_after`, `ending_before`)
Rate limit	Read bucket (`observe`)

Query: status, external_order_id, payment_link_id (plink_...).

Retrieve invoice

GET /v1/invoices/{id}


Scope	`invoices:read`
Path `id`	`inv_...` 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


Scope	`invoices:write`

Only open invoices (awaiting_payment, quoted, etc.) can be cancelled. Emits invoice.cancelled webhook.

Health

Invoices

Transactions

Pay Links

Public Pay Links

Webhooks API

WooCommerce

Webhooks

Overview

Authentication

Create invoice

Request body

Response `201`

Errors

Webhooks

Examples

Security

List invoices

Retrieve invoice

Poll status

Cancel invoice

​Authentication

​Create invoice

​Request body

​Response 201

​Errors

​Webhooks

​Examples

​Security

​List invoices

​Retrieve invoice

​Poll status

​Cancel invoice

Authentication

Create invoice

Request body

Response `201`

Errors

Webhooks

Examples

Security

List invoices

Retrieve invoice

Poll status

Cancel invoice