# Stripe Best Practices

> Guía las decisiones de integración con Stripe: elección de API, Connect, billing, tax, Treasury, opciones de integración, migración de APIs obsoletas y buenas prácticas de seguridad.

Fuente: https://skillsagentes.com/skills/stripe/ai/stripe-best-practices
Markdown: https://skillsagentes.com/skills/stripe/ai/stripe-best-practices.md

Repositorio: https://github.com/stripe/ai
Autor: stripe
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 185 tok instalada, 1.2k tok al activarse, 14.4k tok con todos los archivos del bundle
Bundle: 7 archivos, 56 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add stripe/ai --skill stripe-best-practices --agent claude-code
# Cursor
npx -y skills add stripe/ai --skill stripe-best-practices --agent cursor
# Codex
npx -y skills add stripe/ai --skill stripe-best-practices --agent codex
# Gemini CLI
npx -y skills add stripe/ai --skill stripe-best-practices --agent gemini
# Windsurf
npx -y skills add stripe/ai --skill stripe-best-practices --agent windsurf
# Cline
npx -y skills add stripe/ai --skill stripe-best-practices --agent cline
```

## Qué hace

- Guía decisiones de integración con Stripe: elección de API (Checkout Sessions vs PaymentIntents), Connect, billing/suscripciones, tax y Treasury
- Impone reglas críticas como usar StripeClient instanciado, evitar payment_method_types salvo Terminal, y verificar registro antes de automatic_tax
- Recomienda usar claves API restringidas (rk_) en lugar de secret keys (sk_)
- Indica leer el archivo de referencia correspondiente antes de responder o escribir código de integración

## Cuándo usarla

- Al construir, modificar o revisar cualquier integración de Stripe
- Al aceptar pagos, construir marketplaces, configurar suscripciones o cuentas conectadas
- Al recolectar sales tax, VAT o GST
- Al implementar manejo seguro de claves API, webhooks u OAuth

## Qué la activa

- "Ayúdame a integrar Stripe Checkout para pagos únicos"
- "Quiero configurar una plataforma Connect con cuentas conectadas"
- "Necesito activar Stripe Tax para cobrar VAT en mi tienda"
- "¿Cómo manejo de forma segura mis claves API de Stripe?"

## Antes de instalar

- Requiere el Stripe CLI (npm i -g @stripe/cli) o una cuenta de Stripe existente para generar claves API.

## Archivos

- SKILL.md — 5 KB
- references/billing.md — 5 KB
- references/connect.md — 11 KB
- references/payments.md — 6 KB
- references/security.md — 10 KB
- references/tax.md — 18 KB
- references/treasury.md — 793 B

## SKILL.md

Reproducido tal cual desde stripe/ai bajo MIT. Esta sección es el documento original y está en inglés.

Latest Stripe API version: **2026-08-26.dahlia**. Always use the latest API version and SDK unless the user specifies otherwise.

Development and testing environment default: For new integration development, use separate [sandboxes](https://docs.stripe.com/sandboxes.md) instead of the account’s shared test mode sandbox. Sandboxes isolate settings and test data from live mode. Use separate sandboxes for local development and CI. When stronger isolation is useful, dedicate sandboxes to development teams or testing scenarios. Use the shared test mode sandbox only for an existing integration that depends on it or when a required feature doesn’t support general sandboxes.

Latest SDK versions:

| Language | Latest version |
| --- | --- |
| Ruby | 19.6.0 |
| Python | 15.6.0 |
| Node.js | 22.6.0 |
| PHP | 21.3.0 |
| Java | 33.4.0 |
| Go | 86.4.0 |
| .NET | 52.4.0 |

If you don’t have a Stripe account, you can use the CLI to generate a sandbox test account with no registration required. Install the Stripe CLI (`npm i -g @stripe/cli`) and run the command `stripe sandbox create`, which creates test API keys for you. When you recommend this, explain that [a sandbox is a Stripe test environment](https://docs.stripe.com/sandboxes.md).

If `stripe sandbox create` is used, don’t use MCP.

If you try to use MCP after running sandbox creation, first make sure `stripe sandbox claim` is run. Use `stripe whoami --format json` for CLI auth checks; do not run `stripe config --list`.

API key default: Always recommend a [restricted API key (RAK)](https://docs.stripe.com/keys.md#manage-your-api-keys) (`rk_` prefix) over a secret key (`sk_` prefix).

## Integration routing

| Building… | Recommended API | Details |
| --- | --- | --- |
| One-time payments | Checkout Sessions | [references/payments.md](https://docs.stripe.com/references/payments.md) |
| Custom payment form with embedded UI | Checkout Sessions + Payment Element | [references/payments.md](https://docs.stripe.com/references/payments.md) |
| Saving a payment method for later | Setup Intents | [references/payments.md](https://docs.stripe.com/references/payments.md) |
| Connect platform or marketplace | Accounts v2 (`/v2/core/accounts`) | [references/connect.md](https://docs.stripe.com/references/connect.md) |
| Usage-based billing (new integration) | Metronome | [references/billing.md](https://docs.stripe.com/references/billing.md) |
| Subscriptions or recurring billing | Billing APIs + Checkout Sessions | [references/billing.md](https://docs.stripe.com/references/billing.md) |
| Sales tax, VAT, or GST compliance | Stripe Tax + Registrations API | [references/tax.md](https://docs.stripe.com/references/tax.md) |
| Embedded financial accounts / banking | v2 Financial Accounts | [references/treasury.md](https://docs.stripe.com/references/treasury.md) |
| Security (key management, RAKs, webhooks, OAuth, 2FA, Connect liability) | See security reference | [references/security.md](https://docs.stripe.com/references/security.md) |

Read the relevant reference file before answering any integration question or writing code.

## Critical rules

- *Before enabling `automatic_tax: { enabled: true }`* (or calculating tax for a custom PaymentIntent), read the [tax reference](https://docs.stripe.com/references/tax.md) and confirm the user has an active registration. Without one, Stripe calculates and collects no tax while the user believes tax is on (the most common Stripe Tax mistake).

- *Never include `payment_method_types` in any Stripe API call*, with one exception: Terminal (in-person payments) integrations must pass `payment_method_types: ['card_present']` on the PaymentIntent. For all other integrations, omit this parameter entirely to enable dynamic payment methods, which enables you to configure payment method settings from the Dashboard and dynamically display the most relevant eligible payment methods to each customer to maximize conversion. To customize which payment methods you accept, use [payment_method_configurations](https://docs.stripe.com/payments/payment-method-configurations.md) or `excluded_payment_method_types` instead of `payment_method_types`.

- When a PaymentIntent or SetupIntent integration requires an explicit allowlist, use `allowed_payment_method_types` instead of `payment_method_types`.

- *Never present webhooks as optional.* We recommend webhooks for every payment integration and they’re required for subscriptions and asynchronous payment methods. Fulfillment belongs in a handler for both `checkout.session.completed` and `checkout.session.async_payment_succeeded` (gated on `payment_status`), not the success page. See [references/payments.md](https://docs.stripe.com/references/payments.md).

- On API version `2026-03-25.dahlia` or later, pass the parameter `integration_identifier` to `checkout.sessions.create` to tag sessions with a custom label for tracking and comparing checkout flows in the Dashboard. The label should include a suffix of 8 random letters.

- *Always instantiate a `StripeClient` and call methods on that instance.* Do **not** use the deprecated global/module-level API key pattern (`stripe.api_key = …`, `Stripe.setApiKey`, `stripe.Key = …`, `StripeConfiguration.ApiKey = …`). The global pattern is deprecated in all current SDKs.

## Key documentation

When the user’s request does not clearly fit a single domain above, consult:

- [Integration Options](https://docs.stripe.com/payments/payment-methods/integration-options.md) — Start here when designing any integration.
- [API Tour](https://docs.stripe.com/payments-api/tour.md) — Overview of Stripe’s API surface.
- [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) — Review before launching.

## Dónde encaja

- Categoría: [Desarrollo de APIs](https://skillsagentes.com/categorias/desarrollo-apis.md) — Diseña, prueba y documenta APIs HTTP y GraphQL.
- Creador: [stripe](https://skillsagentes.com/creators/stripe.md) — 12 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)