fix: prevent duplicate BOLT12 offer payments on retry (#4287)
What changed, and why it matters
This commit fixes a bug where retrying a BOLT12 offer payment could accidentally pay the same offer twice. It adds an idempotency check using an external_id so that retries return the original payment instead of creating a duplicate, while still allowing intentional repeat payments with a new ID. The change is defensive and reduces financial loss risk from duplicate spends.
Deploy this patch to prevent duplicate BOLT12 offer spends. Ensure API consumers understand that external_id must be stable for retries and changed for intentional repeats or post-failure retries. Review monitoring for PaymentError responses related to external_id conflicts.
Security signals we found
Duplicate payment prevention for BOLT12 offers
Idempotency keyed on wallet_id + external_id
Conflict detection when external_id reused with different payment details
Failed offer payments require new external_id to retry
Wallet-level scoping of external_id for outgoing payments
Evidence from the diff
The patch introduces idempotency for BOLT12 offer payments by checking for an existing outgoing payment with the same wallet_id + external_id before invoking the wallet backend. If a matching payment exists and has not failed, the existing payment is returned; if details differ, a PaymentError is raised; if the prior attempt failed, a new external_id is required. The UI now generates and persists an external_id for BOLT12 offers across retries. Tests cover retry deduplication, concurrency, changed details, failed attempts, and wallet scoping.
Changed components
lnbits/core/services/payments.pylnbits/core/views/payment_api.pylnbits/static/js/api.jslnbits/static/js/pages/wallet.jsInspect captured patch +426 / −8
### lnbits/core/services/payments.py
@@ -12,7 +12,7 @@
from lnbits.core.models import PaymentDailyStats, PaymentFilters
from lnbits.core.models.payments import CreateInvoice
from lnbits.core.models.wallets import WalletType
-from lnbits.db import Connection, Filters
+from lnbits.db import Connection, Filter, Filters
from lnbits.decorators import check_user_extension_access
from lnbits.exceptions import InvoiceError, PaymentError, UnsupportedError
from lnbits.fiat import get_fiat_provider
@@ -117,7 +117,9 @@ async def pay_offer(
) -> Payment:
"""
Offers are not invoices: they have no payment hash until the backend
- fetches and pays one.
+ fetches and pays one. Reuse external_id for retries within the same wallet;
+ use a new external_id for an intentional repeat payment, including after failure.
+ Without external_id, each call is a separate payment.
"""
if settings.lnbits_only_allow_incoming_payments:
raise PaymentError("Only incoming payments allowed.", status="failed")
@@ -815,6 +817,12 @@ async def _pay_invoice(
f"Could not fetch wallet '{wallet_id}'.", status="failed"
)
+ if looks_like_bolt12_offer(create_payment_model.bolt11):
+ # Check under the wallet lock before reserving funds or paying again.
+ payment = await _get_existing_offer_payment(create_payment_model, conn)
+ if payment:
+ return payment
+
payment = await _pay_internal_invoice(wallet, create_payment_model, conn)
if not payment:
payment = await _pay_external_invoice(
@@ -1548,3 +1556,41 @@ async def _update_incoming_payment_status(
if payment.success:
task_manager.invoice_queue.put_nowait(payment)
return payment
+
+
+async def _get_existing_offer_payment(
+ data: CreatePayment, conn: Connection | None = None
+) -> Payment | None:
+ if not data.external_id:
+ return None
+
+ payments = await get_payments(
+ wallet_id=data.wallet_id,
+ outgoing=True,
+ filters=Filters(
+ model=PaymentFilters,
+ filters=[
+ Filter.parse_query("external_id", [data.external_id], PaymentFilters)
+ ],
+ limit=1,
+ ),
+ conn=conn,
+ )
+ if not payments:
+ return None
+
+ payment = payments[0]
+ if (
+ payment.extra.get("bolt12_offer", payment.bolt11) != data.bolt11
+ or payment.amount != data.amount_msat
+ or payment.extra.get("payer_note") != (data.extra or {}).get("payer_note")
+ ):
+ raise PaymentError(
+ "External ID already used for a different payment.", status="failed"
+ )
+ if payment.failed:
+ raise PaymentError(
+ "Offer payment already failed. Use a new external_id to retry.",
+ status="failed",
+ )
+ return payment
### lnbits/core/views/payment_api.py
@@ -270,6 +270,10 @@ async def api_all_payments_paginated(
`payment_request` to supply the BOLT11 invoice or BOLT12 offer (`lno1…`,
optional `lightning:` URI). Paying a BOLT12 offer requires `amount` in
`sat`. For offers, `memo` is sent to the recipient as a payer note.
+ Reuse `external_id` when retrying an offer payment in the same wallet:
+ matching offer, amount and memo return the existing payment. Use a new
+ `external_id` for intentional repeat payments or retries after failure.
+ Omitting it treats each request as a separate payment.
The optional `webhook` field is honoured in both directions: LNbits POSTs
the payment to that URL once the payment reaches `success`.
""",
### lnbits/static/bundle-components.min.js
[binary or diff unavailable]
### lnbits/static/bundle.min.js
[binary or diff unavailable]
### lnbits/static/js/api.js
@@ -44,7 +44,8 @@ window._lnbitsApi = {
paymentRequest,
internalMemo = null,
amount = null,
- memo = null
+ memo = null,
+ externalId = null
) {
const data = {
out: true,
@@ -62,6 +63,9 @@ window._lnbitsApi = {
if (memo) {
data.memo = memo
}
+ if (externalId) {
+ data.external_id = externalId
+ }
return this.request('post', '/api/v1/payments', wallet.adminkey, data)
},
cancelInvoice(wallet, paymentHash) {
### lnbits/static/js/pages/wallet.js
@@ -9,6 +9,7 @@ window.PageWallet = {
lnurlpay: null,
lnurlauth: null,
sending: false,
+ externalId: null,
decoding: false,
decodeId: 0,
data: {
@@ -96,6 +97,8 @@ window.PageWallet = {
return false
}
if (this.parse.invoice.isBolt12Offer) {
+ // A retry can retrieve a payment that already reserved the balance.
+ if (this.parse.externalId) return true
if (this.bolt12AmountMissing) {
return true
}
@@ -314,10 +317,12 @@ window.PageWallet = {
this.parse.data.internalMemo = null
this.parse.data.memo = ''
this.parse.sending = false
+ this.parse.externalId = null
this.parse.data.paymentChecker = null
this.parse.camera.show = false
},
closeParseDialog() {
+ this.parse.externalId = null
this.parse.decodeId++
this.parse.decoding = false
setTimeout(() => {
@@ -634,6 +639,10 @@ window.PageWallet = {
return
}
+ if (this.parse.invoice.isBolt12Offer && !this.parse.externalId) {
+ // Retain this ID after errors: the funding source may have paid already.
+ this.parse.externalId = Quasar.uid()
+ }
this.parse.sending = true
const dismissPaymentMsg = Quasar.Notify.create({
timeout: 0,
@@ -649,7 +658,8 @@ window.PageWallet = {
this.parse.data.request,
this.parse.data.internalMemo,
amount,
- this.parse.invoice.isBolt12Offer ? this.parse.data.memo : null
+ this.parse.invoice.isBolt12Offer ? this.parse.data.memo : null,
+ this.parse.invoice.isBolt12Offer ? this.parse.externalId : null
)
.then(response => {
this.parse.sending = false
@@ -950,7 +960,10 @@ window.PageWallet = {
this.receive.show = false
},
'g.updatePayments'() {
- this.parse.show = false
+ // Keep unresolved offer attempts open so retries reuse their ID.
+ const keepOfferOpen =
+ this.parse.invoice?.isBolt12Offer && this.parse.externalId
+ if (!keepOfferOpen) this.parse.show = false
if (
this.g.wallet.currency &&
this.$q.localStorage.getItem(
### tests/api/test_api.py
@@ -861,6 +861,44 @@ async def test_pay_bolt12_offer(client, adminkey_headers_to, fields):
assert body["extra"]["bolt12_offer"] == BOLT12_OFFER
+@pytest.mark.anyio
+@pytest.mark.parametrize("pending", [False, True])
+async def test_pay_bolt12_offer_retry_with_external_id(
+ client, adminkey_headers_to, monkeypatch, pending
+):
+ backend = (
+ AsyncMock(return_value=PaymentResponse())
+ if pending
+ else AsyncMock(wraps=FakeWallet().pay_offer)
+ )
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ data = {
+ "out": True,
+ "payment_request": BOLT12_OFFER,
+ "amount": 21,
+ "external_id": uuid4().hex,
+ }
+ first = await client.post(
+ "/api/v1/payments", json=data, headers=adminkey_headers_to
+ )
+ retry = await client.post(
+ "/api/v1/payments", json=data, headers=adminkey_headers_to
+ )
+ assert first.status_code == retry.status_code == 201
+ assert retry.json()["payment_hash"] == first.json()["payment_hash"]
+ assert retry.json()["checking_id"] == first.json()["checking_id"]
+ assert retry.json()["status"] == ("pending" if pending else "success")
+
+ conflict = await client.post(
+ "/api/v1/payments",
+ json={**data, "amount": 22},
+ headers=adminkey_headers_to,
+ )
+ assert conflict.status_code == 520
+ assert "External ID already used" in conflict.json()["detail"]
+ backend.assert_awaited_once()
+
+
@pytest.mark.anyio
@pytest.mark.parametrize(
"memo",
### tests/regtest/test_real_offer.py
@@ -1,11 +1,14 @@
import asyncio
import hashlib
+from uuid import uuid4
import pytest
-from lnbits.core.crud import get_standalone_payment, get_wallet
+from lnbits.core.crud import get_payments_paginated, get_standalone_payment, get_wallet
from lnbits.core.models import Payment
from lnbits.settings import Settings
+from lnbits.wallets import get_funding_source
+from lnbits.wallets.base import PaymentResponse
from .helpers import funding_source, lookup_offer_invoices
@@ -140,3 +143,111 @@ async def test_pay_real_offer(
assert (
wallet_before.balance_msat - wallet_after.balance_msat == total_debit_msat
)
+
+
+@pytest.mark.parametrize("real_offer", [100], indirect=True)
+@pytest.mark.parametrize(
+ "lose_response", [False, True], ids=["success", "lost-response"]
+)
+async def test_pay_real_offer_retry_is_idempotent(
+ client,
+ real_offer,
+ lose_response,
+ from_wallet,
+ adminkey_headers_from,
+ settings: Settings,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ settings.lnbits_funding_source_pay_offer_wait_seconds = 60
+ wallet_before = await get_wallet(from_wallet.id)
+ assert wallet_before
+ records_before = await get_payments_paginated(
+ wallet_id=from_wallet.id, outgoing=True
+ )
+ backend = get_funding_source()
+ backend_pay_offer = backend.pay_offer
+ settled: list[PaymentResponse] = []
+
+ async def pay_offer(*args, **kwargs):
+ result = await backend_pay_offer(*args, **kwargs)
+ assert result.success, result.error_message
+ settled.append(result)
+ if lose_response and len(settled) == 1:
+ # The real node paid, but LNbits never received the result. Inject the
+ # timeout after settlement so this does not depend on network timing.
+ raise asyncio.TimeoutError("Simulated lost BOLT12 payment response")
+ return result
+
+ monkeypatch.setattr(backend, "pay_offer", pay_offer)
+ request = {
+ "out": True,
+ "payment_request": real_offer["bolt12"],
+ "amount": 100,
+ "unit": "sat",
+ "external_id": uuid4().hex,
+ }
+ response = await client.post(
+ "/api/v1/payments", json=request, headers=adminkey_headers_from
+ )
+ assert response.status_code == 201, response.text
+ first = Payment(**response.json())
+ assert first.pending if lose_response else first.success
+ assert first.amount == -100_000
+ assert first.external_id == request["external_id"]
+ assert len(settled) == 1
+ if lose_response:
+ assert first.checking_id.startswith("temp_offer_")
+
+ wallet_after_first = await get_wallet(from_wallet.id)
+ assert wallet_after_first
+ assert wallet_before.balance_msat - wallet_after_first.balance_msat == (
+ 100_000 + abs(first.fee)
+ )
+
+ retry_response = await client.post(
+ "/api/v1/payments", json=request, headers=adminkey_headers_from
+ )
+ assert retry_response.status_code == 201, retry_response.text
+ retry = Payment(**retry_response.json())
+ assert retry.payment_hash == first.payment_hash
+ assert retry.checking_id == first.checking_id
+ assert retry.status == first.status
+ assert len(settled) == 1
+ wallet_after_retry = await get_wallet(from_wallet.id)
+ assert wallet_after_retry
+ assert wallet_after_retry.balance_msat == wallet_after_first.balance_msat
+ records = await get_payments_paginated(wallet_id=from_wallet.id, outgoing=True)
+ assert records.total == records_before.total + 1
+
+ received = await asyncio.to_thread(lookup_offer_invoices, real_offer["offer_id"])
+ paid = [invoice for invoice in received["invoices"] if invoice["status"] == "paid"]
+ assert len(paid) == 1
+ assert paid[0]["payment_hash"] == settled[0].checking_id
+ assert paid[0]["amount_received_msat"] == 100_000
+
+ # A new ID explicitly requests another payment of the reusable offer.
+ new_response = await client.post(
+ "/api/v1/payments",
+ json={**request, "external_id": uuid4().hex},
+ headers=adminkey_headers_from,
+ )
+ assert new_response.status_code == 201, new_response.text
+ second = Payment(**new_response.json())
+ assert second.success
+ assert second.payment_hash != first.payment_hash
+ assert second.checking_id != first.checking_id
+ assert len(settled) == 2
+ wallet_after_second = await get_wallet(from_wallet.id)
+ assert wallet_after_second
+ assert wallet_after_retry.balance_msat - wallet_after_second.balance_msat == (
+ 100_000 + abs(second.fee)
+ )
+ records = await get_payments_paginated(wallet_id=from_wallet.id, outgoing=True)
+ assert records.total == records_before.total + 2
+ received = await asyncio.to_thread(lookup_offer_invoices, real_offer["offer_id"])
+ paid = [invoice for invoice in received["invoices"] if invoice["status"] == "paid"]
+ assert len(paid) == 2
+ assert {invoice["payment_hash"] for invoice in paid} == {
+ result.checking_id for result in settled
+ }
+ assert all(invoice["amount_received_msat"] == 100_000 for invoice in paid)
### tests/unit/test_bolt12_idempotency.py
@@ -0,0 +1,202 @@
+import asyncio
+from unittest.mock import AsyncMock
+
+import pytest
+
+from lnbits.core.crud import (
+ create_payment,
+ create_wallet,
+ get_payments,
+ get_wallet,
+)
+from lnbits.core.models import CreatePayment, PaymentState
+from lnbits.core.services import create_user_account, pay_offer
+from lnbits.core.services.payments import update_wallet_balance
+from lnbits.exceptions import PaymentError
+from lnbits.utils.crypto import random_secret_and_hash
+from lnbits.wallets.base import PaymentResponse
+from lnbits.wallets.fake import FakeWallet
+from tests.helpers import BOLT12_OFFER, BOLT12_OFFER_WITH_DESCRIPTION
+
+
+@pytest.fixture
+async def offer_wallet(app):
+ user = await create_user_account()
+ wallet = await create_wallet(user_id=user.id)
+ await update_wallet_balance(wallet, 1000)
+ return wallet
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("amount", [100, 900])
+async def test_offer_retry_with_external_id_pays_once(
+ offer_wallet, monkeypatch, amount
+):
+ backend = AsyncMock(wraps=FakeWallet().pay_offer)
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ first = await pay_offer(
+ wallet_id=offer_wallet.id,
+ offer=BOLT12_OFFER,
+ amount_sat=amount,
+ external_id="order-1",
+ )
+ retry = await pay_offer(
+ wallet_id=offer_wallet.id,
+ offer="lightning:" + BOLT12_OFFER.upper(),
+ amount_sat=amount,
+ external_id="order-1",
+ )
+
+ backend.assert_awaited_once()
+ assert retry.payment_hash == first.payment_hash
+ assert retry.checking_id == first.checking_id
+ assert retry.status == first.status == "success"
+ assert len(await get_payments(wallet_id=offer_wallet.id, outgoing=True)) == 1
+ after = await get_wallet(offer_wallet.id)
+ assert after and after.balance_msat == (1000 - amount) * 1000
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("state", ["success", "pending", "timeout"])
+async def test_concurrent_offer_retries_pay_once(
+ offer_wallet, monkeypatch, settings, state
+):
+ settings.lnbits_funding_source_pay_offer_wait_seconds = 1
+ preimage, backend_id = random_secret_and_hash()
+
+ async def pay(*args, **kwargs):
+ if state == "timeout":
+ await asyncio.Event().wait()
+ return PaymentResponse(
+ ok=True if state == "success" else None,
+ checking_id=backend_id,
+ preimage=preimage,
+ fee_msat=0,
+ payment_request="lni1resolvedinvoice",
+ )
+
+ backend = AsyncMock(side_effect=pay)
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ first, retry = await asyncio.gather(
+ *(
+ pay_offer(
+ wallet_id=offer_wallet.id,
+ offer=BOLT12_OFFER,
+ amount_sat=100,
+ external_id="order-1",
+ )
+ for _ in range(2)
+ )
+ )
+
+ backend.assert_awaited_once()
+ assert retry.payment_hash == first.payment_hash
+ assert retry.checking_id == first.checking_id
+ assert retry.status == first.status
+ assert first.success if state == "success" else first.pending
+ assert len(await get_payments(wallet_id=offer_wallet.id, outgoing=True)) == 1
+ after = await get_wallet(offer_wallet.id)
+ assert after and after.balance_msat == (900_000 if state == "success" else 880_000)
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+ "changed",
+ [
+ {"offer": BOLT12_OFFER_WITH_DESCRIPTION},
+ {"amount_sat": 101},
+ {"memo": "A different note"},
+ ],
+)
+async def test_offer_retry_rejects_changed_details(offer_wallet, monkeypatch, changed):
+ backend = AsyncMock(wraps=FakeWallet().pay_offer)
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ request = {
+ "wallet_id": offer_wallet.id,
+ "offer": BOLT12_OFFER,
+ "amount_sat": 100,
+ "memo": "Thanks",
+ "external_id": "order-1",
+ }
+ await pay_offer(**request)
+ with pytest.raises(PaymentError, match="External ID already used"):
+ await pay_offer(**{**request, **changed})
+ backend.assert_awaited_once()
+
+
+@pytest.mark.anyio
+async def test_failed_offer_retry_does_not_resend(offer_wallet, monkeypatch):
+ backend = AsyncMock(return_value=PaymentResponse(ok=False))
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ request = {
+ "wallet_id": offer_wallet.id,
+ "offer": BOLT12_OFFER,
+ "amount_sat": 100,
+ "external_id": "order-1",
+ }
+ with pytest.raises(PaymentError, match="Payment failed"):
+ await pay_offer(**request)
+ with pytest.raises(PaymentError, match="Use a new external_id to retry"):
+ await pay_offer(**request)
+ backend.assert_awaited_once()
+
+ # A new ID explicitly requests another attempt.
+ with pytest.raises(PaymentError, match="Payment failed"):
+ await pay_offer(**{**request, "external_id": "order-2"})
+ assert backend.await_count == 2
+ after = await get_wallet(offer_wallet.id)
+ assert after and after.balance_msat == 1_000_000
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("second_id", ["order-2", None, ""])
+async def test_offer_can_be_paid_again_with_new_or_missing_id(
+ offer_wallet, monkeypatch, second_id
+):
+ backend = AsyncMock(wraps=FakeWallet().pay_offer)
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ payments = [
+ await pay_offer(
+ wallet_id=offer_wallet.id,
+ offer=BOLT12_OFFER,
+ amount_sat=100,
+ external_id=external_id,
+ )
+ for external_id in ("order-1" if second_id else second_id, second_id)
+ ]
+ assert backend.await_count == 2
+ assert payments[0].payment_hash != payments[1].payment_hash
+
+
+@pytest.mark.anyio
+async def test_offer_external_id_is_scoped_to_outgoing_wallet_payments(
+ offer_wallet, monkeypatch
+):
+ other_wallet = await create_wallet(user_id=offer_wallet.user)
+ await update_wallet_balance(other_wallet, 1000)
+ _, payment_hash = random_secret_and_hash()
+ await create_payment(
+ checking_id=payment_hash,
+ data=CreatePayment(
+ wallet_id=offer_wallet.id,
+ payment_hash=payment_hash,
+ bolt11="",
+ amount_msat=100_000,
+ memo="Incoming payment with the same reference",
+ external_id="order-1",
+ ),
+ status=PaymentState.SUCCESS,
+ )
+ backend = AsyncMock(wraps=FakeWallet().pay_offer)
+ monkeypatch.setattr(FakeWallet, "pay_offer", backend)
+ payments = [
+ await pay_offer(
+ wallet_id=wallet.id,
+ offer=BOLT12_OFFER,
+ amount_sat=100,
+ external_id="order-1",
+ )
+ for wallet in (offer_wallet, other_wallet)
+ ]
+ assert backend.await_count == 2
+ assert payments[0].payment_hash != payments[1].payment_hashWhy this scored 60/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.