BTCPay Server

Commerce27 min readSelf-hosted Bitcoin payment server with Nostr identity, zaps and NWC support

BTCPay Server

BTCPay Server matters to Nostr because it brings the open social identity layer into checkout, Lightning Address, zaps and wallet backend choice without asking a merchant to hand payment custody to a platform.

A payment server before it is a Nostr tool

BTCPay Server is best understood from the checkout counter outward. A merchant wants to show a payable invoice, receive bitcoin or Lightning, track settlement, keep accounting records and avoid placing the business balance inside a third-party processor. BTCPay was built around that problem long before Nostr became an ecosystem category. The main project describes itself as a free, open-source and self-hosted Bitcoin payment processor. That sentence does a lot of work. Free and open-source means the code can be inspected and run without a SaaS account. Self-hosted means the merchant or host controls the server. Bitcoin payment processor means the product is measured by invoice reliability, wallet setup, integrations and operational custody, not by feed design.

That starting point matters because Nostr can make BTCPay sound more social than it is. The Nostr plugin does not turn BTCPay into Damus, Primal, Coracle or a timeline client. It adds open identity and Nostr-native payment signals to a payment server. The store can expose a NIP-05 name on its own BTCPay domain. The store can advertise zap capability through LNURL pay. The server can receive a zap request, wait for the underlying invoice to be paid, build a NIP-57 zap receipt and publish that receipt to relays. The server can also accept a Nostr Wallet Connect connection string as a Lightning backend, so an NWC-enabled wallet can sit behind BTCPay invoices.

For a reader, this is the useful distinction. BTCPay is not interesting because it wears a Nostr badge. It is interesting because it lets a merchant bring Nostr identity and zaps into a serious payment stack without giving up the larger BTCPay model: invoices, stores, checkout pages, plugins, wallet separation, deployment choices and self-hosted control. The Nostr feature is a bridge between public identity and payment operations.

What BTCPay already does for merchants

BTCPay Server is a broad product. The core documentation covers store creation, wallet setup, invoices, payment requests, pull payments, refunds, payouts, form builder flows, reporting and a set of built-in apps such as point of sale, crowdfunding and donation buttons. It also has integrations for common commerce systems, including WooCommerce, Shopify, Drupal, Magento, OpenCart, PrestaShop and other platforms. That breadth is why the Nostr side should be read as one piece of a larger merchant stack, not as the whole product.

The self-hosted posture changes the trust model. A hosted processor normally owns the account relationship and can impose policy, freeze access, collect identity data or change terms. BTCPay moves much of that burden to the operator. That is liberating and inconvenient at the same time. The merchant has more control over keys, server policy, plugins, Tor access, checkout appearance and data retention. The merchant also inherits server maintenance, update timing, backup discipline, plugin risk and the need to understand how on-chain and Lightning wallets are connected.

Lightning support is part of that merchant reality. BTCPay can work with different Lightning backends, and the project documentation covers Lightning setup separately from the on-chain wallet. The Nostr plugin adds another backend path through Nostr Wallet Connect. That does not replace the need to understand Lightning. It gives the merchant another way to let the server create invoices, look them up and listen for settlement when the actual wallet is elsewhere.

The Nostr plugin has three practical jobs

The BTCPay Nostr plugin describes three main capabilities: NIP-05 account verification, NIP-57 zap support and NIP-47 support for accepting payments to an NWC-enabled Lightning wallet. Those three jobs are related, but they are not the same thing. NIP-05 is about names. Zaps are about a Nostr event that points to a Lightning payment request and later receives a signed receipt. NWC is about a wallet-control connection where one app asks a wallet service to create invoices, look up invoices, list transactions or pay.

The plugin source confirms that this is not just a documentation label. The plugin registers a Nostr side navigation item inside a store, adds a Nostr Wallet Connect setup tab to Lightning payment method configuration, provides a NIP-05 controller, wires a zapper service, and registers a connection string handler for Nostr Wallet Connect. In other words, the plugin touches the store settings UI, the public well-known identity endpoint, the LNURL pay callback path, invoice events and Lightning client setup.

That mix is powerful because Nostr payment UX often fails at the handoff between identity and money. A user sees a profile, wants to send value, and then the app needs a real payment endpoint. BTCPay can make a merchant's domain, Lightning Address and Nostr public key line up. The result is not a casual profile tip jar. It is a store-grade payment server that can also speak the zap language used by Nostr clients.

NIP-05 makes the store domain part of the name

The NIP-05 side is the cleanest part to understand. A store owner opens the Nostr settings page inside BTCPay, chooses a name, enters a public key and optionally adds relays. The public NIP-05 handle becomes something like name@yourbtcpayserver.domain. If several domains are mapped to the same BTCPay server, the documentation says those domains can all be valid. The controller exposes the familiar /.well-known/nostr.json endpoint and returns a map from names to public keys, with relay hints when configured.

That matters because NIP-05 is where a store can turn a bare public key into a domain-backed identity. A reader does not need to memorize the hex key or an npub. The name says which server is making the claim. For a shop, creator, fundraiser, project or event, that can be more meaningful than a platform profile. The domain is already part of the commercial relationship. Using the same domain for the Nostr name keeps payment identity closer to the place where customers already check legitimacy.

The source also shows the constraints. Store owners need permission to modify store settings. Names cannot be reused across stores on the same server. The public key can be entered in different formats, including hex, npub and nprofile. When an nprofile carries relay hints, the controller can add those relays to store settings. This is not a global identity registry. It is a server's statement about names under its own domain, which is exactly the point of NIP-05.

Zaps start with Lightning Address

The Nostr settings page in the plugin contains a detail that is easy to miss: zap support depends on Lightning Address and LNURL pay behavior. BTCPay can expose Nostr zap support in LNURL metadata so a Nostr client knows that the payment endpoint accepts zap requests. The store does not merely publish a social profile and hope a wallet guesses what to do. The server adds the pieces that let a zap request travel through the normal LNURL pay callback and then connect back to a Nostr receipt.

The plugin code has a filter that sets the Nostr public key on the LNURL pay request when the store has a NIP-05 public key configured. If the store does not, the plugin can fall back to a global zapper public key. It also marks that Nostr is allowed for that LNURL pay flow. This is why the public key choice matters. A zap is not just a Lightning payment with a purple label. It is a payment request with a Nostr event attached, and the receipt is supposed to prove what was paid, by whom and for which event.

For a merchant, the practical takeaway is simple: make sure the Lightning Address path is actually configured, reachable and connected to the correct store. NIP-05 identity is useful, but zaps ride through payment infrastructure. If the LNURL endpoint is wrong, the Lightning backend is not ready, the server is unreachable or the store setup is incomplete, the Nostr client can show a beautiful zap button and still fail at payment time.

How a zap receipt is built

The zap flow is not instant magic. The plugin reads the incoming LNURL callback, extracts the nostr parameter, deserializes the event, verifies the event id and signature, and stores the zap request against the invoice. When the invoice later reaches a completed or marked-completed state, the zapper service looks up the cached request and builds a NIP-57 zap receipt. The receipt includes tags from the original zap request plus the BOLT11 invoice and a description of the request.

That separation is important. The Lightning invoice settlement is the payment fact inside BTCPay. The Nostr receipt is the public social proof that gets published afterward. A relay can be slow, offline or filtering, but that does not retroactively make the BTCPay invoice unpaid. The receipt publication is an additional network step. The source shows a pending receipt queue, relay chunking, a timeout and repeated attempts. That is a pragmatic design for a relay world where delivery is useful but not perfectly synchronous.

The signing key is also worth reading carefully. If the store has a private key configured, the zap receipt can be signed with that store key. If not, the plugin can use a generated global zapper key. The first option gives a stronger relationship between the store identity and the receipt, but it means the server stores a private key. The second option avoids putting the store's Nostr private key on the server, but the receipt identity is less directly tied to the merchant's public persona. Neither choice is free. The safer default for many merchants is to use a dedicated store key rather than the same identity key used for personal posting.

NWC turns a wallet into a backend

Nostr Wallet Connect is the part that makes BTCPay feel especially relevant to the NWC ecosystem map. The plugin adds a Lightning payment method setup tab for NIP-47 and accepts connection strings in two forms: the standard nostr+walletconnect: URI and a BTCPay-style type=nwc;key=... wrapper around that URI. The connection string includes the wallet service public key, the client secret, relay information and sometimes additional wallet metadata.

Once configured, BTCPay treats that NWC relationship as a Lightning client. The implementation can create invoices, look up invoices, list incoming transactions, list outgoing payments, fetch balance and request payments. It can also listen for payment received notifications when the wallet advertises support. If notifications are not available, it falls back to polling incoming settled transactions. That is a very different design from pasting a static Lightning Address into a profile. The payment server is actively using a wallet-control protocol to operate the backend.

This is useful for merchants who want BTCPay's invoice and store layer but do not want, or cannot run, the Lightning node directly inside the same stack. It can also be useful for hosted wallet arrangements, mobile wallet experiments, cloud nodes or account systems that expose NWC. The tradeoff is that the NWC credential becomes sensitive infrastructure. If the server can use it to create invoices or pay invoices, it must be protected with the same seriousness as any other backend wallet secret.

What the NWC client expects

The plugin's NWC client validates capabilities rather than assuming every wallet is equivalent. The validation path checks network compatibility and expects methods such as get_info, make_invoice, lookup_invoice and list_transactions. That tells you what BTCPay needs for a reliable receive setup: it must be able to make invoices, find them again and observe settlement. A wallet that only looks good in a consumer zap client may not be sufficient for a store server.

The implementation also contains payment-related methods, including BOLT11 invoice payment and keysend when no invoice is present. That does not mean every merchant should hand BTCPay broad spending permission without thinking. NWC is permissioned by the wallet service and often by budgets, method scopes and expirations. A store that only needs incoming invoices should keep the connection as narrow as the wallet allows. If outgoing payouts or refunds are part of the business process, the operator should document exactly which NWC methods are enabled and why.

The listener behavior is another practical detail. If the wallet supports payment received notifications, BTCPay can listen through NWC notifications. If not, it polls. Polling can be good enough, but it changes latency and load expectations. Before relying on a wallet in production, send test invoices, wait for completion, restart the server, rotate relays when possible and verify that BTCPay still sees settlements after temporary disconnects.

Private keys need a stricter habit

BTCPay already asks operators to think about server trust, backups and wallet boundaries. The Nostr plugin adds another class of secret: Nostr private keys and NWC client secrets. They behave differently, but both deserve a stricter habit than copy-paste convenience. A Nostr private key signs events. An NWC secret authorizes wallet interaction through a remote wallet service. If either is copied into the wrong place, the damage can be subtle and hard to unwind.

The plugin UI allows an optional private key for zaps. It accepts nsec or hex, verifies that the key matches the configured public key and then uses it to sign receipts. That verification is good. It prevents a merchant from accidentally pairing the wrong public and private keys. It does not remove the basic server risk. If the server is compromised, a stored Nostr private key may be compromised too. Many stores should consider a dedicated Nostr key for receipts and store identity instead of reusing the owner's personal key.

The NWC string is even more operational. It may allow invoice creation, invoice lookup, transaction listing, balance access or payments depending on wallet permissions. Treat it like an API credential for money movement. Use the smallest budget and method set that fits the store. Prefer a connection that can be revoked quickly. Do not reuse the same connection across unrelated stores. Keep relay choices boring and documented. A checkout server is the wrong place for experimental permissions you do not understand.

Relay timing is not payment timing

Nostr relays appear in several places: NIP-05 relay hints, zap request relay tags, zap receipt publication and NWC communication. That can make it feel as if relay success and payment success are the same thing. They are not. BTCPay's payment truth comes from the invoice and the Lightning backend. Relays help Nostr clients discover identity, request context and receive receipts. When relays fail, the public Nostr record may lag or disappear. The merchant still needs to look at BTCPay invoice state for accounting.

The zapper service reflects this reality. It queues pending receipts and tries to publish them to relays, chunking relay groups and waiting for receipt. That is a practical engineering choice rather than a ceremonial one. Nostr relays vary in uptime, policy and speed. A store that depends on public zap visibility should test with the clients and relays its audience actually uses. A store that depends on payment settlement should watch BTCPay invoices and wallet state first.

This distinction also helps readers judge support requests. A customer saying the zap did not show in a client may be reporting a relay or receipt problem. A customer saying the invoice did not settle is a payment problem. A customer saying the NIP-05 name does not verify may be hitting DNS, domain, HTTPS, name collision or well-known JSON issues. BTCPay puts these pieces in one admin surface, but each piece still has its own failure mode.

The plugin layer has its own update risk

BTCPay's plugin architecture is one of its strengths, but plugins are still code in the payment environment. The Nostr plugin lives in the BTCPayServerPlugins repository rather than the main BTCPay Server repository. It depends on the wider BTCPay plugin system, the Nostr client library it imports, the current NIP behavior and the wallet services used behind NWC. That gives merchants flexibility, but it also means the plugin should be updated and tested with the same care as the core server.

The BTCPay changelog has included security-sensitive notes for users of specific plugins, including the Nostr plugin. The point is not to scare merchants away. The point is to treat a payment server as infrastructure. If a plugin handles private keys, NWC credentials, LNURL callbacks or invoice events, it belongs in the operator's patching calendar. Do not install it once and forget it because the front-end settings page looks calm.

A careful update rhythm is simple. Track the main BTCPay release notes. Track the plugin repository. Read breaking changes before upgrading. Test zap requests and NWC invoices on a staging store if your volume justifies it. Keep backups before changes. After an update, verify the NIP-05 endpoint, Lightning Address metadata, zap receipt publication, invoice creation and settlement detection. The boring checks are what keep an open payment stack usable.

Where BTCPay fits in Nostr commerce

Nostr commerce is often discussed through storefronts, classifieds, fundraisers and social payment links. BTCPay sits underneath many of those surfaces. It is the payment server a merchant can control while the public discovery layer may happen somewhere else. A shop might be discovered through a Nostr profile, a marketplace, a long-form article, a live stream, a conference page or a Discord post. BTCPay is where the invoice can become real without moving the merchant into a custodial platform.

That is also why its Nostr support is not only for tip culture. Zaps are a visible use case, but BTCPay's stronger role is to connect Nostr identity with merchant-grade payment workflows. A creator can use a domain-backed name and accept zaps. A project can run donation buttons and crowdfunding pages. A small business can run point of sale. A software project can collect paid invoices. A community event can publish a recognizable Nostr identity while using BTCPay for actual checkout.

The future value is composability. A Nostr client can recognize identity. A wallet can speak NWC. A payment server can create invoices and publish receipts. A merchant can keep the relationship on its own domain. No single piece needs to become the entire platform. BTCPay is one of the more concrete examples of that pattern because it connects open social signals to invoices and settlement instead of stopping at a profile page.

What to test before using it

Start with the basics. Confirm that BTCPay itself is up to date, reachable over HTTPS, backed up and configured for the correct network. Create a store, set up the wallet path you actually intend to use and create ordinary invoices before adding Nostr. If the normal payment server is not healthy, the Nostr plugin will only add more surfaces to debug.

Then test NIP-05. Add a store name and public key. Load /.well-known/nostr.json?name=yourname directly in a browser. Verify that the JSON returns the expected public key and relay hints. Check the name in more than one Nostr client. If the public key was entered as npub or nprofile, confirm that the saved value still resolves to the key you meant to use.

After that, test Lightning Address and zaps. Enable the Lightning Address path for the store. From a Nostr client, send a small zap to the address or profile connected to the store. Confirm the BTCPay invoice appears, settles and receives the zap request. Then verify that the receipt appears on relays and inside at least two clients. If you configure a private key for receipt signing, confirm the receipt public key is the store key you expect.

Finally, test NWC like a backend credential. Create the narrowest NWC connection your wallet supports. Paste it into BTCPay's NWC Lightning setup. Validate it, create a small invoice, pay it from another wallet and watch BTCPay detect settlement. Restart BTCPay and repeat. Rotate the NWC connection once so you know how revocation works before there is an emergency. When a payment server can move or request money, rehearsal is not paranoia. It is maintenance.

Sources worth opening

Open the BTCPay documentation, the main BTCPay repository, the Nostr plugin source, the NWC client implementation and the relevant NIPs together. The interesting details live in the boundary between store settings, LNURL metadata, zap receipt signing and wallet connection strings.

• BTCPay Server official website
• BTCPay Server documentation
• BTCPay Server Nostr plugin documentation
• BTCPay Server Lightning Network documentation
• BTCPay Server deployment documentation
• BTCPay Server apps documentation
• BTCPay Server GitHub repository
• BTCPay Server README
• BTCPay Server changelog
• BTCPay Server plugins repository
• BTCPay Nostr plugin source directory
• BTCPay Nostr plugin README
• BTCPay Nostr plugin project file
• BTCPay Nostr plugin registration
• BTCPay NIP-05 controller
• BTCPay NIP-05 store settings
• BTCPay NIP-05 response model
• BTCPay Nostr settings view
• BTCPay LNURL Nostr filter
• BTCPay LNURL zap request filter
• BTCPay zapper service
• BTCPay zapper settings
• BTCPay NWC connection string handler
• BTCPay NWC Lightning client
• BTCPay NWC setup tab
• BTCPay pending payout listener
• BTCPay checkout appearance settings
• NIP-05 mapping Nostr keys to DNS identifiers
• NIP-57 Lightning zaps
• NIP-47 Nostr Wallet Connect
• NIP-07 browser extension signing
• NWC documentation introduction
• NWC reference API overview
• LNURL LUD-06 pay request base specification
• LNURL LUD-16 Lightning Address
• Lightning BOLT 11 invoice specification
• BTCPay community chat