Home › Stripe payments › Stripe payments integration AGENTS.md

Stripe payments integration AGENTS.md

AGENTS.md for Stripe integrations: Checkout and Payment Intents, verified webhooks, idempotency, and test mode only.

AGENTS.mdStripe payments

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: Stripe integration

## Safety first
- The agent works in **test mode only** (`sk_test_...`). Never use or request live keys, and never create real charges, refunds, or payouts.
- Keys come from env (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`); the publishable key is the only one allowed in client code.
- Pin the API version in the client constructor (or the SDK default) and note it in the README.

## Payments
- Prefer Stripe Checkout or the Payment Element over custom card forms. Never handle raw card numbers.
- Prices and amounts are decided on the server from your catalog (or Stripe Price ids), never trusted from the client. Amounts are integers in the smallest currency unit.
- Pass an `idempotencyKey` on create calls that could be retried (payment intents, refunds, customers).
- Store Stripe ids (`cus_`, `pi_`, `sub_`) on your records; Stripe stays the source of truth for payment state.

## Webhooks
- Verify every event with `stripe.webhooks.constructEvent(rawBody, sig, secret)` using the raw request body.
- Fulfill orders from webhooks (`checkout.session.completed`, `invoice.paid`, `customer.subscription.updated`), not from the success redirect.
- Handlers are idempotent (record processed `event.id`s), return 2xx quickly, and do slow work in a background job.

## Testing
- Local webhooks: `stripe listen --forward-to localhost:3000/api/stripe/webhook`; trigger with `stripe trigger checkout.session.completed`.
- Unit tests mock the Stripe client; use test cards (`4242 4242 4242 4242`, `4000 0000 0000 3220` for 3DS).