Settlement Flows
This section documents the technical flows for different settlement patterns.
Direct Settlement Flow
Standard settlement via the REST API.
┌─────────┐ ┌─────────────────┐ ┌──────────┐ ┌─────────┐
│ Client │ │ Lightning Enable│ │ OpenNode │ │Lightning│
└────┬────┘ └────────┬────────┘ └────┬─────┘ └────┬────┘
│ │ │ │
│ POST /settlements │ │ │
│───────────────────>│ │ │
│ │ Create charge │ │
│ │───────────────────>│ │
│ │ │ Invoice │
│ │<───────────────────│ │
│ Invoice + ID │ │ │
│<───────────────────│ │ │
│ │ │ │
│ [Client pays invoice via Lightning wallet] │
│ │ │ │
│ │ Webhook: paid │ │
│ │<───────────────────│ │
│ Webhook: settled │ │ │
│<───────────────────│ │ │
│ │ │ │
Endpoints
POST /api/settlements- Create settlement requestGET /api/settlements/{id}- Check settlement statusPOST /api/webhooks/opennode- Receive settlement confirmations
L402 Settlement Flow
Per-request settlement using HTTP 402 challenges.
┌─────────┐ ┌─────────────────┐ ┌──────────┐
│ Client │ │ Lightning Enable│ │ OpenNode │
└────┬────┘ └────────┬────────┘ └────┬─────┘
│ │ │
│ GET /resource │ │
│───────────────────>│ │
│ │ Create charge │
│ │───────────────────>│
│ │<───────────────────│
│ 402 + Invoice │ │
│<───────────────────│ │
│ │ │
│ [Client pays, receives preimage] │
│ │ │
│ GET /resource │ │
│ Auth: L402 token │ │
│───────────────────>│ │
│ │ Verify preimage │
│ 200 + Content │ │
│<───────────────────│ │
│ │ │
L402 Header Format
Request:
Authorization: L402 <macaroon>:<preimage>
Challenge response (402):
WWW-Authenticate: L402 macaroon="<base64>", invoice="<bolt11>"
Webhook Flow
Settlement confirmation via webhooks.
┌──────────┐ ┌─────────────────┐ ┌──────────┐
│ OpenNode │ │ Lightning Enable│ │ Your App │
└────┬─────┘ └────────┬────────┘ └────┬─────┘
│ │ │
│ POST /webhooks │ │
│ (settlement event) │ │
│────────────────────>│ │
│ │ Verify signature │
│ │ Update state │
│ │ │
│ │ POST /your-webhook │
│ │────────────────────>│
│ │ │ Process
│ │ 200 OK │
│ │<────────────────────│
│ 200 OK │ │
│<────────────────────│ │
│ │ │
Webhook Signature Verification
X-LightningEnable-Signature: t={unix_timestamp},v1={hmac_sha256_hex}
Verify by computing HMAC-SHA256 of {timestamp}.{payload} using your webhook secret. Reject signatures older than 5 minutes. See Webhook Verification for full details and code examples.
Settlement States
| State | Description | Terminal |
|---|---|---|
unpaid | Invoice created, awaiting settlement | No |
processing | Settlement detected, confirming | No |
paid | Settlement complete | Yes |
expired | Invoice expired | Yes |
Further Reading
- API Reference - Complete API documentation
- Webhooks - Webhook implementation details
- L402 Protocol - L402 technical details