LN Merchant
Get Started

API Documentation

Everything you need to accept Bitcoin Lightning and USDC payments.

Base URL: https://api.lnmerchant.com REST API JSON

Quickstart

Accept your first payment in under 5 minutes.

1

Create an account and connect your wallet

Sign up at the dashboard, add your Lightning NWC URI and/or Solana address.

2

Get your API key

Your API key is shown once when you create a merchant wallet. Store it securely.

3

Create a payment

One API call creates a payment. Redirect customers to the hosted checkout page.

curl -X POST https://api.lnmerchant.com/payments \
  -H "Authorization: Bearer lps_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDC",
    "amountCents": 2500,
    "description": "Tee time — Pebble Beach"
  }'

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer lps_your_api_key_here

Your API key is shown once when you create a merchant wallet in the dashboard. Store it in an environment variable — never commit it to code.

Create a Payment

Create a payment in either BTC or USDC. Specify the amount in USD cents — we handle rate conversion for BTC.

POST /payments

Request Body

Field Type Description
currency string "BTC" or "USDC"
amountCents integer Amount in USD cents (e.g. 2500 = $25.00)
amountSats integer BTC only — exact amount in satoshis (alternative to amountCents)
type string BTC only — "one_time" (default) or "hold"
description string Optional. Shown on checkout page.

BTC Response

{
  "id": "abc-123",
  "currency": "BTC",
  "invoice": "lnbc...",
  "amountSats": 26315,
  "amountCents": 2500,
  "amountUsd": "25.00",
  "btcPriceUsd": 95000,
  "status": "pending"
}

USDC Response

{
  "id": "def-456",
  "currency": "USDC",
  "paymentUrl": "solana:7xK...",
  "destinationAddress": "7xK...",
  "amountUsdc": "25.00",
  "amountCents": 2500,
  "status": "pending"
}

Hosted Checkout

After creating a payment, redirect the customer to the hosted checkout page. It shows the QR code, detects payment, and displays a success screen.

https://pay.lnmerchant.com/checkout/{payment.id}

The checkout page handles both BTC (Lightning QR) and USDC (Solana Pay QR) automatically based on the payment currency. It polls for settlement every 3 seconds.

Payment Status

GET /payments/:id

Returns the current status and all payment details.

Status Values

pending held captured settled cancelled refunded failed

Auth & Capture

BTC only. Lock funds first, then capture after completing an action. Perfect for bookings and reservations.

Step 1: Create hold

POST /payments
{ "currency": "BTC", "amountCents": 6000, "type": "hold" }

Step 2: Capture or Cancel

// Capture — take the funds
POST /payments/:id/capture → { "status": "captured" }

// Cancel — release back to customer
POST /payments/:id/cancel → { "status": "cancelled" }

Auth/capture is BTC-only (Lightning hold invoices). USDC payments settle immediately on-chain.

Price Lookup

GET /payments/price?amountCents=2500 
{
  "btcPriceUsd": 95000.50,
  "amountCents": 2500,
  "amountUsd": "25.00",
  "amountSats": 26315
}

Rate is cached for 60 seconds. Source: Coinbase spot price with CoinGecko fallback.

Webhooks

Configure a webhook URL in your dashboard. We'll POST to it when payment events occur.

Events

payment.settled payment.captured 
// POST to your webhook URL
// Headers: X-Webhook-Signature, X-Webhook-Event
{
  "event": "payment.settled",
  "paymentId": "abc-123",
  "currency": "USDC",
  "amountSats": 0,
  "amountCents": 2500,
  "status": "settled",
  "timestamp": "2026-04-28T14:30:00Z"
}

Webhooks are signed with HMAC-SHA256 via the X-Webhook-Signature header. Retries 3 times with exponential backoff on failure.

Subscriptions

POST /subscriptions 
{
  "customerId": "cust-id",
  "amountSats": 50000,
  "intervalDays": 30,
  "description": "Pro Membership"
}

The billing job auto-pulls from the customer's Lightning wallet each cycle via NWC. Failed pulls retry 3 times before marking the subscription as past due.

Manage subscriptions: DELETE /subscriptions/:id (cancel), POST /subscriptions/:id/pause, POST /subscriptions/:id/resume

Refunds

POST /payments/:id/refund 
{
  "amountSats": 5000,
  "reason": "Customer cancelled"
}

BTC refunds are automatic — we create a reverse Lightning invoice on the customer's wallet and pay it from the merchant's wallet. Cost: only routing fees (~$0.001). USDC refunds create a pending record for manual processing.

Ready to integrate?

Get your API key and start accepting payments in minutes.

Get Early Access