caravel/backend/spec/stripe.md

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 small typed results. The domain logic that drives it lives in spec/billing.md, and the webhook dispatch lives in spec/api.md.

Members:

• env: Env - configuration; supplies the Stripe secret key (bearer token + idempotency HMAC key) and the webhook signing secret
• http: reqwest::Client

All requests authenticate with env.stripe_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 the secret key. Reconcile-to-desired-state writes (e.g. setting an item quantity, deleting/canceling) 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 new(env: &Env) -> Self

Constructs the client with a fresh reqwest::Client, holding a clone of env. This is what Billing::new and main call.

pub async fn create_customer(&self, tenant_pubkey: &str, name: &str) -> Result<String>

• POST /v1/customers with name and metadata[tenant_pubkey]
• Idempotent on tenant_pubkey
• Returns the new customer id

pub async fn get_subscription(&self, subscription_id: &str) -> Result<Option<StripeSubscription>>

• GET /v1/subscriptions/:id
• Returns None if Stripe responds 404 (so callers can recover from a stale subscription id), otherwise the parsed StripeSubscription

pub async fn create_subscription(&self, customer_id: &str, items: &BTreeMap<String, i64>) -> Result<StripeSubscription>

• 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 created StripeSubscription (including its items)

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<Vec<StripeInvoice>>

• GET /v1/invoices?customer=…
• Returns the parsed data array

pub async fn get_invoice(&self, invoice_id: &str) -> Result<Option<StripeInvoice>>

• GET /v1/invoices/:id
• Returns None if Stripe responds 404, otherwise the parsed StripeInvoice

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 (under a distinct key from pay_invoice)

pub async fn has_payment_method(&self, customer_id: &str) -> Result<bool>

• 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<String>

• POST /v1/billing_portal/sessions with customer and optional return_url
• Returns the Customer Portal session URL

pub fn get_webhook_event(&self, payload: &str, signature: &str) -> Result<StripeWebhookEvent>

Verifies the Stripe-Signature header against env.stripe_webhook_secret and parses the body.

• Parse t= (timestamp) and v1= (signature) from the header
• Compute HMAC-SHA256(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 StripeWebhookEvent

Typed results

• StripeWebhookEvent { event_type: String, data: StripeWebhookEventData }, StripeWebhookEventData { object: serde_json::Value } — the verified, parsed webhook event (event_type deserializes from the JSON type field)
• StripeSubscription { id, status, items: Vec<StripeSubscriptionItem> } (items flattened from Stripe's { data: [...] } list)
• StripeSubscriptionItem { id, price: StripePrice, quantity } (quantity defaults to 1 when absent)
• StripePrice { id }
• StripeInvoice { id, customer, status, amount_due, currency } (the subset of invoice fields the API surfaces; Serialize + Clone)