feat: add payment links and checkout success_url

Payment Links: reusable no-code URLs tied to a price — each visit
creates a fresh invoice with unique address/memo, redirects to checkout.
CRUD API with rate-limited public resolve endpoint, dashboard tab,
slug-based routing. Includes abuse mitigations (rate limiting,
unpredictable slugs, active/inactive toggle).

Checkout API: add optional success_url field to POST /api/checkout,
return checkout_url in response with redirect baked in. Enables
single-API-call platform integrations (Luma, etc). Zero breaking
changes — field is optional, checkout_url is additive.

Author: Kenbak

.gitignore

@@ -5,3 +5,4 @@
 *.db
 *.db-shm
 *.db-wal
+ROADMAP-INTERNAL.md

ROADMAP.md

@@ -55,15 +55,19 @@ Privacy-preserving Zcash payment gateway. Non-custodial, shielded-only.
 
 ## Phase 3 -- Integrations & Go-to-Market
 
-- [ ] **Hosted checkout page** (`pay.cipherpay.app/{invoice_id}`)
+- [x] **Hosted checkout page** (`pay.cipherpay.app/{invoice_id}`)
   - Standalone payment page merchants can redirect to
   - Mobile-optimized with QR code and deep-link to Zashi/YWallet
-- [ ] **Shopify Custom App integration**
+  - Checkout API returns `checkout_url` with optional `success_url` redirect baked in
+- [x] **Shopify Custom App integration**
   - Merchant installs Custom App in Shopify admin
   - CipherPay marks orders as paid via Shopify Admin REST API
   - (`POST /admin/api/2024-10/orders/{id}/transactions.json`)
   - Avoids Shopify App Store approval process
-- [ ] **WooCommerce plugin** (WordPress/PHP webhook receiver)
+- [x] **WooCommerce plugin** (WordPress/PHP webhook receiver)
+- [x] **Payment Links (no-code)**
+  - Reusable URLs tied to a price — visit creates invoice, redirects to checkout
+  - Dashboard tab for managing links; public resolve endpoint with rate limiting
 - [ ] **Embeddable widget** (JS snippet for any website)
   - `<script src="https://pay.cipherpay.app/widget.js">`
   - Drop-in payment button with modal checkout

src/api/mod.rs

@@ -4,6 +4,7 @@ pub mod events;
 pub mod invoices;
 pub mod luma;
 pub mod merchants;
+pub mod payment_links;
 pub mod prices;
 pub mod products;
 pub mod rates;
@@ -84,6 +85,12 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
             .route("/subscriptions", web::post().to(subscriptions::create))
             .route("/subscriptions", web::get().to(subscriptions::list))
             .route("/subscriptions/{id}/cancel", web::post().to(subscriptions::cancel))
+            // Payment links (merchant auth)
+            .route("/payment-links", web::post().to(payment_links::create))
+            .route("/payment-links", web::get().to(payment_links::list))
+            .route("/payment-links/{id}", web::patch().to(payment_links::update))
+            .route("/payment-links/{id}", web::delete().to(payment_links::delete))
+            .route("/payment-links/{slug}/checkout", web::post().to(payment_links::resolve).wrap(Governor::new(&session_rate_limit)))
             // Buyer checkout (public)
             .route("/checkout", web::post().to(checkout))
             // Invoice endpoints (API key auth)
@@ -419,6 +426,17 @@ async fn checkout(
                     obj.insert("event_location".to_string(), serde_json::to_value(ctx.event_location).unwrap_or(serde_json::Value::Null));
                 }
                 obj.insert("is_luma".to_string(), serde_json::json!(is_luma_event));
+
+                let frontend_url = config.frontend_url.as_deref().unwrap_or("https://cipherpay.app");
+                let mut checkout_url = format!("{}/pay/{}", frontend_url, resp.invoice_id);
+                if let Some(ref url) = body.success_url {
+                    let encoded: String = url.chars().map(|c| match c {
+                        '&' | '=' | '?' | '#' | ' ' => format!("%{:02X}", c as u8),
+                        _ => c.to_string(),
+                    }).collect();
+                    checkout_url = format!("{}?return_url={}", checkout_url, encoded);
+                }
+                obj.insert("checkout_url".to_string(), serde_json::Value::String(checkout_url));
             }
             actix_web::HttpResponse::Created().json(payload)
         }
@@ -439,6 +457,7 @@ struct CheckoutRequest {
     refund_address: Option<String>,
     attendee_name: Option<String>,
     attendee_email: Option<String>,
+    success_url: Option<String>,
 }
 
 fn validate_checkout(req: &CheckoutRequest) -> Result<(), crate::validation::ValidationError> {
@@ -459,6 +478,14 @@ fn validate_checkout(req: &CheckoutRequest) -> Result<(), crate::validation::Val
             crate::validation::validate_zcash_address("refund_address", addr)?;
         }
     }
+    if let Some(ref url) = req.success_url {
+        crate::validation::validate_length("success_url", url, 2000)?;
+        if !url.starts_with("https://") && !url.starts_with("http://") {
+            return Err(crate::validation::ValidationError::invalid(
+                "success_url", "must be a valid HTTP(S) URL"
+            ));
+        }
+    }
     Ok(())
 }
 

src/api/payment_links.rs

@@ -0,0 +1,306 @@
+use actix_web::{web, HttpRequest, HttpResponse};
+use sqlx::SqlitePool;
+
+use crate::payment_links::{self, CreatePaymentLinkRequest, UpdatePaymentLinkRequest};
+use crate::validation;
+
+pub async fn create(
+    req: HttpRequest,
+    pool: web::Data<SqlitePool>,
+    body: web::Json<CreatePaymentLinkRequest>,
+) -> HttpResponse {
+    let merchant = match super::auth::resolve_merchant_or_session(&req, &pool).await {
+        Some(m) => m,
+        None => {
+            return HttpResponse::Unauthorized().json(serde_json::json!({
+                "error": "Not authenticated"
+            }));
+        }
+    };
+
+    if let Err(e) = validate_create(&body) {
+        return HttpResponse::BadRequest().json(e.to_json());
+    }
+
+    match payment_links::create_payment_link(pool.get_ref(), &merchant.id, &body).await {
+        Ok(link) => HttpResponse::Created().json(link_response(&link)),
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to create payment link");
+            HttpResponse::BadRequest().json(serde_json::json!({
+                "error": e.to_string()
+            }))
+        }
+    }
+}
+
+pub async fn list(
+    req: HttpRequest,
+    pool: web::Data<SqlitePool>,
+) -> HttpResponse {
+    let merchant = match super::auth::resolve_merchant_or_session(&req, &pool).await {
+        Some(m) => m,
+        None => {
+            return HttpResponse::Unauthorized().json(serde_json::json!({
+                "error": "Not authenticated"
+            }));
+        }
+    };
+
+    match payment_links::list_payment_links(pool.get_ref(), &merchant.id).await {
+        Ok(links) => {
+            let result: Vec<_> = links.iter().map(link_response).collect();
+            HttpResponse::Ok().json(result)
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to list payment links");
+            HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Internal error"
+            }))
+        }
+    }
+}
+
+pub async fn update(
+    req: HttpRequest,
+    pool: web::Data<SqlitePool>,
+    path: web::Path<String>,
+    body: web::Json<UpdatePaymentLinkRequest>,
+) -> HttpResponse {
+    let merchant = match super::auth::resolve_merchant_or_session(&req, &pool).await {
+        Some(m) => m,
+        None => {
+            return HttpResponse::Unauthorized().json(serde_json::json!({
+                "error": "Not authenticated"
+            }));
+        }
+    };
+
+    let link_id = path.into_inner();
+
+    if let Err(e) = validate_update(&body) {
+        return HttpResponse::BadRequest().json(e.to_json());
+    }
+
+    match payment_links::update_payment_link(pool.get_ref(), &link_id, &merchant.id, &body).await {
+        Ok(Some(link)) => HttpResponse::Ok().json(link_response(&link)),
+        Ok(None) => HttpResponse::NotFound().json(serde_json::json!({
+            "error": "Payment link not found"
+        })),
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to update payment link");
+            HttpResponse::BadRequest().json(serde_json::json!({
+                "error": e.to_string()
+            }))
+        }
+    }
+}
+
+pub async fn delete(
+    req: HttpRequest,
+    pool: web::Data<SqlitePool>,
+    path: web::Path<String>,
+) -> HttpResponse {
+    let merchant = match super::auth::resolve_merchant_or_session(&req, &pool).await {
+        Some(m) => m,
+        None => {
+            return HttpResponse::Unauthorized().json(serde_json::json!({
+                "error": "Not authenticated"
+            }));
+        }
+    };
+
+    let link_id = path.into_inner();
+
+    match payment_links::delete_payment_link(pool.get_ref(), &link_id, &merchant.id).await {
+        Ok(true) => HttpResponse::Ok().json(serde_json::json!({ "status": "deleted" })),
+        Ok(false) => HttpResponse::NotFound().json(serde_json::json!({
+            "error": "Payment link not found"
+        })),
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to delete payment link");
+            HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Internal error"
+            }))
+        }
+    }
+}
+
+/// Public endpoint: resolve a payment link by slug and create an invoice.
+/// Rate limited to prevent invoice flooding.
+pub async fn resolve(
+    pool: web::Data<SqlitePool>,
+    config: web::Data<crate::config::Config>,
+    price_service: web::Data<crate::invoices::pricing::PriceService>,
+    path: web::Path<String>,
+) -> HttpResponse {
+    let slug = path.into_inner();
+
+    let link = match payment_links::get_by_slug(pool.get_ref(), &slug).await {
+        Ok(Some(l)) if l.active == 1 => l,
+        Ok(Some(_)) => {
+            return HttpResponse::Gone().json(serde_json::json!({
+                "error": "This payment link is no longer active"
+            }));
+        }
+        Ok(None) => {
+            return HttpResponse::NotFound().json(serde_json::json!({
+                "error": "Payment link not found"
+            }));
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to resolve payment link");
+            return HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Internal error"
+            }));
+        }
+    };
+
+    let price = match crate::prices::get_price(pool.get_ref(), &link.price_id).await {
+        Ok(Some(p)) if p.active == 1 => p,
+        _ => {
+            return HttpResponse::Gone().json(serde_json::json!({
+                "error": "Price associated with this link is no longer active"
+            }));
+        }
+    };
+
+    let product = match crate::products::get_product(pool.get_ref(), &price.product_id).await {
+        Ok(Some(p)) if p.active == 1 => p,
+        _ => {
+            return HttpResponse::Gone().json(serde_json::json!({
+                "error": "Product associated with this link is no longer available"
+            }));
+        }
+    };
+
+    let merchant = match crate::merchants::get_merchant_by_id(
+        pool.get_ref(), &link.merchant_id, &config.encryption_key
+    ).await {
+        Ok(Some(m)) => m,
+        _ => {
+            return HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Merchant not found"
+            }));
+        }
+    };
+
+    if config.fee_enabled() {
+        if let Ok(status) = crate::billing::get_merchant_billing_status(pool.get_ref(), &merchant.id).await {
+            if status == "past_due" || status == "suspended" {
+                return HttpResponse::PaymentRequired().json(serde_json::json!({
+                    "error": "Merchant account has outstanding fees"
+                }));
+            }
+        }
+    }
+
+    let rates = match price_service.get_rates().await {
+        Ok(r) => r,
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to fetch ZEC rate for payment link");
+            return HttpResponse::ServiceUnavailable().json(serde_json::json!({
+                "error": "Price feed unavailable"
+            }));
+        }
+    };
+
+    let invoice_req = crate::invoices::CreateInvoiceRequest {
+        product_id: Some(product.id.clone()),
+        price_id: Some(price.id.clone()),
+        product_name: Some(product.name.clone()),
+        size: None,
+        amount: price.unit_amount,
+        currency: Some(price.currency.clone()),
+        refund_address: None,
+    };
+
+    let fee_config = if config.fee_enabled() {
+        config.fee_address.as_ref().map(|addr| crate::invoices::FeeConfig {
+            fee_address: addr.clone(),
+            fee_rate: config.fee_rate,
+        })
+    } else {
+        None
+    };
+
+    match crate::invoices::create_invoice(
+        pool.get_ref(),
+        &merchant.id,
+        &merchant.ufvk,
+        &invoice_req,
+        &rates,
+        config.invoice_expiry_minutes,
+        fee_config.as_ref(),
+    )
+    .await
+    {
+        Ok(resp) => {
+            let _ = payment_links::increment_created(pool.get_ref(), &link.id).await;
+
+            let frontend_url = config.frontend_url.as_deref().unwrap_or("https://cipherpay.app");
+            let mut checkout_url = format!("{}/pay/{}", frontend_url, resp.invoice_id);
+            if let Some(ref success) = link.success_url {
+                let encoded: String = success.chars().map(|c| match c {
+                    '&' | '=' | '?' | '#' | ' ' => format!("%{:02X}", c as u8),
+                    _ => c.to_string(),
+                }).collect();
+                checkout_url = format!("{}?return_url={}", checkout_url, encoded);
+            }
+
+            HttpResponse::Created().json(serde_json::json!({
+                "invoice_id": resp.invoice_id,
+                "checkout_url": checkout_url,
+                "payment_address": resp.payment_address,
+                "amount": resp.amount,
+                "currency": resp.currency,
+                "price_zec": resp.price_zec,
+                "zcash_uri": resp.zcash_uri,
+                "expires_at": resp.expires_at,
+                "product_name": product.name,
+                "link_name": link.name,
+            }))
+        }
+        Err(e) => {
+            tracing::error!(error = %e, slug = %slug, "Payment link invoice creation failed");
+            HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Failed to create invoice"
+            }))
+        }
+    }
+}
+
+fn link_response(link: &payment_links::PaymentLink) -> serde_json::Value {
+    serde_json::json!({
+        "id": link.id,
+        "merchant_id": link.merchant_id,
+        "price_id": link.price_id,
+        "slug": link.slug,
+        "name": link.name,
+        "success_url": link.success_url,
+        "metadata": link.metadata_json(),
+        "active": link.active == 1,
+        "total_created": link.total_created,
+        "created_at": link.created_at,
+    })
+}
+
+fn validate_create(req: &CreatePaymentLinkRequest) -> Result<(), validation::ValidationError> {
+    validation::validate_length("price_id", &req.price_id, 100)?;
+    if let Some(ref name) = req.name {
+        validation::validate_length("name", name, 200)?;
+    }
+    if let Some(ref url) = req.success_url {
+        validation::validate_length("success_url", url, 2000)?;
+    }
+    Ok(())
+}
+
+fn validate_update(req: &UpdatePaymentLinkRequest) -> Result<(), validation::ValidationError> {
+    if let Some(ref name) = req.name {
+        validation::validate_length("name", name, 200)?;
+    }
+    if let Some(ref url) = req.success_url {
+        validation::validate_length("success_url", url, 2000)?;
+    }
+    Ok(())
+}