feat: billing email notifications + per-merchant fee rates

Pre-referral billing infrastructure:
- Per-merchant fee_rate column (nullable, falls back to global config)
- fee_rate_applied recorded on each fee_ledger entry for audit trail
- fee_discount_until column for time-limited referral discounts
- email_events table for idempotent billing email delivery
- 7 billing email templates (settlement, reminder, past due, suspended,
  payment confirmed, discount expiry warning, discount expired)
- Emails hooked into process_billing_cycles and check_settlement_payments
- Automated discount expiry + 7-day warning in billing loop
- Admin test-email endpoint for verifying email delivery post-deploy

Author: Kenbak

ROADMAP.md

@@ -174,6 +174,7 @@ Privacy-preserving Zcash payment gateway. Non-custodial, shielded-only.
   - Cron job with cryptographic erasure (not just NULL, but overwrite)
   - Zero-knowledge order fulfillment: merchant gets shipping label, not raw address
 - [ ] **PostgreSQL migration** for production (multi-tenant, proper indexing)
+  - [ ] Separate `settlement_invoices` table from `invoices` — settlement invoices (bills from CipherPay to merchants) currently share the `invoices` table for scanner pipeline reuse; split into dedicated table with shared detection trait during Postgres migration
 - [ ] **Read/write role separation after Postgres** — reserve migration path for scanner-heavy reads, webhook writes, and dashboard queries so one hot connection pool does not do everything
 - [ ] **Multi-node CipherScan infrastructure**
   - Load balancer in front of multiple Zebra nodes
@@ -258,6 +259,7 @@ Privacy-preserving Zcash payment gateway. Non-custodial, shielded-only.
   - Enterprise: dedicated infrastructure, SLA, custom integrations
 - [ ] API key rate limiting per tier
 - [ ] Merchant dashboard (invoice history, analytics, webhook logs)
+- [ ] **Billing export** — CSV/PDF export of billing cycles and settlement invoices for accounting
 - [ ] Multi-merchant management (agencies managing multiple stores)
 - [ ] **Evaluate `mpp-rs` crate adoption** — replace custom MPP challenge/credential handling in `@cipherpay/x402` with the first-party [mpp-rs](https://github.com/nicholasgasior/mpp) Rust crate
   - Reduces protocol maintenance burden as MPP spec evolves

src/api/admin.rs

@@ -1,5 +1,6 @@
 use actix_web::web;
 use hmac::{Hmac, Mac};
+use serde::Deserialize;
 use sha2::Sha256;
 use sqlx::SqlitePool;
 use subtle::ConstantTimeEq;
@@ -517,3 +518,144 @@ pub async fn system(
         "fee_rate": config.fee_rate,
     }))
 }
+
+#[derive(Deserialize)]
+pub struct TestEmailRequest {
+    pub to: String,
+    pub template: Option<String>,
+}
+
+/// POST /api/admin/test-email -- send a test billing email to verify email delivery
+pub async fn test_email(
+    req: actix_web::HttpRequest,
+    pool: web::Data<SqlitePool>,
+    config: web::Data<crate::config::Config>,
+    body: web::Json<TestEmailRequest>,
+) -> actix_web::HttpResponse {
+    if !authenticate_admin(&req) {
+        return unauthorized();
+    }
+
+    if !config.smtp_configured() {
+        return actix_web::HttpResponse::BadRequest().json(serde_json::json!({
+            "error": "Email not configured (SMTP_FROM and SMTP_PASS required)"
+        }));
+    }
+
+    let template = body.template.as_deref().unwrap_or("settlement_invoice");
+    let test_cycle_id = "test-email-verification";
+
+    // Delete any previous test email event so the test can be repeated
+    sqlx::query("DELETE FROM email_events WHERE merchant_id = 'test' AND entity_id = ?")
+        .bind(test_cycle_id)
+        .execute(pool.get_ref())
+        .await
+        .ok();
+
+    let result = match template {
+        "settlement_invoice" => {
+            crate::email::send_settlement_invoice_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                test_cycle_id,
+                0.12345678,
+                "2026-04-20T00:00:00Z",
+                7,
+            )
+            .await
+        }
+        "grace_reminder" => {
+            crate::email::send_billing_reminder_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                test_cycle_id,
+                0.12345678,
+                "2026-04-20T00:00:00Z",
+                3,
+            )
+            .await
+        }
+        "past_due" => {
+            crate::email::send_past_due_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                test_cycle_id,
+                0.12345678,
+            )
+            .await
+        }
+        "suspended" => {
+            crate::email::send_suspended_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                test_cycle_id,
+                0.12345678,
+            )
+            .await
+        }
+        "payment_confirmed" => {
+            crate::email::send_payment_confirmed_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                test_cycle_id,
+            )
+            .await
+        }
+        "discount_expiry_warning" => {
+            crate::email::send_discount_expiry_warning_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                0.01,
+                "2026-04-20",
+            )
+            .await
+        }
+        "discount_expired" => {
+            crate::email::send_discount_expired_email(
+                pool.get_ref(),
+                &config,
+                &body.to,
+                "test",
+                0.01,
+            )
+            .await
+        }
+        _ => {
+            return actix_web::HttpResponse::BadRequest().json(serde_json::json!({
+                "error": "Unknown template",
+                "valid_templates": [
+                    "settlement_invoice", "grace_reminder", "past_due",
+                    "suspended", "payment_confirmed",
+                    "discount_expiry_warning", "discount_expired"
+                ]
+            }));
+        }
+    };
+
+    match result {
+        Ok(true) => actix_web::HttpResponse::Ok().json(serde_json::json!({
+            "sent": true,
+            "template": template,
+            "to": body.to,
+        })),
+        Ok(false) => actix_web::HttpResponse::Ok().json(serde_json::json!({
+            "sent": false,
+            "reason": "Skipped (idempotency or no email configured)"
+        })),
+        Err(e) => actix_web::HttpResponse::InternalServerError().json(serde_json::json!({
+            "error": format!("Email send failed: {}", e)
+        })),
+    }
+}

src/api/mod.rs

@@ -194,7 +194,8 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
             .route("/admin/merchants", web::get().to(admin::merchants))
             .route("/admin/billing", web::get().to(admin::billing))
             .route("/admin/webhooks", web::get().to(admin::webhooks))
-            .route("/admin/system", web::get().to(admin::system)),
+            .route("/admin/system", web::get().to(admin::system))
+            .route("/admin/test-email", web::post().to(admin::test_email)),
     );
 
     cfg.route("/.well-known/payment", web::get().to(well_known_payment));