Skip to main content

Quick Start Guide

Get up and running with Lightning Enable in under 10 minutes. This guide walks you through creating your first Lightning Network payment.

OpenNode KYC Required

Before accepting real payments, you must complete OpenNode KYC verification. For testing, use OpenNode's testnet environment at dev.opennode.com.

Prerequisites​

Before you begin, ensure you have:

  1. OpenNode Account with API key

  2. Lightning Enable Subscription with your API key

  3. HTTP Client - curl, Postman, or any programming language

Step 1: Test Authentication​

Verify your API key works by calling the health endpoint:

curl -X GET https://api.lightningenable.com/health \
  -H "X-API-Key: your-api-key-here"

Expected Response:

{
  "status": "healthy",
  "timestamp": "2024-12-29T12:00:00Z"
}

Step 2: Configure Your OpenNode Key​

Your Lightning Enable account needs your OpenNode API key to create payments. This is configured during signup or via the admin API:

curl -X PUT https://api.lightningenable.com/api/admin/merchants/{merchantId} \
  -H "X-API-Key: admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "openNodeApiKey": "your-opennode-api-key",
    "callbackUrl": "https://yourapp.com/webhooks/lightning"
  }'
note

The admin API key is different from your merchant API key. Contact support if you need admin access.

Step 3: Create Your First Payment​

Create a Lightning invoice for a customer purchase:

curl -X POST https://api.lightningenable.com/api/payments \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORDER-12345",
    "amount": 25.00,
    "currency": "USD",
    "description": "Premium Widget",
    "customerEmail": "customer@example.com",
    "successUrl": "https://yourapp.com/order/success"
  }'

Response:

{
  "invoiceId": "inv_abc123def456",
  "openNodeChargeId": "charge_xyz789",
  "status": "unpaid",
  "amount": 25.00,
  "currency": "USD",
  "lightningInvoice": "lnbc250000n1p...",
  "onchainAddress": "bc1q...",
  "hostedCheckoutUrl": "https://checkout.opennode.com/charge_xyz789",
  "createdAt": "2024-12-29T12:00:00Z",
  "expiresAt": "2024-12-29T12:15:00Z"
}

Step 4: Display Payment Options​

You have three options for accepting payment:

Option A: Hosted Checkout (Easiest)​

Redirect the customer to OpenNode's hosted checkout page:

// JavaScript
window.location.href = response.hostedCheckoutUrl;
// C# / ASP.NET Core
return Redirect(response.HostedCheckoutUrl);

Option B: Lightning Invoice (QR Code)​

Display the Lightning invoice as a QR code:

<div id="qr-code"></div>
<script src="https://cdn.jsdelivr.net/npm/qrcode@1.5.3/build/qrcode.min.js"></script>
<script>
  QRCode.toCanvas(
    document.getElementById('qr-code'),
    'lnbc250000n1p...',  // lightningInvoice from response
    { width: 256 }
  );
</script>

Option C: On-Chain Bitcoin Address​

Display the Bitcoin address for on-chain payment (slower, higher fees):

<p>Send Bitcoin to: <code>bc1q...</code></p>

Step 5: Check Payment Status​

Poll the payment status endpoint:

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

Response (Unpaid):

{
  "invoiceId": "inv_abc123def456",
  "orderId": "ORDER-12345",
  "status": "unpaid",
  "amount": 25.00,
  "currency": "USD",
  "paidAt": null
}

Response (Paid):

{
  "invoiceId": "inv_abc123def456",
  "orderId": "ORDER-12345",
  "status": "paid",
  "amount": 25.00,
  "currency": "USD",
  "paidAt": "2024-12-29T12:03:45Z"
}

Instead of polling, configure webhooks for instant payment notifications:

Webhook Payload:

{
  "invoiceId": "inv_abc123def456",
  "orderId": "ORDER-12345",
  "status": "paid",
  "amount": 25.00,
  "currency": "USD",
  "paidAt": "2024-12-29T12:03:45Z"
}

Verify Webhook Signature:

using System.Security.Cryptography;
using System.Text;

public bool VerifyWebhookSignature(string payload, string signature, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var computedSignature = Convert.ToHexString(hash).ToLowerInvariant();
    return signature == computedSignature;
}

Payment Status Flow​

+---------+    Customer pays    +------------+    Confirmed    +------+
| unpaid  |-------------------->| processing |---------------->| paid |
+---------+                     +------------+                 +------+
     |
     | 15 min timeout
     v
+---------+
| expired |
+---------+

Status Codes:

StatusDescription
unpaidInvoice created, awaiting payment
processingPayment detected, confirming
paidPayment confirmed, fulfill order
expiredInvoice expired without payment
underpaidInsufficient amount received

Complete Example: Node.js​

const axios = require('axios');

const API_URL = 'https://api.lightningenable.com';
const API_KEY = 'your-api-key-here';

async function createPayment() {
  // Create payment
  const response = await axios.post(
    `${API_URL}/api/payments`,
    {
      orderId: `ORDER-${Date.now()}`,
      amount: 25.00,
      currency: 'USD',
      description: 'Premium Widget',
      successUrl: 'https://yourapp.com/order/success'
    },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Checkout URL:', response.data.hostedCheckoutUrl);
  return response.data;
}

createPayment();

Complete Example: C#​

using System.Net.Http;
using System.Net.Http.Json;

public class LightningEnableClient
{
    private readonly HttpClient _httpClient;
    private const string ApiUrl = "https://api.lightningenable.com";

    public LightningEnableClient(string apiKey)
    {
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("X-API-Key", apiKey);
    }

    public async Task<CreatePaymentResponse> CreatePaymentAsync(
        string orderId,
        decimal amount,
        string description)
    {
        var request = new
        {
            orderId,
            amount,
            currency = "USD",
            description
        };

        var response = await _httpClient.PostAsJsonAsync(
            $"{ApiUrl}/api/payments",
            request
        );

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

Troubleshooting​

Problem: 401 Unauthorized response

Solution: Check that your API key is correct and included in the X-API-Key header.

Problem: 400 Bad Request - Merchant OpenNode API key not configured

Solution: Configure your OpenNode API key in Lightning Enable settings.

Problem: Payment stuck in unpaid status

Solution:

  • Check invoice hasn't expired (15 minute default)
  • Verify the Lightning invoice or Bitcoin address
  • Test with OpenNode testnet first

Next Steps​