BITCOIN LIGHTNING

Accept Lightning payments.

Connect a receiving wallet, enable it in your store and let customers pay with a Lightning QR code.

A wallet connection, not a public node.

A public Bitcoin endpoint can read the blockchain. It cannot receive Lightning payments for you. Lightning needs a wallet that creates invoices and reports when they settle.

Your setup	Connect with	Who looks after it?
Your own node	LND over HTTPS, or a compatible NWC wallet	You manage keys, channels, liquidity and backups.
Managed self-custodial wallet	NWC, for example Alby Hub with hosting	A service helps run it. Check that you retain key control and recovery access.
Custodial account	A compatible provider’s NWC connection	The provider holds your funds. Fees, account limits and verification requirements depend on the provider.

NWC is a connection protocol, not a custody guarantee. Choose the wallet model that fits your business. Wholly Crypto does not hold Lightning funds or install a node.

Connect your LND node.

Open Settings → Chain connections → Connect Lightning. Choose LND · HTTPS.
Enter the externally reachable HTTPS REST endpoint and a restricted macaroon in hexadecimal format. Allow invoice read/write and info:read. Add offchain:read if you want channel balances displayed. Never use admin.macaroon or grant spending permissions.
If LND uses its own TLS certificate, paste its public PEM certificate. Do not paste a TLS private key. Allow access from your merchant VPS at the node’s firewall.
Select the projects allowed to use the connection. Check and save, then enable it for new invoices.

The node must be synced to Bitcoin mainnet. TLS verification stays on. This connection accepts public HTTPS addresses only; private, loopback and reserved addresses are blocked. Keep the node separate from your payment server.

LND macaroon permissions ↗

Connect through Nostr Wallet Connect.

In Alby Hub or another compatible wallet, create a dedicated receiving connection.
Allow make_invoice, lookup_invoice and get_info. get_balance is optional. Do not allow payment or withdrawal methods.
Choose Nostr Wallet Connect in Wholly Crypto and paste the complete nostr+walletconnect://… connection string. Treat it like a password.
Use one public WSS relay in the connection string. Choose your custody model and project access, then check and save.

Wholly Crypto verifies signed responses and supports NIP-44 v2 encryption with legacy NIP-04 compatibility. The wallet must support incoming invoice lookup with settlement proof. Not every NWC account supports all receiving methods.

Alby Hub guide ↗ · NWC specification ↗

Enable it for your store.

Open Project → Stores → Payment methods → Bitcoin Lightning. Choose the connection and switch it on. On-chain Bitcoin is a separate choice; you can offer either or both.

Create a small invoice manually or through the usual API. In checkout, choose Bitcoin and then Bitcoin Lightning. Scan the QR code or open the request in a Lightning wallet. No new API route is needed to create an invoice.

Paid means settled.

Each request gets its own BOLT11 invoice and payment hash. Prices use the store’s fiat currency and spread, rounded upward to whole satoshis. Wholly Crypto records receipts with millisatoshi precision.

A held or detected payment is not enough. The wallet must report settlement with a valid payment proof. No block confirmations are needed. Invoice history, processing fees, IPN and webhooks follow the normal invoice workflow.

LND uses one settlement subscription per connection plus recovery lookups. NWC uses invoice lookups. Pending lookups normally run about every 10 seconds; outages, queues and provider limits can delay updates. Unsettled requests remain monitored for 24 hours after the merchant invoice deadline.

Disabling or replacing credentials does not move an existing request to a different wallet. Keep old receiving credentials working until pending requests finish. Expired or cancelled requests must not be paid.

This integration receives payments. Use the connected wallet for sending, refunds, channel management or exchange transfers. Lightning balances are shared wallet balances, not separate project wallets. Provider, routing and channel fees are separate from Wholly Crypto’s processing fee.

Keep capacity and backups ready.

Your node needs incoming channel capacity to receive. A connected wallet with no usable route or receiving capacity can still fail to receive a payment. A liquidity service may help, but costs and conditions vary.

The project wallet text backup does not back up Lightning. Follow your node or wallet’s recovery procedure, including its required channel backups. A seed phrase alone may not recover channel funds safely. Back up Wholly Crypto’s database and encryption key to preserve invoice tracking and encrypted connection credentials.

LND recovery guide ↗

Check the connection first.

Access rejected: check receiving permissions and whether the credential is still valid.
Connection failed: check HTTPS/WSS, TLS, DNS, firewall access and whether the wallet is online.
Request unavailable: check project access, store activation, current exchange rates and the wallet’s mainnet status.
Payment cannot route: check incoming liquidity in your Lightning wallet. A healthy API connection does not prove a route exists.

Test a small payment and its notification flow before offering Lightning to customers. Never send wallet keys, macaroons or NWC secrets to support.