Hold Invoices & Payment Safety

Understand when sms4sats Lightning hold invoices settle or release.

A Lightning hold invoice lets the receiver accept a payment without immediately settling it. The funds remain locked until sms4sats either settles the invoice with its preimage or releases it.

The hold-invoice model applies to bearer-token receive-SMS orders, bearer-token rental orders, and email activations. L402 uses a standard Lightning invoice plus a separate refund-invoice flow.

Receive SMS

invoice paid
  → number allocated
  → SMS durably stored
  → hold settled

If allocation fails, the order expires, or an eligible cancellation completes, the provider activation is cancelled first and the held payment is then released. A payment is not released while the provider outcome is ambiguous.

Email activation

invoice paid
  → email assigned
  → provider returns a code or message
  → hold settled and completed response stored

Allocation failure, provider cancellation, and timeout paths attempt to release the hold. A manual cancellation returns success only after LNbits confirms the hold release; provider-side email cancellation is best-effort. Poll the order and check wallet state rather than assuming release from elapsed time alone.

Number rentals

The rental hold invoice settles when the number is allocated—not when a later SMS arrives. Manual cancellation is available only before payment; any paid browser rental is not manually cancellable.

What “released” means

A released hold was never finally transferred to sms4sats. Most wallets restore the amount to the spendable balance automatically. Wallet interfaces may briefly show the payment as pending while the release propagates.

Integration rules

1. Display priceSats from the creation response, not a locally calculated price.

2. Treat payment as pending until the order API reports progress.

3. Follow server-provided state and cancellation fields.

4. Keep polling through transitional states such as settlement_pending, release_pending, and cancelling.

5. Stop only on a terminal state.

6. For bearer-token SMS/rental creation only, retry an ambiguous response with the same idempotency key. Email and L402 creation do not support idempotency keys and must not be retried blindly.