Skip to main content

Testing Your Integration

This guide walks you through testing your Lightning Enable integration using OpenNode's development environment.

Testing Environments​

Development (Testnet)​

SettingValue
OpenNode Dashboardapp.dev.opennode.com
API Base URLhttps://dev-api.opennode.com/v1/
Lightning Enable EnvOpenNode:Environment = "dev"
Bitcoin NetworkTestnet
KYC RequiredNo

Production (Mainnet)​

SettingValue
OpenNode Dashboardapp.opennode.com
API Base URLhttps://api.opennode.com/v1/
Lightning Enable EnvOpenNode:Environment = "production"
Bitcoin NetworkMainnet
KYC RequiredYes

Setup Test Environment​

Step 1: Create Development Account​

  1. Visit app.dev.opennode.com
  2. Sign up with email
  3. Verify email
  4. No KYC required for testnet

Step 2: Generate Development API Key​

  1. Go to Integrations > API Keys
  2. Click Generate New Key
  3. Select Admin (for full testing capabilities)
  4. Copy and save the key

Step 3: Configure Lightning Enable​

{
  "OpenNode": {
    "Environment": "dev",
    "ApiKey": "your-dev-api-key"
  }
}

Or via environment variable:

OPENNODE_ENVIRONMENT=dev
OPENNODE_API_KEY=your-dev-api-key

Get Testnet Bitcoin​

You need testnet Bitcoin to pay test invoices.

Testnet Faucets​

Get free testnet Bitcoin from:

Testnet Lightning Wallets​

Use these wallets for testnet Lightning:

WalletPlatformNotes
PolarDesktopLocal Lightning network for devs
ThunderHubWebSelf-hosted node management
ZeusMobileConnect to your testnet node

Test Payment Flow​

Create Test Payment​

curl -X POST http://localhost:5096/api/payments \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "TEST-001",
    "amount": 1.00,
    "currency": "USD",
    "description": "Test payment"
  }'

Response:

{
  "invoiceId": "inv_test123",
  "orderId": "TEST-001",
  "status": "unpaid",
  "lightningInvoice": "lntb10u1p...",
  "amountSats": 2500
}

Pay Test Invoice​

  1. Copy the lightningInvoice value
  2. Open your testnet Lightning wallet
  3. Paste or scan the invoice
  4. Confirm payment

Verify Payment​

Check payment status:

curl http://localhost:5096/api/payments/inv_test123 \
  -H "X-API-Key: your-merchant-api-key"

Response after payment:

{
  "invoiceId": "inv_test123",
  "orderId": "TEST-001",
  "status": "paid",
  "paidAt": "2024-12-29T12:05:00Z"
}

Test Webhooks​

Local Webhook Testing​

Use ngrok to receive webhooks locally:

# Terminal 1: Start your server
dotnet run  # or npm start

# Terminal 2: Start ngrok
ngrok http 5096

Configure ngrok URL as webhook endpoint:

curl -X PUT http://localhost:5096/api/admin/merchants/1 \
  -H "X-API-Key: admin-api-key" \
  -d '{
    "webhookUrl": "https://abc123.ngrok.io/webhooks/lightning"
  }'

Verify Webhook Received​

After a test payment, check your server logs for:

POST /webhooks/lightning
{
  "event": "payment.completed",
  "data": {
    "invoiceId": "inv_test123",
    "status": "paid"
  }
}

Test Refunds​

Create Refund​

First, generate a testnet Lightning invoice from your wallet, then:

curl -X POST http://localhost:5096/api/refunds \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "inv_test123",
    "amount": 1.00,
    "currency": "USD",
    "lightningInvoice": "lntb..."
  }'

Verify Refund​

curl http://localhost:5096/api/refunds/ref_xyz123 \
  -H "X-API-Key: your-merchant-api-key"

Test L402 (Optional)​

Create L402 Proxy​

curl -X POST http://localhost:5096/api/proxy \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test API",
    "targetBaseUrl": "https://httpbin.org",
    "defaultPriceSats": 10
  }'

Test L402 Flow​

# Get 402 challenge
curl http://localhost:5096/l402/proxy/test-api/get

# Pay the invoice from response
# ...

# Access with L402 credential
curl http://localhost:5096/l402/proxy/test-api/get \
  -H "Authorization: L402 <macaroon>:<preimage>"

Testing Checklist​

Basic Integration​

  • Create payment successfully
  • Receive Lightning invoice
  • Pay invoice with testnet wallet
  • Status updates to "paid"
  • Webhook received

Webhook Integration​

  • Webhook endpoint accessible
  • Signature verification works
  • Events processed correctly
  • Duplicate handling works

Error Handling​

  • Invalid API key returns 401
  • Invalid request returns 400
  • Not found returns 404
  • Errors have proper format

Refunds (if applicable)​

  • Create refund successfully
  • Refund received in wallet
  • Webhook notification sent

Common Test Scenarios​

Test Expired Invoice​

// Create invoice with short expiry
const payment = await createPayment({
  orderId: 'TEST-EXPIRE',
  amount: 1.00,
  currency: 'USD'
});

// Wait for expiration (default 60 minutes)
// Or check status after expiry
const status = await getPayment(payment.invoiceId);
// status.status === 'expired'

Test Multiple Payments​

// Create multiple payments
const orders = ['ORDER-1', 'ORDER-2', 'ORDER-3'];

for (const orderId of orders) {
  const payment = await createPayment({ orderId, amount: 1.00, currency: 'USD' });
  console.log(`Created: ${payment.invoiceId}`);
}

Test Partial Refund​

// Original payment: $10
const payment = await createPayment({
  orderId: 'ORDER-PARTIAL',
  amount: 10.00,
  currency: 'USD'
});

// Pay the invoice...

// Partial refund: $3
const refund1 = await createRefund({
  invoiceId: payment.invoiceId,
  amount: 3.00,
  currency: 'USD',
  lightningInvoice: 'lntb...'
});

// Another partial refund: $5
const refund2 = await createRefund({
  invoiceId: payment.invoiceId,
  amount: 5.00,
  currency: 'USD',
  lightningInvoice: 'lntb...'
});

Debugging​

Check API Logs​

# View application logs
tail -f logs/lightning-enable-*.txt

Check OpenNode Dashboard​

  1. Log in to app.dev.opennode.com
  2. Go to Transactions
  3. Find your test payments
  4. View status and details

Verify Webhook Delivery​

# Check webhook logs
curl http://localhost:5096/api/webhooks/logs \
  -H "X-API-Key: admin-api-key"

Moving to Production​

After successful testing:

  1. Complete KYC on OpenNode (if not done)
  2. Generate production API key from app.opennode.com
  3. Update configuration to use production environment
  4. Update webhook URL to production endpoint
  5. Test with small real payment
  6. Monitor initial transactions

Production Configuration​

{
  "OpenNode": {
    "Environment": "production",
    "ApiKey": "your-production-api-key"
  }
}
warning

Test with a small amount first in production to verify everything works with real Bitcoin.

Next Steps​