Stripe Best Practices

Best practices for building Stripe payment integrations

Security Scan

This is an instruction-only, knowledge-style skill that provides Stripe integration best-practices and does not request credentials, install code, or perform actions outside its stated scope.

Purpose & Capability

The name/description match the SKILL.md content: a set of best-practice recommendations and migration guidance for Stripe integrations. Nothing in the metadata or runtime instructions requests unrelated capabilities or credentials.

Instruction Scope

SKILL.md contains guidance, preferences, decisions, and links to official Stripe docs. It does not instruct the agent to read files, access environment variables, call external endpoints beyond citing Stripe docs URLs, or collect/transmit user data.

Install Mechanism

No install spec and no code files are present (instruction-only). That minimizes disk writes or arbitrary code execution risk.

Credentials

The skill declares no required environment variables, no primary credential, and no config paths. That is proportional for a knowledge/guide skill and avoids unnecessary access to secrets.

Persistence & Privilege

always is false and the skill is user-invocable. Model invocation is allowed (the platform default) but the skill does not request elevated or persistent privileges or modify other skills/configuration.

Assessment

This skill is a read-only set of Stripe best-practice recommendations and appears internally consistent. It will not access your Stripe account or secrets as-is. If you later want the agent to perform live Stripe actions (create customers, charge cards, migrate data), only grant the minimal Stripe API key needed and avoid sharing raw PANs in the agent chat — follow PCI rules. If you need automation, prefer scoped test keys, short-lived credentials, and review any future skill updates that add install steps or request environment variables.

Best practices for building Stripe payment integrations

Keywords

stripe, payment, checkout, subscription, billing

Intents

• integrate payment processing
• handle subscriptions
• process credit cards

Constraints

Never

• Charges API
• Sources API
• Card Element
• Payment Element in card-only mode
• Tokens API (unless specific need)
• mixing Connect charge types
• legacy Connect terms (Standard/Express/Custom)

Always

• latest API/SDK version (unless specified otherwise)
• advise PCI compliance proof for raw PAN handling
• use controller properties for Connect (not legacy terms)

Preferences

• Prefer CheckoutSessions over PaymentIntents when on-session payments
• Prefer Stripe-hosted Checkout over embedded Checkout when default choice
• Prefer embedded Checkout over Payment Element when more control needed
• Prefer dynamic payment methods over explicit payment_method_types when using Payment Element
• Prefer SetupIntents over Sources when saving payment methods
• Prefer Confirmation Tokens over createPaymentMethod/createToken when inspecting card before payment
• Prefer Billing APIs over raw PaymentIntents when subscriptions/recurring
• Prefer direct charges over destination charges when platform wants Stripe to take risk
• Prefer destination charges over direct charges when platform accepts liability

Decisions

• When user wants Charges API: advise migration to CheckoutSessions or PaymentIntents
• When user wants Card Element: advise migration to Payment Element
• When recurring revenue / subscription / SaaS: recommend Billing APIs + Checkout frontend
• When platform / marketplace / Connect: follow integration recommendations, use controller properties
• When migrating PAN data from another processor: point to migration process
• When render Payment Element before creating intent: use Confirmation Tokens

References

• stripe:integration-options - primary integration design reference
• stripe:api-tour - API overview
• stripe:go-live - pre-launch checklist
• stripe:migration/charges - Charges to PaymentIntents migration
• stripe:migration/payment-element - Card Element to Payment Element migration
• stripe:billing/design-integration - subscription integration planning
• stripe:connect/recommendations - Connect charge type selection
• stripe:pan-import - PAN data migration

---

Converted from UASP format (knowledge skill)