REST API.

{
  "error": {
    "type": "ofac_blocked",
    "message": "Payer address is on a sanctions list. Checkout will not load.",
    "param": null,
    "request_id": "req_01J0AHFG..."
  }
}

curl -X POST https://api.settle.xxx/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8f1a3b2c-7d4e-4f6a-9b8c-1e2d3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{ "amount_usd": 49.00 }'

curl https://api.settle.xxx/v1/get_started \
  -H "Authorization: Bearer sk_test_..."

{
  "steps": [
    { "name": "register_payout_address", "done": false,
      "next_tool": "register_payout_address" },
    { "name": "verify_domain",           "done": false },
    { "name": "set_branding",            "done": false },
    { "name": "register_webhook",        "done": false },
    { "name": "create_first_invoice",    "done": false }
  ],
  "next_action": "Next: Register a payout address on at least one chain..."
}

curl https://api.settle.xxx/v1/whoami \
  -H "Authorization: Bearer sk_test_..."

{
  "merchant_id": "mer_01HZX...",
  "display_name": "Acme",
  "mode": "test",
  "enabled_chains": ["base"],
  "verified_domain": "acme.com"
}

curl "https://api.settle.xxx/v1/integration_patterns/nextjs" \
  -H "Authorization: Bearer sk_test_..."

{
  "framework": "nextjs",
  "install": "bun add @settle/sdk",
  "env": ["SETTLE_API_KEY", "SETTLE_WEBHOOK_SECRET"],
  "files": [
    { "path": "app/api/checkout/route.ts", "code": "..." },
    { "path": "app/api/webhooks/settle/route.ts", "code": "..." }
  ]
}

curl -X POST https://api.settle.xxx/v1/payout_addresses \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "base",
    "address": "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e"
  }'

{
  "challenge": "Settle wants to verify that you own 0xA0Cf... on base. Token: a3f1c9...",
  "instructions": "Sign the challenge with the private key for 0xA0Cf... Then call POST /v1/payout_addresses/base/confirm."
}

curl -X POST https://api.settle.xxx/v1/payout_addresses/base/confirm \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e",
    "signature": "0x4c8e2d..."
  }'

{
  "verified": true,
  "chain": "base",
  "address": "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e",
  "message": "base payout verified. This chain is now active on every invoice."
}

curl https://api.settle.xxx/v1/payout_addresses \
  -H "Authorization: Bearer sk_test_..."

{
  "addresses": [
    { "chain": "base", "address": "0xA0Cf...", "verified": true, "registered_at": "..." }
  ]
}

curl -X POST https://api.settle.xxx/v1/domains \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com" }'

{
  "record_type": "TXT",
  "name": "_settle-verify",
  "value": "v=1;token=a3f1c9...",
  "instructions": "Add a TXT record at _settle-verify.acme.com. Verification completes ~30s after propagation."
}

curl -X POST https://api.settle.xxx/v1/usdt_ethereum/enable \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "min_invoice_usd": 1000 }'

{
  "enabled": true,
  "min_invoice_usd": 1000,
  "message": "USDT on Ethereum is now offered on invoices ≥ $1000."
}

curl https://api.settle.xxx/v1/branding \
  -H "Authorization: Bearer sk_test_..."

{
  "logo_url": "https://acme.com/logo.svg",
  "accent_hex": "#0E7C66"
}

curl -X PUT https://api.settle.xxx/v1/branding \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "logo_url": "https://acme.com/logo.svg",
    "accent_hex": "#0E7C66"
  }'

{
  "ok": true,
  "branding": { "logo_url": "https://acme.com/logo.svg", "accent_hex": "#0E7C66" }
}

curl -X POST https://api.settle.xxx/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8f1a-3b2c-..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 49.00,
    "customer_email": "buyer@example.com",
    "description": "Pro plan, monthly",
    "metadata": { "order_id": "ord_123" },
    "return_url": "https://acme.com/orders/success",
    "cancel_url": "https://acme.com/cart"
  }'

{
  "id": "inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0",
  "checkout_url": "https://pay.settle.xxx/c/inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0",
  "status": "pending",
  "expires_at": "2026-04-27T13:30:00Z",
  "amount_usd": 49.00,
  "payment_options": [
    { "currency": "USDC", "chain": "base", "amount": "49.000000", "network_fee_estimate_usd": 0.01 }
  ]
}

curl https://api.settle.xxx/v1/invoices/inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0 \
  -H "Authorization: Bearer sk_live_..."

{
  "id": "inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0",
  "status": "paid",
  "amount_usd": 49.00,
  "paid_at": "2026-04-27T12:32:14Z",
  "payment_tx": {
    "chain": "base",
    "hash": "0x9ad3b1...",
    "payer": "0x73f4a2..."
  },
  "checkout_url": "https://pay.settle.xxx/c/inv_01HZX9V0K1Q3Y2T7M3N4D5R8S0"
}

curl "https://api.settle.xxx/v1/invoices?status=paid&customer_email=buyer@example.com" \
  -H "Authorization: Bearer sk_live_..."

{
  "invoices": [
    { "id": "inv_01HZX...", "status": "paid", "amount_usd": 49.00, "paid_at": "..." },
    { "id": "inv_01HZW...", "status": "paid", "amount_usd": 99.00, "paid_at": "..." }
  ],
  "count": 2
}

curl -X POST https://api.settle.xxx/v1/invoices/inv_01HZX.../void \
  -H "Authorization: Bearer sk_live_..."

{
  "ok": true,
  "status": "voided",
  "invoice_id": "inv_01HZX..."
}

curl -X POST https://api.settle.xxx/v1/invoices/inv_01HZX.../simulate_payment \
  -H "Authorization: Bearer sk_test_..."

{
  "ok": true,
  "invoice": {
    "id": "inv_01HZX...",
    "status": "paid",
    "paid_at": "2026-04-27T12:32:14Z",
    "payment_tx": { "chain": "base", "hash": "0xtest...", "payer": "0xtestpayer..." }
  },
  "events_fired": [ /* WebhookEvent[] */ ]
}

curl -X POST https://api.settle.xxx/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.com/webhooks/settle",
    "events": ["invoice.paid", "invoice.expired"]
  }'

{
  "id": "wh_01HZX...",
  "url": "https://acme.com/webhooks/settle",
  "events": ["invoice.paid", "invoice.expired"],
  "signing_secret": "whsec_4f8c2d...",
  "created_at": "2026-04-27T12:00:00Z",
  "message": "Store signing_secret as SETTLE_WEBHOOK_SECRET. It will not be shown again."
}

curl https://api.settle.xxx/v1/webhooks \
  -H "Authorization: Bearer sk_live_..."

{
  "webhooks": [
    {
      "id": "wh_01HZX...",
      "url": "https://acme.com/webhooks/settle",
      "events": ["invoice.paid", "invoice.expired"],
      "signing_secret_masked": "whsec_••••8d4f",
      "created_at": "2026-04-27T12:00:00Z"
    }
  ]
}

curl -X PATCH https://api.settle.xxx/v1/webhooks/wh_01HZX... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["invoice.paid", "invoice.expired", "invoice.voided"],
    "rotate_secret": true
  }'

{
  "ok": true,
  "id": "wh_01HZX...",
  "url": "https://acme.com/webhooks/settle",
  "events": ["invoice.paid", "invoice.expired", "invoice.voided"],
  "signing_secret": "whsec_9b7e1a...",
  "message": "Update SETTLE_WEBHOOK_SECRET in the app — old secret is now revoked."
}

curl -X DELETE https://api.settle.xxx/v1/webhooks/wh_01HZX... \
  -H "Authorization: Bearer sk_live_..."

{ "ok": true, "deleted": "wh_01HZX..." }

curl "https://api.settle.xxx/v1/webhook_events?webhook_id=wh_01HZX...&status=failed" \
  -H "Authorization: Bearer sk_live_..."

{
  "events": [
    {
      "id": "evt_01HZX...",
      "webhook_id": "wh_01HZX...",
      "event": "invoice.paid",
      "status": "failed",
      "response_code": 502,
      "attempts": 4,
      "delivered_at": null,
      "payload": { /* the body that was POSTed */ }
    }
  ]
}

curl -X POST https://api.settle.xxx/v1/webhook_events/evt_01HZX.../replay \
  -H "Authorization: Bearer sk_live_..."

{
  "ok": true,
  "replayed_as": "evt_01HZY...",
  "original_id": "evt_01HZX..."
}

curl -X POST https://api.settle.xxx/v1/api_keys \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production server",
    "mode": "live"
  }'

{
  "id": "key_01HZX...",
  "name": "Production server",
  "mode": "live",
  "key": "sk_live_4f8c2d9b7e1a3c5f6d8e2a1b...",
  "created_at": "2026-04-27T12:00:00Z",
  "message": "This is the only time the full key is shown. Store it as SETTLE_API_KEY."
}

curl https://api.settle.xxx/v1/api_keys \
  -H "Authorization: Bearer sk_live_..."

{
  "keys": [
    {
      "id": "key_01HZX...",
      "name": "Production server",
      "mode": "live",
      "masked": "sk_live_••••2a1b",
      "created_at": "2026-04-27T12:00:00Z",
      "revoked": false
    }
  ]
}

curl -X DELETE https://api.settle.xxx/v1/api_keys/key_01HZX... \
  -H "Authorization: Bearer sk_live_..."

{ "ok": true, "revoked": "key_01HZX..." }