# Stripe plugin

The Stripe plugin lets a Vaubaan Gateway mission use Stripe without handing the agent a credential. Billing operations on a Stripe account : catalog, customers, subscriptions, invoices, refunds, payouts, webhooks — test and live modes as separate resources.

- Version: `0.4.0` (package `@vaubaan/plugin-stripe`)
- Status: stable
- Health: not enough reports yet — [what this means](/plugins/health)
- Source: [plugins/stripe](https://github.com/vaubaan/gateway/tree/main/plugins/stripe), catalog [risk-catalog.yaml](https://github.com/vaubaan/gateway/blob/main/plugins/stripe/src/risk-catalog.yaml) version 5 of 2026-10-14
- How to connect an account: [Connect Stripe](/docs/providers/stripe)
- How it is modelled: [handbook](https://github.com/vaubaan/gateway/blob/main/docs/handbook/providers/stripe.md)

One account is one Stripe account, given as a test key, a live key, or both; each mode is its own resource, labelled test or live by the plugin. Every permission is held per mode, so a mission can work freely in test mode and touch live billing only within its limits and after your yes.

## Permissions

Each permission is a named risk of the plugin's catalog: a mission holds an explicit list of them, never "all". The severity is computed from the permission's six axes (undo, blast radius, data, cost, visible to, lasts); nothing is decided from it.

| Permission | What it allows | Severity | Why it is a risk |
| --- | --- | --- | --- |
| `stripe.read-catalog` | Read catalog (products, prices, coupons, promotion codes) | low (only for `test`, `live`) | Inventory of the commercial catalog. Public metadata by construction (prices are shown on the marketing site). No PII, no secret. |
| `stripe.read-billing-history` | Read billing history (subscriptions, invoices, charges, payment intents) | low (only for `test`, `live`) | Reads the transactional history. No card number leaves Stripe, but amounts, dates and descriptions per customer reveal the commercial trajectory. Distinct from read-customer-pii so anonymised statistics can be allowed without identities. |
| `stripe.read-customer-pii` | Read customer PII (email, name, address, phone) | medium (only for `test`, `live`) | Reads the personal fields of customers (\`email\`, \`name\`, \`address\`, \`phone\`, \`shipping\`). GDPR/CCPA surface : any consumption by an agent triggers a minimisation duty. Emitted alongside the business payload of every customer read, so a mission without it cannot read customers. |
| `stripe.read-balance` | Read balance, ledger and events (cash position) | low (only for `test`, `live`) | Available and pending balance, ledger history, event feed. Real-time cash position : sensitive for finance, no PII. Distinct from read-billing-history so an "ops monitoring" agent needs no customer details. |
| `stripe.catalog-write` | Create / update products, prices, coupons, promotion codes | medium (only for `test`, `live`) | Changes the commercial catalog. Reversible (archive and recreate), no effect on existing payments, but every future checkout sees it. A soft posture shift on the offer. |
| `stripe.subscription-create` | Create a subscription (may charge immediately) | medium (only for `test`, `live`) | Creates a subscription. With immediate proration (the default without \`billing\_cycle\_anchor\`) Stripe charges the customer at creation. The classifier also emits \`payment-intent.W\` for that cash side effect ; this entry covers both slices (the second used to fall to the fallback, which presets no longer carry — catalog v3). |
| `stripe.subscription-update` | Update a subscription (plan, quantity, pause, metadata) | medium (only for `test`, `live`) | Changes an existing subscription : plan, quantity, metadata, \`pause\_collection\`. Costly when proration charges or credits the customer. Posture shift on recurring billing. |
| `stripe.subscription-cancel` | Cancel a subscription (stops future charges) | medium (only for `test`, `live`) | Stops future billing. Semantically irreversible : resubscribing creates a new subscription and loses the history. The customer loses access at the end of the period. |
| `stripe.invoice-create-draft` | Create a draft invoice (no customer notification) | low (only for `test`, `live`) | Creates an invoice in draft state. No notification, no money movement, deletable until finalised. Acceptable surface for a billing assistant. |
| `stripe.invoice-finalize` | Finalize an invoice (locks it, notifies, attempts collection) | medium (only for `test`, `live`) | Locks the draft, emails the customer by default and attempts collection when \`auto\_advance\` is set. Costly to revert : voiding leaves a trace. |
| `stripe.invoice-void` | Void a finalized invoice (cannot be undone) | medium (only for `test`, `live`) | Voids a finalised invoice. Irreversible by design (the paper trail stays, the invoice is inert for ever). No direct money movement but the receivable is written off : accounting impact. |
| `stripe.refund-create` | Create a refund (real money out of the merchant account) | high (only for `test`, `live`) | Issues a refund. Real money leaves the account ; bounded per call by the charge amount, unbounded over N calls. Irreversible : a refund is not reversed, the customer has to be charged again and may refuse. The cardinal financial-exfiltration vector of a compromised or prompt-injected agent. |
| `stripe.payout-create` | Create a payout (moves the balance to the bank account on file) | high (only for `test`, `live`) | Sends funds from the Stripe balance to the external account on file. Cancellable only while pending, then irreversible ; the amount is bounded by the balance, not by a limit of the mission. In test mode no money moves. |
| `stripe.customer-delete` | Delete a customer (cancels its subscriptions, cannot be undone) | high (only for `test`, `live`) | Permanently deletes a customer and immediately cancels every active subscription. Irreversible ; erases personal data (a GDPR erasure path) and recurring revenue in one call. |
| `stripe.webhook-endpoint-write` | Create / update / delete a webhook endpoint configuration | medium (only for `test`, `live`) | Configures the URL and the events an endpoint receives. Posture shift : a misconfigured endpoint routes events (customer data included) to an attacker. Distinct from mint-webhook-secret because an update does not regenerate the secret. |
| `stripe.mint-webhook-secret` | Mint a webhook signing secret (create\_webhook\_endpoint) | medium (only for `test`, `live`) | Credential creation. The \`whsec\_\*\` secret is returned once, at creation, and authenticates every event received. Same intention as creating an endpoint, asymmetric secret-bearing effect. |
| `stripe.uncategorized-write` | Uncategorized Stripe write | high (only for `test`, `live`; the catch-all: touched only by a call no other permission covers) | Catch-all for writes without a dedicated entry. Seen in production, it means a tool classifies to a slice no entry covers : add the entry. |

## Presets

A preset pre-fills the permissions of a mission for one account, with a limit per period, a rate and whether each permission runs freely or asks the mission creator first. The person creating the mission adjusts it; the mission stores the explicit list.

### Read-only

`read-only` — Catalog, billing history and cash position of the selected mode. No PII, no write.

| Permission | What it allows | Limit per period | Rate | Runs |
| --- | --- | --- | --- | --- |
| `stripe.read-catalog` | Read catalog (products, prices, coupons, promotion codes) | 2000 | 120 per minute | runs freely |
| `stripe.read-billing-history` | Read billing history (subscriptions, invoices, charges, payment intents) | 2000 | 120 per minute | runs freely |
| `stripe.read-balance` | Read balance, ledger and events (cash position) | 500 | 60 per minute | runs freely |

### Test-mode developer

`test-mode-developer` — Everything on the test-mode resource, generous budgets, nothing on live.

| Permission | What it allows | Limit per period | Rate | Runs |
| --- | --- | --- | --- | --- |
| `stripe[test].read-catalog` |  | 5000 | 120 per minute | runs freely |
| `stripe[test].read-billing-history` |  | 5000 | 120 per minute | runs freely |
| `stripe[test].read-customer-pii` |  | 5000 | 120 per minute | runs freely |
| `stripe[test].read-balance` |  | 1000 | 60 per minute | runs freely |
| `stripe[test].catalog-write` |  | 1000 | 60 per minute | runs freely |
| `stripe[test].subscription-create` |  | 500 | 30 per minute | runs freely |
| `stripe[test].subscription-update` |  | 500 | 30 per minute | runs freely |
| `stripe[test].subscription-cancel` |  | 200 | 30 per minute | runs freely |
| `stripe[test].invoice-create-draft` |  | 500 | 30 per minute | runs freely |
| `stripe[test].invoice-finalize` |  | 200 | 30 per minute | runs freely |
| `stripe[test].invoice-void` |  | 100 | 30 per minute | runs freely |
| `stripe[test].refund-create` |  | 100 | 10 per minute | runs freely |
| `stripe[test].payout-create` |  | 20 | 5 per minute | runs freely |
| `stripe[test].customer-delete` |  | 100 | 30 per minute | runs freely |
| `stripe[test].webhook-endpoint-write` |  | 50 | 10 per minute | runs freely |
| `stripe[test].mint-webhook-secret` |  | 20 | 10 per minute | runs freely |

### Finance operator

`finance-operator` — Live-mode billing operations; refunds, payouts, cancellations, voids and deletions ask first.

| Permission | What it allows | Limit per period | Rate | Runs |
| --- | --- | --- | --- | --- |
| `stripe[live].read-catalog` |  | 2000 | 120 per minute | runs freely |
| `stripe[live].read-billing-history` |  | 2000 | 120 per minute | runs freely |
| `stripe[live].read-customer-pii` |  | 500 | 60 per minute | runs freely |
| `stripe[live].read-balance` |  | 500 | 60 per minute | runs freely |
| `stripe[live].subscription-create` |  | 50 | 10 per minute | runs freely |
| `stripe[live].subscription-update` |  | 100 | 10 per minute | runs freely |
| `stripe[live].subscription-cancel` |  | 50 | 5 per minute | ask me first |
| `stripe[live].invoice-create-draft` |  | 200 | 20 per minute | runs freely |
| `stripe[live].invoice-finalize` |  | 100 | 10 per minute | runs freely |
| `stripe[live].invoice-void` |  | 20 | 5 per minute | ask me first |
| `stripe[live].refund-create` |  | 20 | 3 per minute | ask me first |
| `stripe[live].payout-create` |  | 5 | 2 per minute | ask me first |
| `stripe[live].customer-delete` |  | 10 | 2 per minute | ask me first |

## Tools

| Tool | What it does |
| --- | --- |
| `stripe__list_products` | List products |
| `stripe__list_prices` | List prices |
| `stripe__list_customers` | List customers |
| `stripe__retrieve_customer` | Read a customer |
| `stripe__list_subscriptions` | List subscriptions |
| `stripe__list_invoices` | List invoices |
| `stripe__list_charges` | List charges |
| `stripe__list_payment_intents` | List payment intents |
| `stripe__get_balance` | Read the balance |
| `stripe__list_events` | List events |
| `stripe__create_product` | Create a product |
| `stripe__update_product` | Change a product |
| `stripe__create_price` | Create a price |
| `stripe__update_price` | Change a price |
| `stripe__create_coupon` | Create a coupon |
| `stripe__create_promotion_code` | Create a promotion code |
| `stripe__create_subscription` | Create a subscription |
| `stripe__update_subscription` | Change a subscription |
| `stripe__cancel_subscription` | Cancel a subscription |
| `stripe__pause_subscription` | Pause a subscription |
| `stripe__create_invoice` | Create a draft invoice |
| `stripe__finalize_invoice` | Finalize an invoice |
| `stripe__void_invoice` | Void an invoice |
| `stripe__create_refund` | Refund a payment |
| `stripe__create_webhook_endpoint` | Create a webhook endpoint |
| `stripe__create_payout` | Pay out to the bank account |
| `stripe__delete_customer` | Delete a customer |

## Health

Health: not enough reports yet. A plugin version is deemed validated by the community with at least 200 reports and 90 % of them successful, over the last 90 days, as reported by the instances whose operators turned community telemetry on. It is a community signal, not a security guarantee.