Receive Bitcoin via Lightning

Receive Bitcoin over the Lightning Network into your Neutron wallet. Creates a Bolt11 invoice that the sender pays — settlement is instant.

Overview

Sender  ──Lightning──►  Neutron  ──►  Your Neutron Wallet

Use case: Accepting Lightning payments in your app, generating invoices for customers, or receiving peer-to-peer transfers.

📘

Lightning Address: Your account also has a Lightning Address (e.g., [email protected]) that others can pay directly — no invoice generation needed. This page covers the programmatic invoice flow.

Flow

1. Create the transaction — reserves the quote
2. Confirm the transaction — generates the Bolt11 invoice
3. Share the invoice with the sender (string or QR code)
4. Sender pays — settlement is instant
5. Receive webhook notification when complete (if configured)

Step 1: Create Transaction

curl -X POST https://api.neutron.me/api/v2/transaction \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "sourceReq": {
      "ccy": "BTC",
      "method": "lightning",
      "reqDetails": {}
    },
    "destReq": {
      "ccy": "BTC",
      "method": "neutronpay",
      "amtRequested": 0.0001,
      "reqDetails": {}
    }
  }'

Request Fields

⚠️

Amounts are in BTC, not satoshis. 0.00000100 = 100 sats.

⚠️

Set the amount on one side only (source OR dest), not both.

Response

{
  "txnId": "e3db46cb-6b3f-47f7-ba62-aef7cd35b24d",
  "accountId": "ne01-abc123def456",
  "txnState": "quoted",
  "sourceReq": {
    "ccy": "BTC",
    "method": "lightning",
    "amtRequested": 0.0001,
    "reqStatus": "0",
    "reqDetails": {
      "paymentRequest": null,
      "invoicePageUrl": null
    }
  },
  "destReq": {
    "ccy": "BTC",
    "method": "neutronpay",
    "amtRequested": 0.0001,
    "reqStatus": "0"
  },
  "fxRate": 1,
  "createdAt": 1770342000000
}

📘

The invoice is not generated yet at this stage — paymentRequest and invoicePageUrl are null. You must confirm the transaction first.

Step 2: Confirm Transaction

Confirm to generate and activate the invoice:

curl -X PUT https://api.neutron.me/api/v2/transaction/e3db46cb-6b3f-47f7-ba62-aef7cd35b24d/confirm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⚠️

The Content-Type: application/json header is required on PUT requests, even with no request body.

Response

{
  "txnId": "e3db46cb-6b3f-47f7-ba62-aef7cd35b24d",
  "accountId": "ne01-abc123def456",
  "txnState": "srccreated",
  "sourceReq": {
    "ccy": "BTC",
    "method": "lightning",
    "amtRequested": 0.0001,
    "reqStatus": "0",
    "reqDetails": {
      "paymentRequest": "lnbc1u1p5c6aedpp5h3rnz669r...",
      "invoicePageUrl": "https://endash.npay.live/payment-invoice/e3db46cb-...?token=CQrn2t..."
    }
  },
  "destReq": {
    "ccy": "BTC",
    "method": "neutronpay",
    "amtRequested": 0.0001,
    "reqStatus": "0"
  },
  "fxRate": 1,
  "createdAt": 1770342000000
}

After confirmation, the response includes:

Step 3: Share the Invoice

You have two options to share with the sender:

Option A: Bolt11 string — The sender pastes the paymentRequest string into any Lightning wallet.

Option B: Invoice page URL — Share the invoicePageUrl link. Opens a hosted page with a QR code that any wallet can scan.

Integration Example

Here's a typical payment flow for an e-commerce integration:

Customer clicks "Pay with Lightning"
        │
        ▼
Your server: POST /api/v2/transaction  (create)
        │
        ▼
Your server: PUT /api/v2/transaction/{txnId}/confirm
        │
        ▼
Display Bolt11 QR code or link to invoicePageUrl
        │
        ▼
Customer scans & pays with Lightning wallet
        │
        ▼
Neutron sends webhook → Your server marks order as paid

Polling vs Webhooks

You have two ways to detect payment:

See Webhook Guide for setup instructions.

SDK Examples

TypeScript (neutron-sdk)

import { Neutron } from "neutron-sdk";

const neutron = new Neutron({
  apiKey: process.env.NEUTRON_API_KEY,
  apiSecret: process.env.NEUTRON_API_SECRET,
});

// One-liner: creates and confirms automatically
const invoice = await neutron.lightning.createInvoice({ amountSats: 10000 });

console.log(invoice.invoice);   // "lnbc100u1p..."  — Bolt11 string
console.log(invoice.qrPageUrl); // hosted QR code page URL
console.log(invoice.txnId);     // transaction ID for polling/tracking

// With a reference ID
const invoice2 = await neutron.lightning.createInvoice({
  amountSats: 5000,
  extRefId: "order-1234",
});

Python (neutron-python)

from neutron import Neutron

client = Neutron(api_key="...", api_secret="...")

# Create and confirm in one call
invoice = client.lightning.create_invoice(amount_sats=10000)

print(invoice["invoice"])      # "lnbc100u1p..." — Bolt11 string
print(invoice["qr_page_url"]) # hosted QR code page URL
print(invoice["txn_id"])      # transaction ID for polling/tracking

Transaction States

Lightning invoices have a default expiry (typically 1 hour). If the sender doesn't pay in time, the transaction expires.

See Transaction Status Types for the complete state reference.

Fees

Receiving Lightning payments has minimal or zero fees:

Notes

• No KYC required for Bitcoin Lightning transactions. KYC is only needed for fiat payouts.
• The Bolt11 invoice has an expiry time. Share it with the sender promptly after confirming.
• Use extRefId to attach your own order/reference ID — it's included in webhook payloads for easy matching.
• For a persistent payment endpoint (no invoice generation needed), use your account's Lightning Address.
• Amounts are always in BTC, not satoshis (100 sats = 0.00000100).

Related

• Send Bitcoin via Lightning — Pay Lightning invoices from your wallet
• Webhook Guide — Set up real-time payment notifications
• Transaction Status Types — Complete state reference