Skip to content
← Public packages

@kody/stripe

Read and manage Stripe customers, payments, invoices, subscriptions, and refunds with dry-run mutations.

FollowFork

Files

README.md

86 lines · 3.6 KB · Markdown

@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.

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.

SecretPurpose
stripeApiKeySecret key (sk_live_… / sk_test_…) or restricted key (rk_…)
stripeWebhookSecretEndpoint signing secret (whsec_…) for HMAC verify
  1. Create a key at 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

  1. Approve hosts api.stripe.com and files.stripe.com.
  2. 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 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