Request Headers
Lightning Enable uses these HTTP headers for authentication, idempotency, request tracing, and versioning.
Header Summary
| Header | Direction | Required | Description |
|---|---|---|---|
X-API-Key | Request | Yes | Merchant API key |
X-Idempotency-Key | Request | No | Prevents duplicate operations on payment endpoints |
Idempotency-Key | Request | No | Standard spelling, accepted on POST /api/l402/challenges — see L402 challenge idempotency |
X-Correlation-Id | Request & Response | No | Distributed tracing identifier |
X-API-Version | Response | -- | API version running on the server |
X-API-Deprecation | Response | -- | Deprecation notice (reserved for future use) |
X-Idempotency-Replayed | Response | -- | Indicates a replayed idempotent response was returned |
X-Total-Count | Response | -- | Total rows matching a paged listing, ignoring paging |
Retry-After | Response | -- | Seconds to wait before retrying, on 429 and some 503 responses |
X-Idempotency-Key
Use the X-Idempotency-Key header to safely retry payment and refund requests without creating duplicates. If you send the same idempotency key twice, the API returns the original cached response instead of processing the request again.
How It Works
- Generate a unique key (UUID recommended) on the client side.
- Include it as
X-Idempotency-Keyin your request. - If the request succeeds (2xx), the response is cached for 24 hours keyed by your merchant ID + idempotency key.
- If you retry with the same key within 24 hours, the cached response is returned immediately with the header
X-Idempotency-Replayed: true.
Supported Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/payments | POST | Create payment invoice |
/api/refunds | POST | Create refund |
/api/checkout/sessions | POST | Create checkout session |
Constraints
- Maximum key length: 256 characters
- Keys are scoped per merchant (two different merchants can use the same key without conflict)
- Only successful responses (2xx) are cached. If the request fails, you can safely retry with the same key.
- Cached responses expire after 24 hours
- The cache lives in server memory, so a deploy or restart clears it. Use a unique
orderIdas well: a secondPOST /api/paymentswith the sameorderIdis refused with400whatever the header says.
Example
# First request - creates the payment
curl -X POST https://api.lightningenable.com/api/payments \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Idempotency-Key: order-12345-attempt-1" \
-H "Content-Type: application/json" \
-d '{
"orderId": "ORDER-12345",
"amount": 49.99,
"currency": "USD"
}'
# Response: 201 Created { "invoiceId": "1042", ... }
# Retry with same key - returns cached response
curl -X POST https://api.lightningenable.com/api/payments \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Idempotency-Key: order-12345-attempt-1" \
-H "Content-Type: application/json" \
-d '{
"orderId": "ORDER-12345",
"amount": 49.99,
"currency": "USD"
}'
# Response: 201 Created { "invoiceId": "1042", ... }
# Response header: X-Idempotency-Replayed: true
Error Responses
| Scenario | Status | Response |
|---|---|---|
| Key exceeds 256 characters | 400 Bad Request | { "error": "Idempotency key must not exceed 256 characters." } |
Best Practices
- Derive the key from the operation, for example
{orderId}-create, so every retry of that operation reuses it. Use a new key for each distinct operation. - Retry network errors with the same key. You get either the cached result or a first-time run.
L402 challenge idempotency
POST /api/l402/challenges has its own idempotency, and it works differently from the response cache above — it is anchored on the minted challenge rather than on a cached HTTP response, so a retry gets back the same invoice, not a replayed response body that may no longer be payable.
| Payment endpoints | POST /api/l402/challenges | |
|---|---|---|
| Header | X-Idempotency-Key | Idempotency-Key (or X-Idempotency-Key) |
| Max key length | 256 characters | 200 characters |
| Over-long key | 400 | 400 |
| What is replayed | The cached 2xx response | The minted challenge itself — same invoice, macaroon, and payment hash |
| Window | 24 hours | The life of the invoice (10 minutes by default) |
| Survives a restart | No (process cache) | Yes (stored on the challenge) |
| Same key, different body | Cached response returned | 409 if the resource or price differs and the invoice is still live; a fresh mint once it has expired |
The key can also be sent as an idempotencyKey body field. Replays carry X-Idempotency-Replayed: true.
Full rules: Producer API Reference → Idempotency.
X-Correlation-Id
The X-Correlation-Id header enables distributed request tracing across your systems and the Lightning Enable API.
How It Works
- If you send an
X-Correlation-Idheader with your request, the API uses your value throughout the request lifecycle. - If you do not send one, the API generates a new UUID automatically.
- The correlation ID is always returned in the response
X-Correlation-Idheader. - The same ID appears in the
correlationIdfield of error responses for unhandled exceptions. - All server-side log entries for the request include this ID.
Example
# Send your own correlation ID
curl -X GET https://api.lightningenable.com/api/payments/1042 \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Correlation-Id: my-trace-id-12345"
# Response headers include:
# X-Correlation-Id: my-trace-id-12345
# Let the API generate one
curl -X GET https://api.lightningenable.com/api/payments/1042 \
-H "X-API-Key: YOUR_API_KEY"
# Response headers include:
# X-Correlation-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Log the correlation ID on your side and include it when you contact support.
X-API-Version
Every API response includes an X-API-Version header indicating the version of the Lightning Enable API that served the request.
HTTP/1.1 200 OK
X-API-Version: 1.0.0
Usage
- Use this header to verify which API version you are communicating with.
- The version follows semantic versioning (major.minor.patch).
- Breaking changes will increment the major version.
X-API-Deprecation (Reserved)
The X-API-Deprecation response header is reserved for future use. When an endpoint or API version is deprecated, this header will contain a human-readable deprecation notice with a migration deadline. Currently, no endpoints are deprecated.
Next Steps
- Authentication - API key setup
- Errors - Error handling and correlation IDs
- Rate Limiting - Rate limits and
Retry-After