Skip to main content

Frequently Asked Questions

General​

What is Lightning Enable?​

Lightning Enable is payment enablement middleware that connects your platform to payment providers (Strike, OpenNode) for Bitcoin Lightning payments. We provide the API layer - your payment provider handles payment processing, custody, and settlement.

How is Lightning Enable different from a payment gateway?​

AspectTraditional GatewayLightning Enable
RoleProcesses paymentsAPI middleware
Fund custodyGateway holds fundsProvider holds funds
KYB/ComplianceGateway handlesProvider handles
SettlementGateway settlesProvider settles
Revenue modelPer-transaction feesSubscription only

Why do I need a payment provider account?​

Lightning Enable connects to a payment provider (Strike or OpenNode) that facilitates:

  • Bitcoin custody and settlement
  • KYB/KYC/AML compliance
  • Bank settlements (if desired)
  • Lightning Network infrastructure

Lightning Enable connects to your provider account to create invoices and receive payment notifications. Strike is the default and recommended for most merchants.

What is Lightning Enable's role in payment processing?​

Lightning Enable is API middleware software. We connect your platform to a payment provider (Strike or OpenNode). Lightning Enable does not:

  • Hold or custody funds (your provider does)
  • Process payments (your provider does)
  • Handle settlements (your provider does)

Your payment provider handles payment processing, custody, KYB/KYC, and settlement. Consult with legal counsel regarding your specific regulatory obligations.

Pricing​

How much does Lightning Enable cost?​

ProductPriceIncludes
Agentic Commerce — Individual$99/monthFull REST API + L402 protocol + Strike settlement
Kentico Commerce$249/monthFull REST API + Xperience by Kentico integration
Agentic Commerce — Business$299/monthFull REST API + pay-per-request API monetization

All plans include: webhook notifications, refund support, multi-currency pricing, and priority email support.

Are there transaction fees?​

Lightning Enable charges a flat subscription fee only — no per-transaction fees from us. Your payment provider may charge their own processing fees, which you pay directly to them.

Can I switch plans?​

Yes. Upgrade or downgrade anytime. Changes take effect immediately, with prorated billing.

Technical​

What programming languages are supported?​

Lightning Enable provides a REST API that works with any language. We have examples for:

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

Do you have an SDK?​

Official SDKs are coming soon. For now, use our REST API with your preferred HTTP client.

What's the API latency?​

Typical response times:

  • Create payment: 200-500ms
  • Get payment status: 50-100ms
  • Exchange rates: 50-100ms

Most latency comes from provider API calls (Strike or OpenNode).

Is there a sandbox environment?​

Yes. Both providers offer test environments:

Strike sandbox:

  • Dashboard: dashboard.dev.strike.me
  • API: api.dev.strike.me

OpenNode testnet:

  • Dashboard: app.dev.opennode.com
  • API: dev-api.opennode.com

No KYB/KYC required for test environments.

Payments​

How long do invoices last?​

Default: 60 minutes. After expiration, the invoice cannot be paid and you'll need to create a new one.

What currencies are supported?​

  • USD - US Dollar
  • EUR - Euro
  • GBP - British Pound
  • BTC - Bitcoin
  • sats - Satoshis

Fiat currencies are converted to Bitcoin at current rates.

How do refunds work?​

Since Lightning payments are instant and irreversible, refunds work differently depending on your provider:

OpenNode merchants: Native refund support via Lightning or on-chain withdrawal.

Strike merchants: Refunds are processed as new outgoing payments via payment-quotes (Lightning or on-chain).

Both methods require sufficient balance in your provider account.

What happens if a payment fails?​

Lightning payments either succeed instantly or fail immediately. If a customer's payment fails:

  • No funds are transferred
  • Invoice can be retried
  • Create a new invoice if expired

Webhooks​

How do I know when a payment is complete?​

Two options:

  1. Webhooks (recommended) - Receive instant notifications
  2. Polling - Check payment status via API

Webhooks are more efficient and provide real-time updates.

Are webhooks retried?​

Yes. If your endpoint fails, we retry up to 5 times with exponential backoff (1 min, 5 min, 30 min, 2 hours).

How do I verify webhooks?​

Webhooks include an HMAC-SHA256 signature in the X-LightningEnable-Signature header in the format t={timestamp},v1={hmac}. Verify by computing HMAC-SHA256 of {timestamp}.{payload} using your webhook secret, and reject signatures older than 5 minutes. See the Webhook Verification guide for code examples.

L402 Protocol​

What is L402?​

L402 is a protocol for HTTP 402 (Payment Required) that enables pay-per-request API access using Lightning payments. Perfect for:

  • AI API monetization
  • Premium content access
  • Metered API usage

Do I need L402?​

L402 is optional. Use it if you want:

  • Per-request payment instead of subscriptions
  • Anonymous API access without accounts
  • Micropayment monetization

Which plan includes L402?​

L402 server-side features (creating L402-protected endpoints for your API) are available on the Agentic Commerce — Individual ($99/month) and Agentic Commerce — Business ($299/month) plans. The Kentico Commerce ($249/mo) plan does NOT include L402 server-side support.

PlanL402 Server-SidePrice
Agentic Commerce — Individual✅ Yes$99/mo
Kentico Commerce❌ No$249/mo
Agentic Commerce — Business✅ Yes$299/mo

Note: The MCP server's L402 client tools (access_l402_resource, pay_l402_challenge) are free for everyone. The subscription is only needed to create L402-protected endpoints.

How do I check if my account has L402 enabled?​

Use the /api/merchant/l402-status endpoint:

curl https://api.lightningenable.com/api/merchant/l402-status \
  -H "X-API-Key: your-api-key"

Response shows l402Enabled: true if your plan includes L402 features.

Can I monetize third-party APIs?​

Yes. The L402 proxy feature lets you wrap any API with Lightning payments. You pay the upstream API, customers pay you.

Where is L402 used in production?​

store.lightningenable.com uses L402 payments for its Community Collection feature, where designers pay a Lightning micropayment to submit designs to the store. This demonstrates L402 as a gating mechanism for real-world commerce workflows.

MCP Server (AI Integration)​

What is the MCP server?​

The MCP (Model Context Protocol) server enables AI agents like Claude to automatically pay for L402-protected APIs using Lightning payments. It connects to your wallet and handles payments on behalf of the AI.

Are all MCP tools free?​

Yes! All MCP tools are completely free. No subscription or paid tier is required.

ToolDescription
pay_invoicePay any Lightning invoice
check_wallet_balanceCheck your wallet balance
get_payment_historyView recent payments
get_budget_statusView spending limits
access_l402_resourceAutomatically pay L402 challenges
pay_l402_challengeManual L402 payment handling

All tools work with any supported wallet configuration.

What is LIGHTNING_ENABLE_API_KEY?​

This environment variable is your merchant API key for the MCP server. It is used for license validation if you have an Agentic Commerce subscription, but it is not required to use any MCP tools. All tools including access_l402_resource and pay_l402_challenge are free.

{
  "mcpServers": {
    "lightning-enable": {
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://..."
      }
    }
  }
}

Just configure a wallet and all tools are available immediately.

Do I need a subscription to use MCP tools?​

No. All MCP tools are completely free, including access_l402_resource and pay_l402_challenge. You just need a configured wallet. The MCP server works independently of any Lightning Enable subscription plan.

What happened to the license purchase?​

Removed in v1.6.0. Previously, L402 tools (access_l402_resource, pay_l402_challenge) required a 6,000 sat license or $299/month subscription. All tools are now free with no license or API key required.

How do I test L402 payments?​

The Lightning Enable Store is a live L402-powered web store where AI agents can purchase physical merchandise. Ask Claude:

Buy me a Lightning Enable t-shirt from store.lightningenable.com

This demonstrates the full L402 flow: browse catalog, checkout (get 402), pay invoice, claim with L402 credential.

API Features​

What is the X-Idempotency-Key header and when should I use it?​

The X-Idempotency-Key header prevents duplicate operations when retrying requests. If a network failure occurs and you're unsure whether your request succeeded, resending with the same idempotency key returns the original response instead of creating a duplicate.

How it works:

  1. Generate a unique key (UUID recommended) and include it as X-Idempotency-Key: <your-key>
  2. If the request succeeds, the response is cached for 24 hours keyed to your merchant account
  3. Repeating the request with the same key returns the cached response with an X-Idempotency-Replayed: true header

Supported endpoints:

  • POST /api/payments (create payment)
  • POST /api/refunds (create refund)
  • POST /api/checkout/sessions (create checkout session)

Example:

curl -X POST https://api.lightningenable.com/api/payments \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10.00, "currency": "USD"}'

Rules:

  • Keys must be 256 characters or fewer
  • Keys are scoped per merchant, so different merchants can use the same key without conflict
  • Only successful responses (2xx) are cached
  • Use a new key for each distinct operation

How do I trace a request through logs?​

Every API request is assigned a correlation ID for end-to-end tracing. You can use this ID when contacting support to quickly locate your request in our logs.

How it works:

  • Send your own ID via the X-Correlation-Id request header, or the API generates one automatically
  • The same ID is returned in the X-Correlation-Id response header
  • All internal log entries for that request include the correlation ID

Example:

# Let the API generate one
curl -v https://api.lightningenable.com/api/payments \
  -H "X-API-Key: your-api-key"
# Response header: X-Correlation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6

# Or provide your own
curl -v https://api.lightningenable.com/api/payments \
  -H "X-API-Key: your-api-key" \
  -H "X-Correlation-Id: my-trace-id-12345"

If something goes wrong, include the correlation ID when contacting support for faster diagnosis.

Why am I getting a 429 Too Many Requests response?​

The API enforces rate limits to protect against abuse. If you exceed the limit, you'll receive a 429 Too Many Requests response.

Rate limits by operation type:

OperationLimitWindow
Global (all requests)100 requests1 minute
Payment/refund creation10 requests1 minute
Checkout session creation5 requests1 minute
Read operations (GET)200 requests1 minute
Write operations (updates)20 requests1 minute
Admin operations30 requests1 minute
Webhooks100 requests1 minute (sliding window)

Rate limits are partitioned by:

  • API key (if authenticated)
  • IP address (if unauthenticated)

How to handle 429 responses:

  1. Implement exponential backoff (wait 1s, 2s, 4s, etc.)
  2. Cache responses for repeated queries instead of re-requesting
  3. Use webhooks for payment status instead of polling
  4. Batch operations where possible

What are the L402 proxy size limits?​

The L402 reverse proxy enforces size limits on both request and response bodies to prevent abuse:

DirectionDefault Limit
Request body (client to proxy)1 MB (1,048,576 bytes)
Response body (target API to client)10 MB (10,485,760 bytes)
  • Request too large: Returns 413 Payload Too Large
  • Response too large: Returns 502 Bad Gateway

These limits apply to proxied API calls only. Standard Lightning Enable API endpoints are not affected.

What security protections does the L402 proxy have?​

The L402 proxy includes several security layers to protect both API providers and consumers:

SSRF (Server-Side Request Forgery) Protection:

  • Target URLs are validated at request time by resolving DNS and checking the resulting IP addresses
  • Requests to private/internal IP ranges are blocked: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fc00::/7, fe80::/10
  • Cloud metadata endpoints (e.g., 169.254.169.254) are blocked to prevent credential theft

Header Sanitization:

  • Sensitive hop-by-hop headers are stripped from forwarded requests (Authorization, Proxy-Authorization, Connection, etc.)
  • The proxy adds identification headers (X-L402-Proxy-Id, X-L402-Proxy) to proxied responses

Request Limits:

  • Request and response body size limits (see "What are the L402 proxy size limits?")
  • 30-second timeout for upstream API responses (returns 504 Gateway Timeout if exceeded)

Callback URL Validation:

  • Webhook callback URLs are validated against blocked hostnames (localhost, metadata services, Kubernetes internals)
  • Common internal service ports (Redis 6379, PostgreSQL 5432, MySQL 3306, etc.) are blocked

Error Sanitization:

  • In production, error responses are sanitized to remove stack traces, internal namespaces, file paths, and connection strings
  • Errors include a correlation ID for support reference without exposing implementation details

How does error sanitization work in production?​

In production, the API automatically strips internal details from error responses to prevent information leakage. Fields like stackTrace, innerException, and exceptionType are removed. Fields like message and details are replaced with a generic message if they contain references to internal namespaces, file paths, or database details.

Every error response includes a correlationId that you can reference when contacting support. In development environments, full error details (including stack traces) are returned for debugging convenience.

Security​

Is my API key secure?​

Yes. API keys are encrypted at rest using AES-256-GCM. They're only decrypted in memory during authentication.

Should I use HTTPS?​

Yes. Always use HTTPS in production. We require HTTPS for webhooks in production environments.

What if my API key is compromised?​

  1. Generate a new API key immediately
  2. Update your application configuration
  3. The old key is automatically invalidated
  4. Review your access logs

Kentico Commerce​

Which Kentico versions are supported?​

Lightning Enable supports Xperience by Kentico (version 29.0 and later).

How do I install the Kentico integration?​

  1. Install the NuGet package: LightningEnable.Kentico
  2. Configure in appsettings.json
  3. Register in Program.cs

See the Kentico Commerce documentation for details.

Does it work with Kentico Commerce?​

Yes. Lightning Enable implements IPaymentGateway and integrates directly with the checkout flow.

Troubleshooting​

Payments not working​

  1. Check API key - Is it valid and for the correct environment?
  2. Check provider - Is your payment provider account (Strike or OpenNode) active and verified?
  3. Check environment - Are you using sandbox/testnet for testing?
  4. Check logs - What error is returned?

Webhooks not received​

  1. Check URL - Is your webhook URL correct and HTTPS?
  2. Check firewall - Can external services reach your endpoint?
  3. Check logs - View webhook delivery logs
  4. Test manually - Use curl to test your endpoint

Invalid API key errors​

  1. Verify key is copied correctly (no extra spaces)
  2. Confirm environment matches (dev vs production)
  3. Check key hasn't been revoked
  4. Generate new key if needed

Rate limit exceeded​

  1. Implement request caching
  2. Use webhooks instead of polling
  3. Add exponential backoff
  4. Review the rate limits table in "Why am I getting a 429 Too Many Requests response?" for specific limits per endpoint

Support​

How do I get help?​

Is there an SLA?​

All plans include best-effort availability and priority email support. We do not currently offer formal SLA guarantees.

Where can I report bugs?​

Email support@lightningenable.com with:

  • Description of the issue
  • Steps to reproduce
  • Error messages/logs
  • Your environment details

Still Have Questions?​

If your question isn't answered here:

  1. Check the API Reference
  2. Review the Product Guides
  3. Email support@lightningenable.com

We're here to help you succeed with Lightning payments!