# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. The payer is a user or a workspace, as the `payer` input says. | Table | Columns | | --- | --- | | `billing_customers` | `payer_id` (primary key), `provider_customer_id` (unique), `trial_used`, `created_at` | | `subscriptions` | `payer_id` (primary key), `provider_subscription_id` (unique), `plan`, `state`, `ends_with_period`, `period_end`, `trial_end`, `past_due_since`, `provider_updated_at` | | `billing_events` | `id` (the provider's event id, primary key), `type`, `received_at`, `handled_at`, `payload` | One row per payer in `subscriptions`. A new subscription after an ended one replaces the row. ## States | State | Means | Access | | --- | --- | --- | | `trialing` | In a trial, not yet charged | The plan | | `active` | Paid up | The plan | | `past_due` | A payment failed and the provider is retrying | The plan for the `grace_days` input from `past_due_since`, then none | | `canceled` | Ended | None | | From | To | When | | --- | --- | --- | | none | `trialing` | Checkout completes, `trial_days` is more than 0, and no trial was used | | none | `active` | Checkout completes otherwise | | `trialing` | `active` | The first payment succeeds | | `trialing` | `canceled` | Cancelled in the trial, or the first payment fails for good | | `active` | `past_due` | A payment fails | | `past_due` | `active` | A retry succeeds | | `past_due` | `canceled` | The provider gives up | | `active` | `canceled` | The paid period ends with `ends_with_period` set | ## The adapter Everything provider-specific sits behind four operations. Tests use a stand-in that implements them in memory. | Operation | Does | | --- | --- | | `ensure_customer(payer)` | Returns the provider's customer id, creating it if needed | | `checkout_url(customer, plan, trial_days)` | Returns the address of a hosted checkout | | `portal_url(customer)` | Returns the address of the provider's portal | | `read_subscription(id)` | Returns the subscription as the provider has it now | and one function that turns a webhook's raw bytes and headers into either "signature bad" or an event with an id, a time, a kind and a subscription id. ## Stripe When the `provider` input is `stripe`. Confirm the event names in Stripe's documentation before building. | Stripe event | The app does | | --- | --- | | `checkout.session.completed` | Reads the subscription and stores it | | `customer.subscription.updated` | Reads the subscription and stores it | | `customer.subscription.deleted` | Sets `canceled` | | `invoice.payment_failed` | Sets `past_due_since` if it is empty, then reads the subscription | | `invoice.paid` | Clears `past_due_since`, then reads the subscription | Stripe's `trialing`, `active`, `past_due` and `canceled` map to the same names. Treat `unpaid` and `incomplete_expired` as `canceled`, and `incomplete` as no subscription yet. ## Rules - Create the customer inside a transaction that first inserts the `billing_customers` row with an empty id, so a second request waits on the row instead of creating a second customer. Give the provider an idempotency key made from the payer's id as well. - Insert the `billing_events` row before handling. A unique-key failure means the event was seen: answer 200 and stop. - Store `provider_updated_at` from the provider's own time on the event or the subscription, and apply nothing older than it. - Take the time from one function, so tests can set it. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `PAYMENT_PROVIDER_KEY` | Calls the provider. | | `PAYMENT_WEBHOOK_SECRET` | Checks the signature on webhooks. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.