# Stripe Integration :::note{title="Beta"} API Monetization is in beta and free to try. The APIs are stable but should be evaluated in non-production environments first. To go to production, contact [sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been announced. ::: Zuplo uses Stripe to collect payments. Zuplo is the system of record for plans, subscriptions, features, entitlements, and metered usage; Stripe is the system of record for **money** — customers, invoices, and payment collection. ## How it works The integration flow: 1. You define plans, features, and meters in Zuplo 2. You connect your Stripe account via the Zuplo Portal 3. Plans, features, and rate cards stay in Zuplo's catalog — Stripe is used only at billing time 4. Customers subscribe through your Developer Portal via Stripe Checkout 5. Stripe collects the payment method and Zuplo creates the subscription with an API key scoped to the plan's entitlements 6. As the customer uses the API, the monetization policy meters usage in real time 7. At the end of each billing period, Zuplo issues a Stripe Invoice for fixed fees and usage-based charges Throughout this flow, Zuplo is the source of truth for access control, plans/rate cards, and metered usage. Stripe is the source of truth for payment state and tax. **Stripe Subscriptions, Products, Prices, and Billing Meters are not used** — Zuplo manages those concepts internally and only materializes them in Stripe at the moment a charge is needed (as invoice line items). ## Connecting your Stripe account ### Via the Zuplo Portal 1. Open your project's [**Services**](https://portal.zuplo.com/+/account/project/services) page, select the Monetization Service, then go to **Payment Provider** 2. Click **Configure** on the Stripe card 3. Paste your **Stripe API Key** 4. Click **Save** :::tip To script the same flow (CI, infrastructure-as-code, etc.) use the [Stripe setup API](./api-access.mdx#stripe-setup-and-billing-readiness) — it exposes `POST /setup/stripe`, `GET /billing-readiness`, and key-rotation endpoints with the same prefix validation as the UI. ::: The connection authorizes Zuplo to manage Stripe objects on your behalf — specifically Customers, Checkout Sessions, Customer Portal Sessions, Invoices, and Tax Calculations. See [What Zuplo creates in Stripe](#what-zuplo-creates-in-stripe) for the full list. ### Test mode vs. live mode Connect with a Stripe **test** key (`sk_test_...`) first to validate your configuration end-to-end. Test mode uses Stripe's test card numbers (e.g., `4242 4242 4242 4242`) and never charges real money. When you're ready to go live, configure a separate Zuplo environment (e.g., **Production**) with your live key (`sk_live_...`). :::caution Use one Stripe key type per Zuplo environment — do not replace a test key with a live key in the same environment. Test mode and live mode are separate environments in Stripe. Products, customers, and subscriptions created in test mode don't transfer to live mode and vice versa. ::: ## Using a Stripe restricted key Zuplo accepts both **secret keys** (`sk_test_*`, `sk_live_*`) and **restricted keys** (`rk_test_*`, `rk_live_*`) when you connect Stripe. For production, use a restricted key — it follows the principle of least privilege and limits the blast radius if the credential is ever leaked. A Monetization V3 restricted key needs the following eight permissions. Leave every other permission set to **None**. | Stripe permission | Level | Why Zuplo needs it | | -------------------------------------------------- | ----- | ---------------------------------------------------------------------------------- | | Connect → Accounts | Read | Verifies the key on install and reads basic account details (country, currency) | | Core → Customers | Write | Creates and updates Stripe Customers when developers subscribe | | Core → Payment Methods | Read | Displays saved cards in the customer portal | | Checkout → Checkout Sessions | Write | Creates checkout sessions when developers add a payment method | | Billing → Customer portal | Write | Creates customer-portal sessions for self-service plan management | | Billing → Invoices | Write | Issues, finalizes, and pays invoices for metered usage (also covers Invoice items) | | Tax → Tax Calculations and Transactions | Write | Calculates tax via Stripe Tax when tax collection is enabled | | Webhook → Webhook Endpoints and Event Destinations | Write | Registers the webhook Zuplo uses to receive payment events | Zuplo doesn't use Stripe Subscriptions, Products, Prices, Payment Intents, Setup Intents, Refunds, or Stripe Billing Meters — leave all of those at **None**. ### Create the restricted key 1. In the Stripe Dashboard, go to **Developers → API keys → Create restricted key**. 2. Name the key something recognizable, for example `Zuplo Monetization (test)` or `Zuplo Monetization (production)`. 3. For each of the eight permissions above, set the level shown in the table. 4. Click **Create key**, copy the value (`rk_test_...` or `rk_live_...`), and paste it into the Monetization Service's **Payment Provider** screen (open your project's [**Services**](https://portal.zuplo.com/+/account/project/services) page, then the Monetization Service) in your Zuplo project. :::caution Use a **test** restricted key (`rk_test_*`) for preview and working-copy environments, and a **live** restricted key (`rk_live_*`) for production. Zuplo rejects a live key on a non-production environment and vice versa. ::: ### Troubleshoot permission errors If you see an error like: ``` The provided key 'rk_test_...' does not have the required permissions for this endpoint. Having the 'rak_accounts_kyc_basic_read' permission would allow this request to continue. ``` The key is missing one of the permissions in the table above. Stripe's internal name in the error (`rak__`) maps to a row in the table. The most common omissions: - **`rak_accounts_kyc_basic_read`** → enable **Connect → Accounts** at **Read**. - **`rak_tax_calculations_*`** → enable **Tax → Tax Calculations and Transactions** at **Write**. - **`rak_webhook_endpoints_*`** → enable **Webhook → Webhook Endpoints and Event Destinations** at **Write**. - **`rak_invoices_*`** → enable **Billing → Invoices** at **Write**. Edit the key in the Stripe Dashboard, tick the missing permission, save, and retry the connection in Zuplo. ### Rotate the key You can replace the connected key from the same **Payment Provider** screen. The new key must: - Use the same prefix mode (test or live) as the existing key. - Belong to the same Stripe account. - Carry all eight permissions above. ## What Zuplo creates in Stripe Zuplo's catalog — plans, features, rate cards, and entitlements — is stored in Zuplo. Stripe is used only at the points where money or payment state is involved. The objects that Zuplo creates or manages in your Stripe account: | Object | When it's created | | ------------------------------- | -------------------------------------------------------------------------- | | Stripe Customer | When a developer first subscribes — one Stripe Customer per Zuplo customer | | Stripe Checkout Session | When a developer subscribes to a plan that requires a payment method | | Stripe Customer Portal Session | When a developer opens **Manage Billing** in the Developer Portal | | Stripe Invoice and Invoice Item | At the end of each billing period for fixed and usage-based charges | | Stripe Tax Calculation | At invoice time when [tax collection](./tax-collection.md) is enabled | | Stripe Webhook Endpoint | Once on connection, so Zuplo can react to payment events | To see what Zuplo has created, look under **Customers** and **Invoices** in your Stripe dashboard. ## Subscription flow ### New subscription When a customer clicks "Subscribe" in your Developer Portal: 1. A Stripe Checkout Session is created so the customer can enter a payment method 2. The customer is redirected to Stripe Checkout to enter payment details 3. On successful payment, the subscription is created 4. An API key is generated scoped to the subscription's plan entitlements 5. The customer is redirected back to the Developer Portal, where they can immediately see their subscription, usage dashboard, and API key ### Plan changes (upgrades/downgrades) When a customer changes their plan through the Developer Portal: 1. Zuplo records the plan change and recalculates the customer's entitlements 2. Any prorated amount is reflected on the customer's next Stripe Invoice 3. The customer's entitlements update immediately 4. The API key remains the same; its associated quota changes in real time Zuplo uses **max_consumption_based proration** so customers can't game mid-period upgrades and downgrades — see [Subscription Lifecycle → Proration behavior](./subscription-lifecycle.md#proration-behavior) for the detailed model and examples. ### Cancellation When a customer cancels through the Developer Portal, the timing of the cancellation depends on whether the current phase has billable items: - **Paid phases** — the portal sends `timing: "next_billing_cycle"`. The subscription is scheduled to cancel at the end of the current billing period, the customer retains access until then, and the API key stops working at period end. - **Free phases** — the portal sends `timing: "immediate"`. With nothing to invoice at period end, there's no billing period to wait out, so the subscription cancels and access is revoked right away. Two situations fall into this branch: - The customer is on a **free trial phase** (the first phase of a plan with a later paid phase) and cancels before the trial converts. - The customer is on a **free plan** — a plan whose only phase has no billable rate cards (every rate card's `price` is `null`). For programmatic cancellation, see [Cancellation](./subscription-lifecycle.md#cancellation) in the Subscription Lifecycle guide — the API endpoint accepts a `timing` parameter to control this same behavior explicitly. ## Usage-based billing For plans with usage-based pricing (per-unit, tiered, pay-as-you-go), usage is tracked in real time by the `MonetizationInboundPolicy`. Each API request increments the meter immediately. At the end of the billing period, Zuplo generates a Stripe Invoice with line items for the period's fixed fees and metered usage, and Stripe collects payment. You don't need to implement usage reporting or run any batch jobs — and Zuplo does **not** call Stripe Billing Meters; metered usage is materialized as invoice line items directly. ## Handling failed payments When Stripe fails to collect payment, access is determined by the subscription's payment status. By default, a 3-day grace period allows continued access while Stripe retries the payment. | Payment status | Default behavior | | --------------- | ------------------------------------------------ | | `paid` | Full access | | `not_required` | Full access (free plans) | | `pending` | Full access (within grace period) | | `failed` | Access blocked after grace period (configurable) | | `uncollectible` | Access blocked | The grace period is configurable, with customer metadata overriding plan metadata, which overrides the bucket-level `maxPaymentOverdueDays`. Default is 3 days. See [Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation) for the full resolution order. ## Customer portal Stripe provides a hosted Customer Portal where customers can update their payment method, view invoices, and manage their subscription. The Developer Portal links to this from the subscription management page. To enable the Stripe Customer Portal: 1. Configure the Customer Portal in your [Stripe Dashboard → Settings → Billing → Customer Portal](https://dashboard.stripe.com/settings/billing/portal) 2. Enable the features you want (update payment method, view invoices) 3. The Developer Portal automatically includes a "Manage Billing" link that opens the Stripe Customer Portal ## Testing ### Test card numbers Use Stripe's test card numbers to simulate different scenarios: | Card number | Scenario | | --------------------- | ---------------------------------------- | | `4242 4242 4242 4242` | Successful payment | | `4000 0000 0000 3220` | Requires 3D Secure authentication | | `4000 0000 0000 0341` | Attaches to customer but fails on charge | | `4000 0000 0000 9995` | Declined (insufficient funds) | ### Verifying the integration After connecting Stripe and publishing plans: 1. Open your Developer Portal 2. Subscribe to a plan using test card `4242 4242 4242 4242` 3. Verify in Stripe Dashboard: - **Customers** — a customer was created with correct metadata and test card attached - **Developers → Webhooks** — the Zuplo-managed webhook endpoint is registered and recent events show `200` responses 4. Make API requests and verify: - Requests succeed within quota - `403 Forbidden` returned when quota exceeded (hard-limit plans) - Usage visible in the Developer Portal dashboard 5. Wait for the next billing cycle (or trigger a manual invoice in test mode) and verify: - **Invoices** — a Stripe Invoice was created with line items matching your plan's fixed fees and metered usage 6. Cancel the subscription in the Developer Portal and verify: - Access is revoked after the billing period ends - The Zuplo subscription shows `canceled` in the API and Developer Portal (Stripe doesn't track this — there is no Stripe Subscription to look at)