Skip to main content

Request Headers

Lightning Enable uses these HTTP headers for authentication, idempotency, request tracing, and versioning.

Header Summary​

HeaderDirectionRequiredDescription
X-API-KeyRequestYesMerchant API key
X-Idempotency-KeyRequestNoPrevents duplicate operations on payment endpoints
Idempotency-KeyRequestNoStandard spelling, accepted on POST /api/l402/challenges — see L402 challenge idempotency
X-Correlation-IdRequest & ResponseNoDistributed tracing identifier
X-API-VersionResponse--API version running on the server
X-API-DeprecationResponse--Deprecation notice (reserved for future use)
X-Idempotency-ReplayedResponse--Indicates a replayed idempotent response was returned
X-Total-CountResponse--Total rows matching a paged listing, ignoring paging
Retry-AfterResponse--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​

  1. Generate a unique key (UUID recommended) on the client side.
  2. Include it as X-Idempotency-Key in your request.
  3. If the request succeeds (2xx), the response is cached for 24 hours keyed by your merchant ID + idempotency key.
  4. 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​

EndpointMethodDescription
/api/paymentsPOSTCreate payment invoice
/api/refundsPOSTCreate refund
/api/checkout/sessionsPOSTCreate 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 orderId as well: a second POST /api/payments with the same orderId is refused with 400 whatever 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​

ScenarioStatusResponse
Key exceeds 256 characters400 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 endpointsPOST /api/l402/challenges
HeaderX-Idempotency-KeyIdempotency-Key (or X-Idempotency-Key)
Max key length256 characters200 characters
Over-long key400400
What is replayedThe cached 2xx responseThe minted challenge itself — same invoice, macaroon, and payment hash
Window24 hoursThe life of the invoice (10 minutes by default)
Survives a restartNo (process cache)Yes (stored on the challenge)
Same key, different bodyCached response returned409 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-Id header 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-Id header.
  • The same ID appears in the correlationId field 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​