feat: invoice payment flow for paid relays

backend/spec/billing.md

@@ -29,12 +29,11 @@ Manages the Stripe subscription and subscription items for a relay's tenant. Onl
 Stripe uses **pay-in-advance** by default: when a subscription is first created, Stripe immediately generates an open invoice for the current period. The `invoice.created` webhook fires shortly after and `handle_invoice_created` attempts payment.
 
 - Fetch the relay and tenant associated with the `activity`
-- **If relay plan is `free`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then run downgrade proration validation by previewing the upcoming invoice and logging proration lines/amounts. Then check cleanup (below). Return early.
+- **If relay plan is `free`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
 - **If relay is `inactive` or `delinquent`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
 - **If relay is `active` and on a paid plan**:
   - **Ensure subscription exists**: If the tenant has no `stripe_subscription_id`, create a Stripe subscription for the customer with `collection_method: "charge_automatically"` and the relay's price as the first item. Save the subscription ID via `command.set_tenant_subscription` and the item ID via `command.set_relay_subscription_item`. Return early.
   - **Sync the subscription item**: If the tenant already has a subscription, create or update the relay's Stripe subscription item to the plan's `stripe_price_id` via the Stripe API, then call `command.set_relay_subscription_item`.
-  - **Downgrade validation**: when changing an existing subscription item, detect if the new plan amount is lower than the current one. If yes, preview the upcoming Stripe invoice and log proration line/amount details to validate expected credit/proration behavior.
 - **Clean up empty subscription**: After any item deletion, check if the tenant has any remaining active paid relays. If none and the tenant has a `stripe_subscription_id`, cancel the Stripe subscription immediately and call `command.clear_tenant_subscription`.
 
 ## `pub fn handle_webhook(&self, payload: &str, signature: &str) -> Result<()>`
@@ -47,7 +46,6 @@ Stripe uses **pay-in-advance** by default: when a subscription is first created,
   - `invoice.overdue` -> `self.handle_invoice_overdue`
   - `customer.subscription.updated` -> `self.handle_subscription_updated`
   - `customer.subscription.deleted` -> `self.handle_subscription_deleted`
-  - `payment_method.attached` -> `self.handle_payment_method_attached`
 - Unknown event types are ignored (return Ok)
 
 ## `pub async fn stripe_list_invoices(&self, customer_id: &str) -> Result<Value>`
@@ -81,16 +79,6 @@ Called when a tenant first sets their NWC URL (via `PUT /tenants/:pubkey`). Atte
   - On success: call `stripe_pay_invoice_out_of_band` and `command.clear_tenant_nwc_error`.
   - On failure: call `command.set_tenant_nwc_error` and log the error; continue to the next invoice.
 
-## `pub async fn pay_outstanding_card_invoices(&self, tenant: &Tenant) -> Result<()>`
-
-Attempts Stripe-side collection for open invoices when the tenant has a card on file.
-
-- If tenant has no card payment method, return early.
-- List all Stripe invoices for `tenant.stripe_customer_id`.
-- For each invoice with `status == "open"` and `amount_due > 0`:
-  - Call Stripe `POST /v1/invoices/:id/pay` to retry collection using the card on file.
-  - Log and continue on failures.
-
 ## `fn handle_invoice_created(&self, invoice: &Invoice)`
 
 Attempts to pay a new subscription invoice. Because Stripe defaults to pay-in-advance, this webhook fires immediately when a subscription is created (i.e. when a paid relay is added or a plan is upgraded). Payment priority:
@@ -100,7 +88,7 @@ Attempts to pay a new subscription invoice. Because Stripe defaults to pay-in-ad
    - Pay the bolt11 invoice using the tenant's `nwc_url` (the spending/tenant wallet)
    - If payment succeeds: call Stripe `POST /v1/invoices/:id/pay` with `paid_out_of_band: true`. Clear `nwc_error` via `command.clear_tenant_nwc_error`.
    - If payment fails: set `nwc_error` on tenant via `command.set_tenant_nwc_error`. Fall through to next option.
-2. **Card on file**: If the tenant has a payment method on the Stripe customer, do nothing here — Stripe will charge automatically for this invoice attempt.
+2. **Card on file**: If the tenant has a payment method on the Stripe customer, do nothing — Stripe will charge automatically.
 3. **Manual payment**: If neither NWC nor card is available, send a DM via `robot.send_dm` notifying the tenant that payment is due with a link to the application for manual Lightning payment.
 
 Skip invoices with `amount_due` of 0.
@@ -137,8 +125,3 @@ Skip invoices with `amount_due` of 0.
 
 - Look up tenant by `stripe_customer_id`
 - Clear `stripe_subscription_id` via `command.clear_tenant_subscription`
-
-## `fn handle_payment_method_attached(&self, stripe_customer_id: &str)`
-
-- Look up tenant by `stripe_customer_id`
-- Call `pay_outstanding_card_invoices` so invoices that were due before card setup are retried immediately

backend/src/billing.rs

@@ -167,8 +167,6 @@ impl Billing {
                 self.command
                     .delete_relay_subscription_item(&relay.id)
                     .await?;
-                self.validate_downgrade_proration(&tenant, "free-plan-downgrade")
-                    .await;
             }
             self.cleanup_empty_subscription(&tenant.pubkey).await?;
             return Ok(());
@@ -208,28 +206,8 @@ impl Billing {
         // Sync the subscription item: create or update
         let subscription_id = tenant.stripe_subscription_id.as_ref().unwrap();
         let item_id = if let Some(ref existing_item_id) = relay.stripe_subscription_item_id {
-            let is_downgrade = self
-                .is_subscription_item_downgrade(existing_item_id, plan.amount)
-                .await
-                .unwrap_or_else(|error| {
-                    tracing::warn!(
-                        error = %error,
-                        relay_id = %relay.id,
-                        "failed to determine relay plan downgrade direction"
-                    );
-                    false
-                });
-
-            let updated_item_id = self
-                .stripe_update_subscription_item(existing_item_id, stripe_price_id)
-                .await?;
-
-            if is_downgrade {
-                self.validate_downgrade_proration(&tenant, "paid-plan-downgrade")
-                    .await;
-            }
-
-            updated_item_id
+            self.stripe_update_subscription_item(existing_item_id, stripe_price_id)
+                .await?
         } else {
             self.stripe_create_subscription_item(subscription_id, stripe_price_id)
                 .await?
@@ -297,10 +275,6 @@ impl Billing {
                 let customer = obj["customer"].as_str().unwrap_or_default();
                 self.handle_subscription_deleted(customer).await?;
             }
-            "payment_method.attached" => {
-                let customer = obj["customer"].as_str().unwrap_or_default();
-                self.handle_payment_method_attached(customer).await?;
-            }
             _ => {}
         }
 
@@ -518,103 +492,6 @@ impl Billing {
         Ok(())
     }
 
-    async fn handle_payment_method_attached(&self, stripe_customer_id: &str) -> Result<()> {
-        if stripe_customer_id.is_empty() {
-            return Ok(());
-        }
-
-        let Some(tenant) = self
-            .query
-            .get_tenant_by_stripe_customer_id(stripe_customer_id)
-            .await?
-        else {
-            return Ok(());
-        };
-
-        self.pay_outstanding_card_invoices(&tenant).await?;
-        Ok(())
-    }
-
-    async fn is_subscription_item_downgrade(
-        &self,
-        item_id: &str,
-        next_plan_amount: i64,
-    ) -> Result<bool> {
-        let Some(current_price_id) = self.stripe_get_subscription_item_price_id(item_id).await?
-        else {
-            return Ok(false);
-        };
-
-        let Some(current_plan_amount) = Self::plan_amount_from_price_id(&current_price_id) else {
-            return Ok(false);
-        };
-
-        Ok(next_plan_amount < current_plan_amount)
-    }
-
-    fn plan_amount_from_price_id(price_id: &str) -> Option<i64> {
-        Query::list_plans().into_iter().find_map(|plan| {
-            if plan.stripe_price_id.as_deref() == Some(price_id) {
-                Some(plan.amount)
-            } else {
-                None
-            }
-        })
-    }
-
-    async fn validate_downgrade_proration(&self, tenant: &crate::models::Tenant, context: &str) {
-        match self
-            .stripe_preview_upcoming_invoice(
-                &tenant.stripe_customer_id,
-                tenant.stripe_subscription_id.as_deref(),
-            )
-            .await
-        {
-            Ok(upcoming) => {
-                let lines = upcoming["lines"]["data"]
-                    .as_array()
-                    .cloned()
-                    .unwrap_or_default();
-                let proration_lines = lines
-                    .iter()
-                    .filter(|line| line["proration"].as_bool().unwrap_or(false))
-                    .count();
-                let amount_due = upcoming["amount_due"]
-                    .as_i64()
-                    .unwrap_or_else(|| upcoming["total"].as_i64().unwrap_or(0));
-                let currency = upcoming["currency"].as_str().unwrap_or("usd");
-                let preview_id = upcoming["id"].as_str().unwrap_or_default();
-
-                tracing::info!(
-                    tenant_pubkey = %tenant.pubkey,
-                    stripe_customer_id = %tenant.stripe_customer_id,
-                    context,
-                    preview_id,
-                    proration_lines,
-                    amount_due,
-                    currency,
-                    "validated Stripe proration preview for downgrade"
-                );
-
-                if proration_lines == 0 {
-                    tracing::warn!(
-                        tenant_pubkey = %tenant.pubkey,
-                        context,
-                        "downgrade proration preview has no proration lines; verify in Stripe dashboard"
-                    );
-                }
-            }
-            Err(error) => {
-                tracing::warn!(
-                    error = %error,
-                    tenant_pubkey = %tenant.pubkey,
-                    context,
-                    "failed to fetch downgrade proration preview"
-                );
-            }
-        }
-    }
-
     // --- Public API helpers ---
 
     pub async fn get_invoice_with_tenant(
@@ -722,7 +599,10 @@ impl Billing {
         Ok(invoice_response.invoice)
     }
 
-    pub async fn pay_outstanding_nwc_invoices(&self, tenant: &crate::models::Tenant) -> Result<()> {
+    pub async fn pay_outstanding_nwc_invoices(
+        &self,
+        tenant: &crate::models::Tenant,
+    ) -> Result<()> {
         if tenant.nwc_url.is_empty() {
             return Ok(());
         }
@@ -775,40 +655,6 @@ impl Billing {
         Ok(())
     }
 
-    async fn pay_outstanding_card_invoices(&self, tenant: &crate::models::Tenant) -> Result<()> {
-        if !self
-            .stripe_has_payment_method(&tenant.stripe_customer_id)
-            .await?
-        {
-            return Ok(());
-        }
-
-        let invoices = self
-            .stripe_list_invoices(&tenant.stripe_customer_id)
-            .await?;
-        let invoices_arr = invoices.as_array().cloned().unwrap_or_default();
-
-        for invoice in &invoices_arr {
-            let status = invoice["status"].as_str().unwrap_or_default();
-            let amount_due = invoice["amount_due"].as_i64().unwrap_or(0);
-            let invoice_id = invoice["id"].as_str().unwrap_or_default();
-
-            if status != "open" || amount_due == 0 || invoice_id.is_empty() {
-                continue;
-            }
-
-            if let Err(error) = self.stripe_pay_invoice(invoice_id).await {
-                tracing::error!(
-                    error = %error,
-                    invoice_id,
-                    "failed to retry card payment for outstanding invoice"
-                );
-            }
-        }
-
-        Ok(())
-    }
-
     pub async fn stripe_create_portal_session(&self, customer_id: &str) -> Result<String> {
         let resp = self
             .http
@@ -925,48 +771,6 @@ impl Billing {
         Ok(())
     }
 
-    async fn stripe_pay_invoice(&self, invoice_id: &str) -> Result<()> {
-        self.http
-            .post(format!("{STRIPE_API}/invoices/{invoice_id}/pay"))
-            .bearer_auth(&self.stripe_secret_key)
-            .send()
-            .await?
-            .error_for_status()?;
-
-        Ok(())
-    }
-
-    async fn stripe_get_subscription_item_price_id(&self, item_id: &str) -> Result<Option<String>> {
-        let resp = self
-            .http
-            .get(format!("{STRIPE_API}/subscription_items/{item_id}"))
-            .bearer_auth(&self.stripe_secret_key)
-            .send()
-            .await?;
-
-        let body: serde_json::Value = resp.error_for_status()?.json().await?;
-        Ok(body["price"]["id"].as_str().map(ToString::to_string))
-    }
-
-    async fn stripe_preview_upcoming_invoice(
-        &self,
-        customer_id: &str,
-        subscription_id: Option<&str>,
-    ) -> Result<serde_json::Value> {
-        let mut req = self
-            .http
-            .get(format!("{STRIPE_API}/invoices/upcoming"))
-            .bearer_auth(&self.stripe_secret_key)
-            .query(&[("customer", customer_id)]);
-
-        if let Some(subscription_id) = subscription_id {
-            req = req.query(&[("subscription", subscription_id)]);
-        }
-
-        let body: serde_json::Value = req.send().await?.error_for_status()?.json().await?;
-        Ok(body)
-    }
-
     async fn stripe_pay_invoice_out_of_band(&self, invoice_id: &str) -> Result<()> {
         self.http
             .post(format!("{STRIPE_API}/invoices/{invoice_id}/pay"))
@@ -1057,6 +861,16 @@ impl Billing {
     }
 
     async fn fetch_btc_spot_price(&self, currency: &str) -> Result<f64> {
+        // BTC_PRICE_USD_OVERRIDE bypasses the external price API entirely.
+        // Set this to a fixed USD/BTC rate (e.g. "97000") for local testing
+        // when Coinbase is unreachable. Remove or leave unset in production.
+        if let Ok(val) = std::env::var("BTC_PRICE_USD_OVERRIDE") {
+            let price = val
+                .trim()
+                .parse::<f64>()
+                .map_err(|e| anyhow!("invalid BTC_PRICE_USD_OVERRIDE: {e}"))?;
+            return Ok(price);
+        }
         fetch_btc_spot_price_from_base(&self.http, &self.btc_quote_api_base, currency).await
     }
 

frontend/src/components/PaymentDialog.tsx

@@ -3,6 +3,7 @@ import QRCode from "qrcode"
 import Modal from "@/components/Modal"
 import PaymentSetup from "@/components/PaymentSetup"
 import { getInvoice, getInvoiceBolt11 } from "@/lib/api"
+import { tenantNeedsPaymentSetup } from "@/lib/hooks"
 
 type PayStatus = "idle" | "loading" | "success" | "error"
 type Bolt11Status = "idle" | "loading" | "ready" | "error"
@@ -25,6 +26,7 @@ export default function PaymentDialog(props: PaymentDialogProps) {
   const [bolt11Error, setBolt11Error] = createSignal("")
   const [payStatus, setPayStatus] = createSignal<PayStatus>("idle")
   const [payError, setPayError] = createSignal("")
+  const [showSetup, setShowSetup] = createSignal(false)
   const [showPaymentSetup, setShowPaymentSetup] = createSignal(false)
   const [setupSaved, setSetupSaved] = createSignal(false)
 
@@ -62,6 +64,7 @@ export default function PaymentDialog(props: PaymentDialogProps) {
       const invoice = await getInvoice(props.invoice.id)
       if (invoice.status === "paid") {
         setPayStatus("success")
+        tenantNeedsPaymentSetup().then(needs => setShowSetup(needs)).catch(() => {})
       } else {
         setPayStatus("error")
         setPayError("Payment not yet confirmed. Please try again after sending.")
@@ -79,6 +82,7 @@ export default function PaymentDialog(props: PaymentDialogProps) {
     setBolt11Error("")
     setBolt11("")
     setQrDataUrl("")
+    setShowSetup(false)
     props.onClose()
   }
 
@@ -178,13 +182,15 @@ export default function PaymentDialog(props: PaymentDialogProps) {
             </div>
             <p class="text-sm font-medium text-gray-900">Payment confirmed!</p>
             <p class="text-xs text-gray-500">Thank you. Your account is up to date.</p>
-            <button
-              type="button"
-              onClick={() => setShowPaymentSetup(true)}
-              class="mt-2 text-sm font-medium text-blue-600 hover:text-blue-700"
-            >
-              Set up automatic payments
-            </button>
+            <Show when={showSetup()}>
+              <button
+                type="button"
+                onClick={() => setShowPaymentSetup(true)}
+                class="mt-2 text-sm font-medium text-blue-600 hover:text-blue-700"
+              >
+                Set up automatic payments
+              </button>
+            </Show>
           </div>
         </Show>
       </div>

frontend/src/components/PaymentSetup.tsx

@@ -146,7 +146,7 @@ export default function PaymentSetup(props: PaymentSetupProps) {
                 <line x1="1" y1="10" x2="23" y2="10" />
               </svg>
             </div>
-            <p class="text-sm text-gray-600">Add a payment card via Stripe to enable automatic billing. If an invoice is currently due, we will retry collection after card setup.</p>
+            <p class="text-sm text-gray-600">Add a payment card via Stripe to enable automatic billing once invoices are issued.</p>
             <button
               type="button"
               onClick={openPortal}