API Reference

The Lightning Enable API is a RESTful web service for integrating Bitcoin Lightning payments into your platform.

Base URL

https://api.lightningenable.com

Authentication

All API requests require authentication via the X-API-Key header:

curl -X GET https://api.lightningenable.com/api/payments \
  -H "X-API-Key: le_merchant_your-api-key"

See Authentication for details.

API Endpoints

Payments

Method	Endpoint	Description
POST	/api/payments	Create payment invoice
GET	/api/payments/{invoiceId}	Get payment by ID
GET	/api/payments/order/{orderId}	Get payment by order ID
POST	/api/payments/{invoiceId}/sync	Sync status from OpenNode

Refunds

Method	Endpoint	Description
POST	/api/refunds	Create refund
GET	/api/refunds/{refundId}	Get refund status
GET	/api/refunds	List all refunds
GET	/api/refunds/invoice/{invoiceId}	Get refunds for invoice

Exchange Rates

Method	Endpoint	Description
GET	/api/rates	Get current BTC exchange rates
GET	/api/rates/{currency}	Get rate for specific currency

L402 Protocol

Method	Endpoint	Description
GET	/api/l402/pricing	Get L402 endpoint pricing
GET	/api/l402/status	Check L402 auth status
*	/l402/proxy/{proxyId}/*	L402-protected proxy

Webhooks

Method	Endpoint	Description
POST	/api/webhooks/opennode	OpenNode webhook receiver

Merchant Settings (Self-Service)

Method	Endpoint	Description
GET	/api/merchant/me	Get account info and onboarding status
PUT	/api/merchant/opennode-key	Update OpenNode API key
PUT	/api/merchant/webhook-url	Update webhook URL
GET	/api/merchant/subscription	Get subscription details
POST	/api/merchant/validate-opennode	Validate OpenNode API key
GET	/api/merchant/quickstart	Get onboarding guide

Health Check

Method	Endpoint	Description
GET	/health	Structured health check (public, no auth required)

Admin (Requires Admin Key)

Method	Endpoint	Description
GET	/api/admin/merchants	List merchants
POST	/api/admin/merchants	Create merchant
GET	/api/admin/merchants/{id}	Get merchant
PUT	/api/admin/merchants/{id}	Update merchant

Request Format

Headers

Header	Required	Description
X-API-Key	Yes	Your merchant API key
Content-Type	Yes (POST/PUT)	application/json
X-Idempotency-Key	No	Prevents duplicate payments/refunds (UUID recommended)
X-Correlation-Id	No	Request tracing ID (auto-generated if not provided)

See Request Headers for full details on idempotency, correlation IDs, and API versioning.

Request Body

POST and PUT requests accept JSON bodies:

{
  "orderId": "ORDER-12345",
  "amount": 99.99,
  "currency": "USD"
}

Response Format

Success Response

{
  "invoiceId": "inv_abc123",
  "status": "unpaid",
  "amount": 99.99,
  "currency": "USD"
}

Error Response

{
  "error": "Bad Request",
  "message": "Amount is required",
  "code": "INVALID_REQUEST"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
402	Payment Required - L402 payment needed
403	Forbidden - Access denied
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Server Error

Pagination

List endpoints support pagination using skip and take parameters:

GET /api/refunds?skip=0&take=20

Parameter	Default	Description
skip	0	Number of records to skip
take	50	Number of records to return (max 100)

Example - get second page of 20 results:

GET /api/refunds?skip=20&take=20

Rate Limiting

Policy	Limit	Applied To
Global	100/min	All authenticated requests (per API key)
Read	200/min	GET operations
Payment Create	10/min	POST /api/payments, POST /api/refunds
Admin	30/min	/api/admin/* endpoints

See Rate Limiting for details.

SDKs and Libraries

Official SDKs (coming soon):

• .NET / C#
• JavaScript / TypeScript
• Python

Quick Examples

Create Payment

curl -X POST https://api.lightningenable.com/api/payments \
  -H "X-API-Key: le_merchant_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORDER-12345",
    "amount": 49.99,
    "currency": "USD",
    "description": "Premium Subscription"
  }'

Check Payment Status

curl https://api.lightningenable.com/api/payments/inv_abc123 \
  -H "X-API-Key: le_merchant_abc123"

Create Refund

curl -X POST https://api.lightningenable.com/api/refunds \
  -H "X-API-Key: le_merchant_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "inv_abc123",
    "amount": 49.99,
    "lightningInvoice": "lnbc499900n1p..."
  }'

Health Check Endpoint

The /health endpoint returns structured JSON describing the status of the API and its dependencies. It is public and does not require authentication, making it suitable for external monitoring and infrastructure health probes.

Request

curl https://api.lightningenable.com/health

Response

{
  "status": "Healthy",
  "totalDuration": 42.15,
  "checks": [
    {
      "name": "database",
      "status": "Healthy",
      "duration": 38.72,
      "description": null,
      "exception": null,
      "tags": ["db", "sql"]
    }
  ]
}

Response Fields

Field	Type	Description
status	string	Overall health: Healthy, Degraded, or Unhealthy
totalDuration	number	Total time to run all checks (milliseconds)
checks	array	Individual health check results
checks[].name	string	Name of the check (e.g., database)
checks[].status	string	Check result: Healthy, Degraded, or Unhealthy
checks[].duration	number	Time for this check (milliseconds)
checks[].description	string|null	Optional description from the check
checks[].exception	string|null	Error message if the check failed
checks[].tags	array	Tags for categorizing checks (e.g., ["db", "sql"])

HTTP Status Codes

Code	Meaning
200	All checks passed (Healthy)
503	One or more checks failed (Unhealthy)

Current Checks

Check	Tags	What It Verifies
database	db, sql	SQL Server connectivity via EF Core CanConnectAsync

Unhealthy Response Example

When the database is unreachable, the endpoint returns HTTP 503:

{
  "status": "Unhealthy",
  "totalDuration": 5023.41,
  "checks": [
    {
      "name": "database",
      "status": "Unhealthy",
      "duration": 5001.88,
      "description": null,
      "exception": "A network-related or instance-specific error occurred while establishing a connection to SQL Server.",
      "tags": ["db", "sql"]
    }
  ]
}

Using with Monitoring Tools

Azure App Service Health Probes:

Configure in the Azure portal under Monitoring > Health check:

• Path: /health
• The probe will automatically mark the instance as unhealthy after consecutive failures.

UptimeRobot / Pingdom / External Monitors:

Point your uptime monitor at:

https://api.lightningenable.com/health

• Alert on HTTP status code other than 200
• Recommended check interval: 1 minute
• Parse the JSON response to alert on specific check failures (e.g., checks[0].status != "Healthy")

curl Quick Check:

# Check overall status
curl -s https://api.lightningenable.com/health | jq '.status'

# Check database specifically
curl -s https://api.lightningenable.com/health | jq '.checks[] | select(.name == "database") | .status'

Next Steps

• Authentication - API key management
• Request Headers - Idempotency, correlation IDs, and API versioning
• Payments - Create and manage payments
• Webhooks - Real-time notifications
• Errors - Error handling