API and webhooks

Production API base:

https://api.settlebolt.com

Send JSON with Content-Type: application/json. Write requests with JSON bodies are capped at 5 MiB, with smaller caps on support ticket and feedback routes.

Dashboard APIs use the logged-in dashboard session token:

Authorization: Bearer <dashboard-session-token>

Only verified-email accounts can access the dashboard API. Mutating requests made through admin impersonation are rejected unless they are read-only.

Starter can use WooCommerce through the dedicated plugin key created by the Connect SettleBolt flow. That key is limited to payment_links:create and webhooks:write.

The Agent API is the supported surface for AI agents and backend automations. It requires an active paid Pro or Business subscription, uses scoped API keys from Developers, and is limited to merchant operations that are safe to automate. Agent keys are not accepted on dashboard endpoints and cannot manage wallets, billing, team members, or account deletion.

Required header:

Authorization: Bearer sb_live_...

Machine-readable OpenAPI:

https://settlebolt.com/openapi.json

Examples

All amounts are in EUR cents (5000 = EUR 50.00). Set "mode":"demo" to create in TEST mode; omit it for live. List endpoints accept ?mode=live or ?mode=demo, an unrecognized value returns 400 Invalid mode, and every payment.confirmed webhook carries a mode field so you can ignore demo events in production. Demo and live data are fully isolated: demo checkouts never move funds or send real emails, and on-chain settlement only ever attaches to live links and invoices.

1. Create a payment link

curl -X POST https://api.settlebolt.com/api/agent/payment-links \
  -H "Authorization: Bearer sb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Pro plan","amount":5000,"currency":"EUR","token":"USDC","chain":"base"}'

{
  "id": "pl_9f2c...",
  "checkoutSlug": "a1b2c3d4e5f6",
  "mode": "live",
  "walletAutoEnabled": null,
  "url": "https://settlebolt.com/checkout/?kind=l&slug=a1b2c3d4e5f6"
}

2. Create and send an invoice in one call (requires invoices:create + invoices:send)

curl -X POST https://api.settlebolt.com/api/agent/invoices/send \
  -H "Authorization: Bearer sb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "FPSHEAVEN",
    "customerEmail": "[email protected]",
    "invoiceNumber": "INV-0007",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base",
    "dueDate": "2026-08-01"
  }'

{
  "id": "inv_7a3e...",
  "invoiceNumber": "INV-0007",
  "status": "sent",
  "mode": "live",
  "payUrl": "https://settlebolt.com/checkout/?kind=pay&slug=...",
  "email": { "sent": true }
}

If you send lineItems, their total must equal amount. Invoice numbers are unique per merchant.

3. List recent payments

curl "https://api.settlebolt.com/api/agent/payments?limit=20" \
  -H "Authorization: Bearer sb_live_..."

{
  "payments": [
    {
      "id": "pay_4c1d...",
      "status": "confirmed",
      "token": "USDC",
      "chain": "base",
      "amount_usd_cents": 5000,
      "tx_hash": "0x8ab3...",
      "payment_link_id": "pl_9f2c...",
      "invoice_id": null,
      "created_at": "2026-07-05 12:30:00"
    }
  ],
  "limit": 20,
  "offset": 0
}

4. Receive and verify the payment.confirmed webhook

When a payment clears, SettleBolt POSTs a signed event to your endpoint. Verify the X-SettleBolt-Signature header (t=<timestamp>,v1=<hex>): compute HMAC-SHA256 over {timestamp}.{event_id}.{raw_body} with your endpoint's signing secret, compare in constant time, and reject timestamps older than 10 minutes.

import crypto from 'node:crypto'

function verifySettleBolt(rawBody, headers, secret) {
  const ts      = headers['x-settlebolt-timestamp']
  const eventId = headers['x-settlebolt-event-id']
  const parts   = Object.fromEntries((headers['x-settlebolt-signature'] || '')
                    .split(',').map(kv => kv.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 600) return false // stale
  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}.${eventId}.${rawBody}`).digest('hex')
  return !!parts.v1 &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
}

Example payload:

{
  "type": "payment.confirmed",
  "created_at": "2026-07-05T12:30:00.000Z",
  "data": {
    "payment_id": "pay_4c1d...",
    "status": "confirmed",
    "chain": "base",
    "token": "USDC",
    "amount": "50000000",
    "amount_eur_cents": 5000,
    "tx_hash": "0x8ab3...",
    "payment_link_id": "pl_9f2c...",
    "invoice_id": null,
    "payer_address": "0x1111...",
    "merchant_address": "0x2222...",
    "mode": "live"
  }
}

Respond with a 2xx quickly. SettleBolt retries with backoff on any non-2xx response, and includes a mode field so you can ignore demo events in production.

The WhatsApp channel lets a merchant pair a WhatsApp sender to a scoped SettleBolt agent. It uses the same paid Pro/Business, verified-email, plan-current, scope, wallet, and audit-log checks as the Agent API, but no API key is shown in WhatsApp.

Supported WhatsApp commands include:

send invoice to FPSHEAVEN [email protected] for EUR 1200 due July 16 using USDC on Base
create payment link Website deposit for EUR 500 using USDC on Base
add customer FPSHEAVEN [email protected]
payments
customers
status

WhatsApp cannot manage wallets, billing, team members, account deletion, dashboard sessions, or other high-risk settings.

The Telegram channel lets a merchant pair one Telegram account to scoped SettleBolt actions. It uses the same paid Pro/Business, verified-email, plan-current, scope, wallet, and audit-log checks as the Agent API. No API key is shown in Telegram.

Pair by sending /pair 123456 to the bot. After pairing, the bot shows buttons for payment links, invoices, customers, payments, account status, help, and clearing recent bot messages.

Telegram cannot manage wallets, payout changes, billing, team members, account deletion, dashboard sessions, custom domains, or settings.

Custom checkout domains may call only public checkout and public asset APIs. The public checkout response intentionally returns public RPC fallbacks only, never configured provider secrets.

Create and send an invoice with an agent key:

curl -X POST "$API/api/agent/invoices/send" \
  -H "Authorization: Bearer $SETTLEBOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "FPSHEAVEN",
    "customerEmail": "[email protected]",
    "invoiceNumber": "INV-0008",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base",
    "dueDate": "2026-07-16",
    "lineItems": [
      { "description": "Brand and website design", "qty": 1, "unitPrice": 90000 },
      { "description": "Hosting setup", "qty": 1, "unitPrice": 30000 }
    ]
  }'

Create a payment link:

curl -X POST "$API/api/payment-links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website design",
    "description": "Deposit",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base"
  }'

Create a draft invoice:

curl -X POST "$API/api/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "FPSHEAVEN",
    "customerEmail": "[email protected]",
    "invoiceNumber": "INV-0008",
    "amount": 120000,
    "currency": "EUR",
    "token": "USDC",
    "chain": "base",
    "dueDate": "2026-07-16",
    "lineItems": [
      { "description": "Brand and website design", "qty": 1, "unitPrice": 90000 },
      { "description": "Hosting setup", "qty": 1, "unitPrice": 30000 }
    ]
  }'

List payments with filters:

curl "$API/api/payments?status=confirmed,overpaid&chain=base&source=invoices" \
  -H "Authorization: Bearer $TOKEN"

Webhook management is available only during an active paid Pro or Business billing period.

payment.confirmed is the currently delivered merchant webhook event. Do not build against other event labels unless they are listed here as delivered.

Event headers:

X-SettleBolt-Event: payment.confirmed
X-SettleBolt-Event-Id: <event-id>
X-SettleBolt-Timestamp: 1783100000
X-SettleBolt-Signature: t=1783100000,v1=<hmac>

Signature base string:

<timestamp>.<event_id>.<raw_json_body>

Node verification shape:

import crypto from "node:crypto";

function verifySettleBoltWebhook(rawBody, headers, secret) {
  const eventId = headers["x-settlebolt-event-id"];
  const timestamp = headers["x-settlebolt-timestamp"];
  const sig = headers["x-settlebolt-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${eventId}.${rawBody}`)
    .digest("hex");
  return sig && sig.includes(`v1=${expected}`);
}

Request body:

{
  "type": "payment.confirmed",
  "created_at": "2026-07-03T12:00:00.000Z",
  "data": {
    "payment_id": "pay_...",
    "merchant_id": "merchant_...",
    "status": "confirmed",        // confirmed | underpaid | overpaid
    "chain": "base",
    "token": "USDC",
    "amount": "1200000000",       // raw on-chain units, as a string
    "amount_eur_cents": 120000,   // null for unmatched priced-native (ETH/BTC/SOL/TRX)
    "tx_hash": "0x...",
    "invoice_id": null,
    "payment_link_id": "pl_...",
    "payer_address": "0x...",
    "merchant_address": "0x...",
    "mode": "live"
  }
}

• Webhook endpoints must be public HTTPS URLs on port 443.
• Private, loopback, link-local, CGNAT, metadata, credentialed, IPv6 literal, and redirect-following webhook targets are rejected.
• Webhook delivery fetches use manual redirects and an 8 second timeout.
• Webhook secrets are encrypted at rest and the raw secret is only shown once.
• Payment recording validates chain, token, recipient wallet, and idempotency before crediting.
• Do not put dashboard session tokens, API keys, or webhook secrets in browser code.

Most errors return JSON with an error string and an appropriate HTTP status.

{ "error": "Unsupported chain or token" }