Skip to main content

Request Headers

Lightning Enable uses several custom 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

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

Example​

# First request - creates the payment
curl -X POST https://api.lightningenable.com/api/payments \
  -H "X-API-Key: le_merchant_abc123" \
  -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": "inv_abc123", ... }

# Retry with same key - returns cached response
curl -X POST https://api.lightningenable.com/api/payments \
  -H "X-API-Key: le_merchant_abc123" \
  -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": "inv_abc123", ... }
# 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​

  1. Use UUIDs or deterministic keys. A UUID per request attempt works well. Alternatively, use a deterministic key like {orderId}-{action} so retries naturally reuse the same key.
  2. Do not reuse keys across different operations. Each logically distinct operation should have its own key.
  3. Always retry on network errors. If you never received a response, it is safe to retry with the same idempotency key -- you will either get the cached result or the request will process for the first time.

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/inv_abc123 \
  -H "X-API-Key: le_merchant_abc123" \
  -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/inv_abc123 \
  -H "X-API-Key: le_merchant_abc123"

# Response headers include:
# X-Correlation-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Best Practices​

  1. Generate a unique correlation ID per request in your client and include it in every API call.
  2. Log the correlation ID on your side so you can cross-reference with Lightning Enable logs if you contact support.
  3. Pass correlation IDs through your own microservices to enable end-to-end tracing.

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​