# `pub struct Stripe` A thin async wrapper around the subset of the Stripe REST API this service uses. It knows nothing about relays, tenants, or the database — it just speaks HTTP to Stripe and returns `serde_json::Value` (or small typed results). The domain logic that drives it lives in `spec/billing.md`. Members: - `secret_key: String` - Stripe API key, used as the bearer token and as the HMAC key for idempotency keys - `webhook_secret: String` - secret for verifying Stripe webhook signatures - `http: reqwest::Client` All requests authenticate with `secret_key` via `Authorization: Bearer`. Write requests that must not be retried twice (customer/subscription/item creation, invoice payment) send a deterministic `Idempotency-Key` derived by HMAC-ing the operation name and its arguments with `secret_key`. Reconcile-to-desired-state writes (e.g. setting an item quantity) intentionally omit the idempotency key, since re-applying the same target is a no-op. On any 4xx/5xx response, the wrapper reads the body and folds Stripe's JSON error payload (`error.message` / `error.type` / `error.code` / `error.param`) into the returned error so callers get an actionable message instead of a bare status line. ## `pub fn from_env() -> Self` Reads `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` (both required) and constructs the client. Panics if either is missing or blank. This is what `Billing::new` calls. ## `pub fn new(secret_key: String, webhook_secret: String) -> Self` Constructs the client with a fresh `reqwest::Client` from explicit keys (does not touch the environment). ## `pub async fn create_customer(&self, name: &str, tenant_pubkey: &str) -> Result` - `POST /v1/customers` with `name` and `metadata[tenant_pubkey]` - Idempotent on `tenant_pubkey` - Returns the new customer id; errors if it isn't a `cus_…` id ## `pub async fn get_subscription(&self, subscription_id: &str) -> Result>` - `GET /v1/subscriptions/:id` - Returns `None` if Stripe responds `404` (so callers can recover from a stale subscription id), otherwise the subscription object ## `pub async fn create_subscription(&self, customer_id: &str, items: &BTreeMap) -> Result<(String, BTreeMap)>` - `POST /v1/subscriptions` with `collection_method: charge_automatically` and one `items[n][price]` / `items[n][quantity]` pair per entry - Idempotent on the customer and the `(price, quantity)` set - Returns the subscription id and a map from price id to the created subscription item id ## `pub async fn create_subscription_item(&self, subscription_id: &str, price_id: &str, quantity: i64) -> Result<()>` - `POST /v1/subscription_items` - Idempotent on `(subscription_id, price_id)` ## `pub async fn set_subscription_item_quantity(&self, item_id: &str, quantity: i64) -> Result<()>` - `POST /v1/subscription_items/:id` with `quantity` - No idempotency key (reconcile-to-target write) ## `pub async fn delete_subscription_item(&self, item_id: &str) -> Result<()>` - `DELETE /v1/subscription_items/:id` ## `pub async fn cancel_subscription(&self, subscription_id: &str) -> Result<()>` - `DELETE /v1/subscriptions/:id` ## `pub async fn list_invoices(&self, customer_id: &str) -> Result` - `GET /v1/invoices?customer=…` - Returns the `data` array ## `pub async fn get_invoice(&self, invoice_id: &str) -> Result` - `GET /v1/invoices/:id` - On a 4xx response, returns `InvoiceLookupError::StripeClient { status }` (callers usually surface this as a client error, e.g. `404` "no such invoice"); other failures are `InvoiceLookupError::Internal` - Returns the full invoice object ## `pub async fn pay_invoice(&self, invoice_id: &str) -> Result<()>` - `POST /v1/invoices/:id/pay` (retries collection using the customer's default payment method) - Idempotent on `invoice_id` ## `pub async fn pay_invoice_out_of_band(&self, invoice_id: &str) -> Result<()>` - `POST /v1/invoices/:id/pay` with `paid_out_of_band: true` — used when payment was collected over Lightning rather than through Stripe - Idempotent on `invoice_id` ## `pub async fn preview_invoice(&self, customer_id: &str, subscription_id: Option<&str>) -> Result` - `GET /v1/invoices/upcoming?customer=…[&subscription=…]` - Used to validate proration when a subscription is downgraded ## `pub async fn has_payment_method(&self, customer_id: &str) -> Result` - `GET /v1/payment_methods?customer=…&type=card` - Returns whether the customer has at least one card on file ## `pub async fn create_portal_session(&self, customer_id: &str, return_url: Option<&str>) -> Result` - `POST /v1/billing_portal/sessions` with `customer` and optional `return_url` - Returns the portal session URL ## `pub fn construct_event(&self, payload: &str, sig_header: &str) -> Result` Verifies the `Stripe-Signature` header against `webhook_secret` and parses the body. - Parse `t=` (timestamp) and `v1=` (signature) from the header - Compute `HMAC-SHA256(webhook_secret, "{t}.{payload}")`, hex-encode it, and compare to `v1=`; error on mismatch - Error if the timestamp is more than 300 seconds from now - Returns the deserialized `Event` (`{ event_type, data: { object } }`) # `pub enum InvoiceLookupError` - `StripeClient { status: reqwest::StatusCode }` - Stripe returned a 4xx for an invoice lookup - `Internal(anyhow::Error)` - any other failure Implements `Display`/`Error` and `From` / `From` (both mapping to `Internal`). # `pub struct Event` / `pub struct EventData` The verified, parsed webhook event: `Event { event_type: String, data: EventData }`, `EventData { object: serde_json::Value }`.