feat: invoice payment flow for paid relays

backend/spec/billing.md

@@ -26,6 +26,8 @@ Members:
 
 Manages the Stripe subscription and subscription items for a relay's tenant. Only paid (non-free) relays interact with Stripe. Free-only tenants have no subscription. Must be idempotent.
 
+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 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.
@@ -66,9 +68,20 @@ Manages the Stripe subscription and subscription items for a relay's tenant. Onl
 - Creates a Stripe Customer Portal session for the given customer
 - Returns the portal session URL
 
+## `pub async fn pay_outstanding_nwc_invoices(&self, tenant: &Tenant) -> Result<()>`
+
+Called when a tenant first sets their NWC URL (via `PUT /tenants/:pubkey`). Attempts to pay any currently open invoices for the tenant using their NWC wallet, so that invoices created before NWC was configured are not left unpaid.
+
+- If `tenant.nwc_url` is empty, return early.
+- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe_list_invoices`.
+- For each invoice with `status == "open"` and `amount_due > 0`:
+  - Attempt NWC payment via `nwc_pay_invoice`.
+  - 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.
+
 ## `fn handle_invoice_created(&self, invoice: &Invoice)`
 
-Attempts to pay a new subscription invoice. Payment priority:
+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:
 
 1. **NWC auto-pay**: If the tenant has a `nwc_url`:
    - Create a bolt11 Lightning invoice for the invoice amount using `self.nwc_url` (the receiving/system wallet)

backend/src/api.rs

@@ -945,12 +945,29 @@ async fn update_tenant(
     state.api.require_admin_or_tenant(&auth, &pubkey)?;
     let mut tenant = state.api.get_tenant_or_404(&pubkey).await?;
 
+    let nwc_previously_empty = tenant.nwc_url.is_empty();
     if let Some(nwc_url) = payload.nwc_url {
         tenant.nwc_url = nwc_url;
     }
 
     match state.api.command.update_tenant(&tenant).await {
-        Ok(()) => Ok(ok(StatusCode::OK, tenant)),
+        Ok(()) => {
+            // When NWC is first connected, attempt to pay any outstanding open invoices.
+            if nwc_previously_empty && !tenant.nwc_url.is_empty() {
+                let billing = state.api.billing.clone();
+                let tenant_clone = tenant.clone();
+                tokio::spawn(async move {
+                    if let Err(e) = billing.pay_outstanding_nwc_invoices(&tenant_clone).await {
+                        tracing::error!(
+                            error = %e,
+                            pubkey = %tenant_clone.pubkey,
+                            "pay_outstanding_nwc_invoices failed after NWC setup"
+                        );
+                    }
+                });
+            }
+            Ok(ok(StatusCode::OK, tenant))
+        }
         Err(e) => Ok(err(
             StatusCode::INTERNAL_SERVER_ERROR,
             "internal",

backend/src/billing.rs

@@ -599,6 +599,62 @@ impl Billing {
         Ok(invoice_response.invoice)
     }
 
+    pub async fn pay_outstanding_nwc_invoices(
+        &self,
+        tenant: &crate::models::Tenant,
+    ) -> Result<()> {
+        if tenant.nwc_url.is_empty() {
+            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();
+            let currency = invoice["currency"].as_str().unwrap_or("usd");
+
+            if status != "open" || amount_due == 0 || invoice_id.is_empty() {
+                continue;
+            }
+
+            match self
+                .nwc_pay_invoice(amount_due, currency, &tenant.nwc_url)
+                .await
+            {
+                Ok(()) => {
+                    if let Err(e) = self.stripe_pay_invoice_out_of_band(invoice_id).await {
+                        tracing::error!(
+                            error = %e,
+                            invoice_id,
+                            "failed to mark invoice paid out of band"
+                        );
+                    } else {
+                        let _ = self.command.clear_tenant_nwc_error(&tenant.pubkey).await;
+                    }
+                }
+                Err(e) => {
+                    let error_msg = format!("{e}");
+                    tracing::error!(
+                        error = %e,
+                        invoice_id,
+                        "nwc payment failed for outstanding invoice"
+                    );
+                    let _ = self
+                        .command
+                        .set_tenant_nwc_error(&tenant.pubkey, &error_msg)
+                        .await;
+                }
+            }
+        }
+
+        Ok(())
+    }
+
     pub async fn stripe_create_portal_session(&self, customer_id: &str) -> Result<String> {
         let resp = self
             .http
@@ -805,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
     }