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 or admin API key
X-Idempotency-KeyRequestNoPrevents duplicate operations on payment endpoints
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 cached idempotency response was returned

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.

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​