Settlement Flows

This section documents the technical flows for different settlement patterns.

Direct Settlement Flow

Standard settlement via the REST API.

┌─────────┐      ┌─────────────────┐      ┌──────────┐      ┌─────────┐
│ Client  │      │ Lightning Enable│      │ Provider │      │Lightning│
└────┬────┘      └────────┬────────┘      └────┬─────┘      └────┬────┘
     │                    │                    │                 │
     │ POST /api/payments │                    │                 │
     │───────────────────>│                    │                 │
     │                    │ Create charge      │                 │
     │                    │───────────────────>│                 │
     │                    │                    │ Invoice         │
     │                    │<───────────────────│                 │
     │  Invoice + ID      │                    │                 │
     │<───────────────────│                    │                 │
     │                    │                    │                 │
     │        [Client pays invoice via Lightning wallet]         │
     │                    │                    │                 │
     │                    │   Webhook: paid    │                 │
     │                    │<───────────────────│                 │
     │ Webhook: settled   │                    │                 │
     │<───────────────────│                    │                 │
     │                    │                    │                 │

Endpoints

Settlements ride on the Payments API — there is no separate settlements endpoint:

POST /api/payments - Create an invoice (a settlement request)
GET /api/payments/{invoiceId} - Check settlement status
POST /api/payments/{invoiceId}/sync - Force a status sync from your payment provider
POST /api/webhooks/strike / POST /api/webhooks/opennode - Where your payment provider notifies Lightning Enable; Lightning Enable then forwards a signed webhook to your callback URL

L402 Settlement Flow

Per-request settlement using HTTP 402 challenges.

┌─────────┐      ┌─────────────────┐      ┌──────────┐
│ Client  │      │ Lightning Enable│      │ Provider │
└────┬────┘      └────────┬────────┘      └────┬─────┘
     │                    │                    │
     │ 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.

┌──────────┐      ┌─────────────────┐      ┌──────────┐
│ Provider │      │ 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
`refunded`	Settlement was refunded	Yes

These are the same status values returned by the Payments API and forwarded in webhooks.

Direct Settlement Flow​

Endpoints​

L402 Settlement Flow​

L402 Header Format​

Webhook Flow​

Webhook Signature Verification​

Settlement States​

Further Reading​