# @kody/stripe ## Intent Reusable Stripe helpers so Kody agents can read and manage customers, payments, invoices, subscriptions, refunds, products, and webhook events on **the caller's** Stripe account — not a shared platform store. Auth is a saved API key, not OAuth. Reads are free-form; mutations support `dryRun: true`, and money-moving or destructive calls also require `confirm: true`. This listing is meant to be forked. After you fork, save your own `stripeApiKey` and call the helpers in your account. This official API-key package is the **preferred** invoke path. Setup is harder: save a Stripe secret or restricted key. For a faster first win, connect Stripe MCP in Get started and use [`@kody/stripe-mcp`](https://kody.codes/@kody/stripe-mcp). ## What it does - Customers: list, search, get, create, update, delete - Payments: PaymentIntents, charges, refunds - Invoices: list/search/get, create, finalize, send, void, delete draft - Subscriptions: list/search/get, create, cancel - Products, prices, and payment links - Account profile, balance, payouts, and events - Webhook HMAC verify and event re-fetch (`loadVerifiedEvent`) - Low-level `stripeRequest` / list / search for endpoints without a typed helper ## Prerequisites / setup **API key** (secret-backed). There is no Stripe OAuth integration and no bot token. Do not open `/connect/oauth` for Stripe. | Secret | Purpose | | --- | --- | | `stripeApiKey` | Secret key (`sk_live_…` / `sk_test_…`) or restricted key (`rk_…`) | | `stripeWebhookSecret` | Endpoint signing secret (`whsec_…`) for HMAC verify | 1. Create a key at [dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys). Prefer a **restricted key** with only the permissions you need. 2. Save it in Kody (do not paste the value in chat): https://kody.codes/account/secrets/new?name=stripeApiKey&description=Stripe%20secret%20API%20key%20(sk_live_%20or%20rk_live_)%20for%20customers%2C%20payments%2C%20invoices%2C%20and%20subscriptions&allowedHosts=api.stripe.com,files.stripe.com&scope=user 3. Approve hosts **`api.stripe.com`** and **`files.stripe.com`**. 4. Optional webhook signing secret: https://kody.codes/account/secrets/new?name=stripeWebhookSecret&description=Stripe%20webhook%20signing%20secret%20(whsec_)%20from%20Developers%20%E2%86%92%20Webhooks&scope=user `stripeWebhookSecret` is for local HMAC only (no Stripe API hosts required). Inbound deliveries still need a URL you control (after a fork, a package-declared Kody webhook is one option). This official listing does not mint a shared ingress URL. ### Multi-account Pass `account: "work"` → secret `stripeApiKey-work` (and `stripeWebhookSecret-work` for HMAC), or `secretName: "stripeApiKey-live"`. ### Restricted-key permissions A full `sk_…` key can call everything exposed here. Restricted keys need the matching `rak_…` permission; 403s name the missing permission when Stripe includes it. HTTP 401 means the key is missing or invalid. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke, and confirm guards. ## Done when - `stripeApiKey` is saved; Stripe hosts and package secret access are approved - Smoke test returns `ok: true` (live account/balance when the key exists) - Destructive helpers refuse unless `confirm: true`; `dryRun: true` never writes ## Branding `community-icon.svg` is Stripe's official "S" glyph (Simple Icons, CC0), on Stripe purple `#635BFF`. Stripe® is a trademark of Stripe, Inc. This package is not affiliated with or endorsed by Stripe. ## Docs - [Stripe API](https://docs.stripe.com/api) - [Restricted keys](https://docs.stripe.com/keys-best-practices) - [Webhook signatures](https://docs.stripe.com/webhooks/signatures)