> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twinbay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Payment intents, charges, refunds, disputes and payouts as state machines over a real clock

The Stripe API in test mode, for the money side of an ecommerce agent: charge a
customer, survive a decline and retry the same intent, answer a dispute before
its deadline, reconcile a payout against the balance transactions inside it.
Stripe's own `stripe-mock` returns spec-shaped fixtures and remembers nothing;
this twin's whole point is the state `stripe-mock` gives up on — it remembers
the charge you made, moves money from `pending` to `available` when time
advances, and lets an unanswered dispute deadline become `lost`.

**Slug:** `stripe`

## What it models

| Area | Modelled |
| - | - |
| Starting account | A US test-mode account, `usd` default currency, standard 2.9% + 30¢ card pricing — and otherwise empty, because a real Stripe account starts empty; seeds are what fill one |
| Authentication | The `sk_test_…` secret key as a Bearer token — what stripe-python always sends — and the legacy basic form, with Stripe's real 401s: the missing-key message, the star-redacted echo of an unknown key, and the `pk_`/`rk_` refusals |
| Wire | Bracket-nested form encoding exactly as stripe-python 15.6.1 sends it, the one `{"error": {...}}` envelope every SDK exception is built on, `Request-Id` on processed operation responses but not authentication, invalid-version, unsupported-content, rate-limit or unknown-URL refusals, and Stripe's clamped-limit cursor pagination |
| Payments | Customers, payment methods from Stripe's test tokens, payment intents through the whole status machine (manual and automatic capture, test-card declines carrying `decline_code` and the intent itself, retry after decline), and the charges behind them |
| Money | Balance transactions whose `fee`, `fee_details` and `net` always reconcile against a modelled rate, the derived `available`/`pending` balance, refunds with their reversals, disputes with real evidence deadlines, and payouts that group what became available |
| Catalog, search and events | Products and prices (one-time, recurring, zero-decimal currencies), search across customers, payment intents, charges, products and prices, and an event log with Stripe's own `type` strings as the queryable read model |
| Idempotency | The SDK sends an `Idempotency-Key` on every POST, so replays return the original response, mismatched reuse is refused, and keys expire after Stripe's 24-hour window when the environment advances |

Weird money states come from directives — `open_dispute`, `settle_balance`,
`force_decline`, `fail_payout`, `network_flake` and friends — because no
provider call can create them, which is exactly why they are worth modelling.

## Not modelled

Everything subscription-shaped (subscriptions, invoices, checkout sessions,
setup intents), Connect, Issuing, Terminal, Radar, Treasury, tax, files and
webhook delivery (events exist as a queryable log; nothing is pushed). An
operation Stripe has that the twin has not built answers an explicit
`501` refusal with a code Stripe never sends, never a plausible response; a URL
Stripe does not have gets Stripe's own unrecognized-URL 404, verbatim.