Payments API

Create Lightning invoices and manage payment status.

Create Payment

Create a new Lightning invoice for a customer payment.

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	Payment amount
currency	string	Yes	Currency code (USD, EUR, GBP, BTC)
description	string	No	Payment 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 Payment by Invoice ID

Retrieve payment 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,
  "paidAt": "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 Payment by Order ID

Retrieve payment details by your order ID.

GET /api/payments/order/{orderId}

Parameters

Parameter	Type	Description
orderId	string	Your order identifier

Response

Same as Get Payment by Invoice ID.

Example

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

Sync Payment Status

Force sync payment 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 payment object with current status.

Example

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

Payment Statuses

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

Payment Flow

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

2. Display to Customer
   Show QR code or invoice string
   Customer pays with Lightning wallet

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

4. Fulfill Order
   When status = "paid", deliver goods/services

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 paid
• Create new payment 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"
}

Payment Not Found

{
  "error": "Not Found",
  "message": "Payment not found",
  "code": "PAYMENT_NOT_FOUND"
}

Code Examples

JavaScript

async function createPayment(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(`Payment failed: ${response.statusText}`);
  }

  return response.json();
}

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

C#

public async Task<PaymentResponse> CreatePaymentAsync(
    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<PaymentResponse>();
}

Python

import requests

def create_payment(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 payment notifications
• Refunds - Process refunds
• Errors - Error handling