Settlements API

Create Lightning invoices and manage settlement status.

Create Settlement

Create a new Lightning invoice for settlement.

POST /api/payments

Request Headers

Header	Required	Description
X-API-Key	Yes	Your merchant API key
Content-Type	Yes	application/json

Request Body

{
  "orderId": "ORDER-12345",
  "amount": 49.99,
  "currency": "USD",
  "description": "Premium Subscription",
  "customerEmail": "customer@example.com",
  "metadata": {
    "productId": "prod_123",
    "userId": "user_456"
  }
}

Parameters

Field	Type	Required	Description
orderId	string	Yes	Your unique order identifier
amount	decimal	Yes	Settlement amount
currency	string	Yes	Currency code (USD, EUR, GBP, BTC)
description	string	No	Settlement description
customerEmail	string	No	Customer email for receipt
metadata	object	No	Custom key-value data

Response

{
  "invoiceId": "inv_abc123def456",
  "orderId": "ORDER-12345",
  "status": "unpaid",
  "amount": 49.99,
  "currency": "USD",
  "amountSats": 125000,
  "lightningInvoice": "lnbc1250000n1pnxyz...",
  "expiresAt": "2024-12-29T13:00:00Z",
  "createdAt": "2024-12-29T12:00:00Z"
}

Example

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"
  }'

Get Settlement by Invoice ID

Retrieve settlement details by Lightning Enable invoice ID.

GET /api/payments/{invoiceId}

Parameters

Parameter	Type	Description
invoiceId	string	Lightning Enable invoice ID

Response

{
  "invoiceId": "inv_abc123def456",
  "orderId": "ORDER-12345",
  "status": "paid",
  "amount": 49.99,
  "currency": "USD",
  "amountSats": 125000,
  "settledAt": "2024-12-29T12:05:00Z",
  "createdAt": "2024-12-29T12:00:00Z"
}

Example

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

Get Settlement by Order ID

Retrieve settlement details by your order ID.

GET /api/payments/order/{orderId}

Parameters

Parameter	Type	Description
orderId	string	Your order identifier

Response

Same as Get Settlement by Invoice ID.

Example

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

Sync Settlement Status

Force sync settlement status from OpenNode. Useful if webhook was delayed.

POST /api/payments/{invoiceId}/sync

Parameters

Parameter	Type	Description
invoiceId	string	Lightning Enable invoice ID

Response

Returns updated settlement object with current status.

Example

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

Settlement Statuses

Status	Description
unpaid	Invoice created, awaiting settlement
processing	Settlement detected, confirming
paid	Settlement confirmed
expired	Invoice expired without settlement
refunded	Settlement was refunded

Settlement Flow

1. Create Settlement
   POST /api/payments
   Returns: invoiceId, lightningInvoice

2. Present to Payer
   Show QR code or invoice string
   Payer settles with Lightning wallet

3. Settlement Confirmed
   Webhook notification sent
   Or poll GET /api/payments/{invoiceId}

4. Proceed
   When status = "paid", settlement is complete

Supported Currencies

Currency	Code	Notes
US Dollar	USD	Converted to BTC at current rate
Euro	EUR	Converted to BTC at current rate
British Pound	GBP	Converted to BTC at current rate
Bitcoin	BTC	Direct amount (use decimal, e.g., 0.001)
Satoshis	sats	Direct amount (integer)

Invoice Expiration

• Default expiration: 60 minutes
• After expiration, invoice cannot be settled
• Create new settlement request if expired

Error Responses

Invalid Amount

{
  "error": "Bad Request",
  "message": "Amount must be greater than 0",
  "code": "INVALID_AMOUNT"
}

Missing Order ID

{
  "error": "Bad Request",
  "message": "Order ID is required",
  "code": "MISSING_ORDER_ID"
}

Settlement Not Found

{
  "error": "Not Found",
  "message": "Settlement not found",
  "code": "SETTLEMENT_NOT_FOUND"
}

Code Examples

JavaScript

async function createSettlement(orderId, amount, currency) {
  const response = await fetch('https://api.lightningenable.com/api/payments', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.LIGHTNING_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ orderId, amount, currency })
  });

  if (!response.ok) {
    throw new Error(`Settlement failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const settlement = await createSettlement('ORDER-123', 49.99, 'USD');
console.log('Lightning Invoice:', settlement.lightningInvoice);

C#

public async Task<SettlementResponse> CreateSettlementAsync(
    string orderId,
    decimal amount,
    string currency)
{
    var request = new
    {
        orderId,
        amount,
        currency
    };

    var response = await _httpClient.PostAsJsonAsync("/api/payments", request);
    response.EnsureSuccessStatusCode();

    return await response.Content.ReadFromJsonAsync<SettlementResponse>();
}

Python

import requests

def create_settlement(order_id, amount, currency):
    response = requests.post(
        'https://api.lightningenable.com/api/payments',
        headers={
            'X-API-Key': os.environ['LIGHTNING_API_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'orderId': order_id,
            'amount': amount,
            'currency': currency
        }
    )
    response.raise_for_status()
    return response.json()

Next Steps

• Webhooks - Real-time settlement notifications
• Refunds - Process refunds
• Errors - Error handling