fix(payments): record-payment fails closed and shares the claim gate

Two fixes to POST /api/v1/record-payment:

- The Fava duplicate check caught every exception and proceeded to
  write, so a transient Fava blip produced double entries. It now
  fails closed: transport errors return 503 and the client retries.
  While here: the check queried {base_url}/api/journal, but base_url
  already ends in /api — the doubled path 404'd, meaning the
  duplicate check has silently never run.

- The endpoint now goes through the same processed_payments claim
  gate as the background invoice listener, so the webhook+poller pair
  can't both record the same payment_hash: a 'done' claim replays as
  "already recorded", an in-flight claim returns 409.

Addresses CODE-REVIEW-2026-06 finding #10.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

views_api.py

@@ -1850,90 +1850,130 @@ async def api_record_payment(
 
     try:
         async with httpx.AsyncClient(timeout=5.0) as client:
-            # Get recent entries from Fava's journal endpoint
+            # Get recent entries from Fava's journal endpoint. base_url
+            # already ends in /api — the previous "/api/journal" path
+            # 404'd, so this duplicate check silently never ran.
             response = await client.get(
-                f"{fava.base_url}/api/journal",
+                f"{fava.base_url}/journal",
                 params={"time": ""}  # Get all entries
             )
+            response.raise_for_status()
+            response_data = response.json()
+            entries = response_data.get('entries', [])
 
-            if response.status_code == 200:
-                response_data = response.json()
-                entries = response_data.get('entries', [])
-
-                # Check if any entry has our payment link
-                for entry in entries:
-                    entry_links = entry.get('links', [])
-                    if link_to_find in entry_links:
-                        # Payment already recorded, return existing entry
-                        balance_data = await fava.get_user_balance_bql(target_user_id)
-                        return {
-                            "journal_entry_id": f"fava-exists-{data.payment_hash[:16]}",
-                            "new_balance": balance_data["balance"],
-                            "message": "Payment already recorded",
-                        }
-    except Exception as e:
+            # Check if any entry has our payment link
+            for entry in entries:
+                entry_links = entry.get('links', [])
+                if link_to_find in entry_links:
+                    # Payment already recorded, return existing entry
+                    balance_data = await fava.get_user_balance_bql(target_user_id)
+                    return {
+                        "journal_entry_id": f"fava-exists-{data.payment_hash[:16]}",
+                        "new_balance": balance_data["balance"],
+                        "message": "Payment already recorded",
+                    }
+    except httpx.HTTPError as e:
+        # Fail CLOSED: if Fava can't confirm the payment isn't already
+        # recorded, refuse to write — proceeding on a transient blip is
+        # how double entries happen. The client can simply retry.
         logger.warning(f"Could not check Fava for duplicate payment: {e}")
-        # Continue anyway - Fava/Beancount will catch duplicate if it exists
-
-    # Convert amount from millisatoshis to satoshis
-    amount_sats = payment.amount // 1000
-
-    # Extract fiat metadata from invoice (if present)
-    fiat_currency = None
-    fiat_amount = None
-    if payment.extra and isinstance(payment.extra, dict):
-        logger.info(f"Payment.extra contents: {payment.extra}")
-        fiat_currency = payment.extra.get("fiat_currency")
-        fiat_amount_str = payment.extra.get("fiat_amount")
-        if fiat_amount_str:
-            from decimal import Decimal
-            fiat_amount = Decimal(str(fiat_amount_str))
-
-    logger.info(f"Extracted fiat metadata - currency: {fiat_currency}, amount: {fiat_amount}")
-
-    # Get user's receivable account (what user owes)
-    user_receivable = await get_or_create_user_account(
-        target_user_id, AccountType.ASSET, "Accounts Receivable"
-    )
-
-    # Get lightning account
-    lightning_account = await get_account_by_name("Assets:Bitcoin:Lightning")
-    if not lightning_account:
         raise HTTPException(
-            status_code=HTTPStatus.NOT_FOUND, detail="Lightning account not found"
+            status_code=HTTPStatus.SERVICE_UNAVAILABLE,
+            detail="Cannot verify payment duplicate status; try again shortly",
         )
 
-    # Get unsettled receivable entries to link to this settlement
-    unsettled = await fava.get_unsettled_entries_bql(target_user_id, "receivable")
-    settled_links = [e["link"] for e in unsettled if e.get("link")]
-
-    # Format payment entry and submit to Fava
-    entry = format_payment_entry(
-        user_id=target_user_id,
-        payment_account=lightning_account.name,
-        payable_or_receivable_account=user_receivable.name,
-        amount_sats=amount_sats,
-        description=f"Lightning payment from user {target_user_id[:8]}",
-        entry_date=datetime.now().date(),
-        is_payable=False,  # User paying libra (receivable settlement)
-        fiat_currency=fiat_currency,
-        fiat_amount=fiat_amount,
-        payment_hash=data.payment_hash,
-        reference=data.payment_hash,
-        settled_entry_links=settled_links
+    # Local idempotency gate shared with the background invoice listener
+    # (tasks.on_invoice_paid): exactly one claimant records a payment_hash.
+    from .crud import (
+        claim_payment,
+        get_processed_payment,
+        mark_payment_done,
+        release_payment_claim,
     )
 
-    logger.info(f"Formatted payment entry: {entry}")
+    if not await claim_payment(data.payment_hash):
+        existing = await get_processed_payment(data.payment_hash)
+        if existing and existing["status"] == "done":
+            balance_data = await fava.get_user_balance_bql(target_user_id)
+            return {
+                "journal_entry_id": existing.get("entry_id")
+                or f"fava-exists-{data.payment_hash[:16]}",
+                "new_balance": balance_data["balance"],
+                "message": "Payment already recorded",
+            }
+        raise HTTPException(
+            status_code=HTTPStatus.CONFLICT,
+            detail="Payment is being recorded; check balance shortly",
+        )
 
-    # Submit to Fava
-    result = await fava.add_entry(entry)
-    logger.info(f"Payment entry submitted to Fava: {result.get('data', 'Unknown')}")
+    # Convert amount from millisatoshis to satoshis
+    try:
+        amount_sats = payment.amount // 1000
+
+        # Extract fiat metadata from invoice (if present)
+        fiat_currency = None
+        fiat_amount = None
+        if payment.extra and isinstance(payment.extra, dict):
+            logger.info(f"Payment.extra contents: {payment.extra}")
+            fiat_currency = payment.extra.get("fiat_currency")
+            fiat_amount_str = payment.extra.get("fiat_amount")
+            if fiat_amount_str:
+                from decimal import Decimal
+                fiat_amount = Decimal(str(fiat_amount_str))
+
+        logger.info(f"Extracted fiat metadata - currency: {fiat_currency}, amount: {fiat_amount}")
+
+        # Get user's receivable account (what user owes)
+        user_receivable = await get_or_create_user_account(
+            target_user_id, AccountType.ASSET, "Accounts Receivable"
+        )
+
+        # Get lightning account
+        lightning_account = await get_account_by_name("Assets:Bitcoin:Lightning")
+        if not lightning_account:
+            raise HTTPException(
+                status_code=HTTPStatus.NOT_FOUND, detail="Lightning account not found"
+            )
+
+        # Get unsettled receivable entries to link to this settlement
+        unsettled = await fava.get_unsettled_entries_bql(target_user_id, "receivable")
+        settled_links = [e["link"] for e in unsettled if e.get("link")]
+
+        # Format payment entry and submit to Fava
+        entry = format_payment_entry(
+            user_id=target_user_id,
+            payment_account=lightning_account.name,
+            payable_or_receivable_account=user_receivable.name,
+            amount_sats=amount_sats,
+            description=f"Lightning payment from user {target_user_id[:8]}",
+            entry_date=datetime.now().date(),
+            is_payable=False,  # User paying libra (receivable settlement)
+            fiat_currency=fiat_currency,
+            fiat_amount=fiat_amount,
+            payment_hash=data.payment_hash,
+            reference=data.payment_hash,
+            settled_entry_links=settled_links
+        )
+
+        logger.info(f"Formatted payment entry: {entry}")
+
+        # Submit to Fava
+        result = await fava.add_entry(entry)
+        logger.info(f"Payment entry submitted to Fava: {result.get('data', 'Unknown')}")
+
+        entry_id = f"ln-{data.payment_hash[:16]}"
+        await mark_payment_done(data.payment_hash, entry_id)
+    except BaseException:
+        # Release the claim so a retry (client or background listener)
+        # can record this payment.
+        await release_payment_claim(data.payment_hash)
+        raise
 
     # Get updated balance from Fava
     balance_data = await fava.get_user_balance_bql(target_user_id)
 
     return {
-        "journal_entry_id": f"fava-{datetime.now().timestamp()}",
+        "journal_entry_id": entry_id,
         "new_balance": balance_data["balance"],
         "message": "Payment recorded successfully",
     }