NWC

Build Conditional Payment Logic Into Your App

• 3 min read
Build Conditional Payment Logic Into Your App

Why Developers Should Build on Hold Invoices

If you’re building on the lightning network, Hold invoices* are your secret weapon. They give you powerful control over the final step of a payment—the moment of settlement—which unlocks app behaviors that were previously hard or impossible to build in a trust-minimized way.

Let’s list some use cases enabled by Hold invoices:

1. Conditional Payments for Smarter App Logic

Don’t just accept payments, evaluate them. Hold invoices let your app pause the settlement until your logic says it’s OK. If something doesn’t work out, the transaction is canceled and the user gets their funds back. You don't need to build refunds. The app just doesn't settle the payment until it's safe to do so.

Use Cases:

  • Inventory check before shipping
  • Workflow gating (e.g. allow access only if certain criteria are met) (Example: Users lock up funds upfront in the peer-to-peer wagering game Clinch by THNDR) 

2. Add Economic Guarantees Without Charging Upfront

Want to deter abuse or spam without charging honest users? Use Hold invoices as fidelity bonds: a user pays a Hold invoice to start a session or request a resource. If they behave, you cancel it with zero cost to them. If they abuse it, you settle the payment as a penalty.

Use Cases:

  • Rate-limiting API keys
  • Secure access to real-time services
  • Pay-to-play interactions that only cost money if misused (Example: Fidelity bond for peer-to-peer trading on Robosats)

3. "No Delivery, No Pay" Workflows

Think of Hold invoices as programmable escrow. The buyer locks in a payment upfront, but the seller only gets paid when proof of delivery is exchanged—often just a preimage. No middlemen required.

Use Cases:

  • Physical delivery services
  • Digital goods with delayed unlocking (Example: If you lease a payment channel from a Lightning Service Provider, you only pay if the channel has actually been opened)

Hold invoices let you decide when and why to settle or cancel a payment. This enables building smarter logic on top of payments without the need for custodians or centralized logic.

How to use Alby Hub to make use of Hold Invoices.  

Alby Hub makes it easy to build with Hold invoices. Using the Nostr Wallet Connect (NWC) API, you can programmatically create, monitor, settle, and cancel Hold invoices—no need to run another lightning wallet or node.

  • make_hold_invoice: Create a Hold invoice using a pre-generated preimage and its payment hash.
  • settle_hold_invoice: Settle a Hold invoice by providing the original preimage.
  • cancel_hold_invoice: Cancel a Hold invoice using its payment hash.
  • hold_invoice_accepted: Emitted when a payer accepts a Hold invoice (i.e., locks in payment).

Example of a 1v1 wagering game between Bob and Alice

  1. Game Creation
    a) Backend generates two preimages: one for Alice, one for Bob
    b) Backend creates Hold invoices with make_hold_invoice using the generated preimages and passes them to Alice and Bob
    c) Backend requests invoices from Alice and Bob for the possible payout after winning the game
  2. Wait for both hold_invoice_accepted events from Bob and Alice. 
    a) When both are locked in, the match starts. 
  3. Game is played
    a) Backend tracks the game state and determines a winner
  4. Settle and cancel Hold invoices when Alice wins
    a) Settle Bob's invoice: settle_hold_invoice - Bob’s funds are kept.
    b) Cancel Alice's invoice: cancel_hold_invoice - Alice’s funds are released back.
  5. Pay reward to Alice
    a) Use the requested invoice from step 1c to pay out Alice's reward

Note: Using NWC makes the Game Creation in step 1 seamless for the user as no manual interaction is needed.

Bottom Line for Developers

Hold invoices unlock programmable, conditionally-settled bitcoin payments on the lightning network. They’re not just a payment mechanism. They’re an app development primitive to build:

  • Safer pay-per-access services (e.g. APIs)
  • Trustless delivery workflows
  • Bitcoin-native escrow models
  • P2P wagering games

⚡ If you’ve ever needed more control over when or why a bitcoin payment settles, Hold invoices are your answer. 

Please, reach out, we would love to help you build the app you envision. Have a look at the Alby JS SDK where you’ll find an example to easily create unique payment experiences!  

Hold invoices are a special type of Lightning invoice where the receiver, instead of immediately locking and settling the HTLC when a payment arrives, only locks the HTLC but deliberately delays settlement (i.e., they withhold the preimage). At this stage, the sender can no longer cancel the payment. The receiver can then perform some action before choosing to either accept the payment, explicitly reject it, or let it expire.

From the sender’s perspective, a Hold invoice looks just like a regular payment request. They are sometimes spelled “Hodl invoices.” One important detail is that Hold invoices lock up the liquidity of all routing nodes along the payment path until the invoice is either settled or times out. This should be taken into account when choosing the appropriate lockup period.