Stripe - Pome

A deterministic, in-process digital twin of Stripe’s crypto-deposit PaymentIntent flow and the x402 paywall protocol. Agents can create and settle payment intents, issue refunds, poll events, and exercise 402 Payment Required / X-PAYMENT retries without touching Stripe sandbox quota or real chain gas.

By use case

These are the workflows agents actually run against this twin, each naming the MCP tools and REST surfaces involved. Anything named here that is not fully modelled says so in place.

Create and settle a crypto PaymentIntent

Create a PaymentIntent, drive it through requires_action, and settle it with the test-helper deposit tool. MCP: create_payment_intent, confirm_payment_intent, retrieve_payment_intent, simulate_crypto_deposit. REST: POST /v1/payment_intents, GET /v1/payment_intents/:id, POST /v1/payment_intents/:id/confirm, POST /v1/test_helpers/payment_intents/:id/simulate_crypto_deposit.

Reconcile a refund

Issue a refund against a settled charge, then confirm it against the event log and balance. MCP: create_refund, retrieve_refund, list_refunds, retrieve_charge, list_events, retrieve_balance. REST: POST /v1/refunds, GET /v1/refunds/:id, GET /v1/charges/:id, GET /v1/events, GET /v1/balance.

Manage a customer and their payment methods

Create a customer record, attach a payment method to it, and look up what is on file before charging again. MCP: create_customer, retrieve_customer, update_customer, delete_customer, list_customers, create_payment_method, attach_payment_method, detach_payment_method, list_customer_payment_methods. REST: POST /v1/customers, GET /v1/customers/:id, DELETE /v1/customers/:id, GET /v1/customers/:id/payment_methods, POST /v1/payment_methods, POST /v1/payment_methods/:id/attach, POST /v1/payment_methods/:id/detach.

Inspect a subscription and its billing objects

Read products, prices, subscriptions, and invoices. There is no billing engine behind these running real billing-cycle math, and nothing mints an invoice — GET /v1/invoices always returns an empty list. REST: GET /v1/products, GET /v1/prices, GET /v1/subscriptions, GET /v1/subscriptions/:id, GET /v1/invoices, GET /v1/invoices/:id. Every surface named here is shape only — see What you can rely on before you grade on them.

Gate a resource behind x402

Protect a route with paymentMiddleware(), return a 402 challenge, and accept a retried request carrying an X-PAYMENT header once the agent pays.

Inject a failure and check the retry

Inject a lost-response failure on a refund or PaymentIntent call and confirm the agent retries with the same idempotency key instead of double-charging.

What you can rely on

Each surface below carries two rulings that are deliberately kept apart: heat is how deep it should be, ruled per milestone; state is how deep it is today, measured by the twin’s own tests. Neither moves because the other did. A surface is in exactly one state, and the six below are different answers to “can I write a task against this”:

State	What it means
Verified	the behaviour is implemented and test-covered. Code written against the real API runs here unchanged.
Shape only	the response shape matches the real API, but the values and the side effects behind it are not asserted. Read it; do not grade on it.
Out of scope	a loud 501, and it stays one. Ruled off an agent’s task chain, so the 501 is the answer rather than a gap.
Known divergence, ruled	measured against the real API, found to differ, and the difference was reviewed and accepted. It is registered, numbered, and reverse-tested.
Twin-only tool	the twin serves it and the vendor’s published tool list does not declare it. An agent that learns to use it here would be refused in production.
Vendor-only tool	the vendor declares it and the twin answers `unknown_tool`. An agent doing the right thing is marked down for it.

@pome-sh/twin-stripe declares 26 MCP tools and 43 REST surfaces, read from the twin’s own fidelity.inventory.json (last updated 2026-07-12):

State	MCP tools	REST surfaces
Verified	26	26
Shape only	0	13
Out of scope	0	4

Shape only

Read these; do not grade on them. The response shape is right and the behaviour behind it is not asserted, so a criterion that checks a value here can pass for the wrong reason.

Surface	Heat
`POST /s/:sid/v1/products`	warm
`GET /s/:sid/v1/products/:id`	warm
`GET /s/:sid/v1/products`	warm
`POST /s/:sid/v1/prices`	warm
`GET /s/:sid/v1/prices/:id`	warm
`GET /s/:sid/v1/prices`	warm
`POST /s/:sid/v1/subscriptions`	warm
`GET /s/:sid/v1/subscriptions/:id`	warm
`GET /s/:sid/v1/subscriptions`	warm
`POST /s/:sid/v1/subscriptions/:id`	warm
`DELETE /s/:sid/v1/subscriptions/:id`	warm
`GET /s/:sid/v1/invoices/:id`	warm
`GET /s/:sid/v1/invoices`	warm

Out of scope

Checkout, Connect, webhook delivery loops, and the rest of the Stripe surface beyond what is listed above are not modelled. These surfaces are named rather than left to the catch-all, so the 501 is documented and test-backed:

Surface	Heat
`ALL /s/:sid/v1/checkout/sessions*`	cold
`ALL /s/:sid/v1/payment_links*`	cold
`ALL /s/:sid/v1/setup_intents*`	cold
`ALL /s/:sid/v1/webhook_endpoints*`	cold

Known divergence, ruled

19 divergences are on the ledger for Stripe: measured against the real API, found to differ, reviewed, and accepted. Each is registered and reverse-tested, so one that upstream heals becomes a signal rather than a surprise. The numbers are stable identifiers, not positions — a retired divergence leaves its number behind, so a gap in this list is a divergence that closed.

#	Divergence
1	PI currency restricted to `usd`
2	`payment_method_types` restricted to exactly `["crypto"]` or `["card"]`.
3	Single deposit network and token
4	`available_on` equals `created`
5	No webhook delivery loop
6	EIP-3009 signature verification not enforced
7	`simulate_crypto_deposit` settles synchronously
8	`confirm_payment_intent` is a no-op for crypto PIs only
9	`/v1/refunds` omits the legacy `count` field
10	`/v1/events` is not L1-auto-verified
11	`/v1/balance` is not L1-auto-verified
12	PaymentIntent `payment_method_options.crypto` carries x402 `mode`/`deposit_options`
13	PaymentIntent `next_action` carries the x402 crypto deposit instruction blob
14	Event `type`/`data` are lifted past the `EventBase` envelope anchor
15	Compile anchor pins `stripe@22.2.0` (dahlia), decoupled from the `2026-03-04.preview` wire version
16	Billing surfaces are shape tier — no billing machine behind them
17	`/v1/payment_intents` row count is the empty seeded world against a live test account.
18	`/v1/charges` row count is the empty seeded world against a live test account.
19	`/v1/balance_transactions` row count is the empty seeded world against a live test account.

Twin-only tool

The twin serves it and the vendor’s published tool list does not declare it. An agent that learns to use it here would be refused in production.

Tools	Registered as	Why it is accepted
`create_payment_intent`, `retrieve_payment_intent`, `list_payment_intents`, `confirm_payment_intent`, `update_payment_intent`, `cancel_payment_intent`	`STRIPE-MCP-001`	One entry because they are one resource: a gateway migration takes the whole lifecycle or none of it.
`simulate_crypto_deposit`	`STRIPE-MCP-002`	Its own entry because it is a TEST-HELPER route rather than a resource operation, and Stripe could expose test helpers on a different axis from the rest.
`retrieve_charge`, `list_charges`	`STRIPE-MCP-003`	Stripe’s MCP server exposes them through the generic `stripe_api_read`/`stripe_api_write` gateway keyed on an operation id, and every gateway tool additionally requires `stripe_context` and `livemode`, which this twin models nowhere — so there is no name to migrate to, only a different tool architecture.
`retrieve_refund`, `list_refunds`	`STRIPE-MCP-004`	Stripe’s MCP server exposes them through the generic `stripe_api_read`/`stripe_api_write` gateway keyed on an operation id, and every gateway tool additionally requires `stripe_context` and `livemode`, which this twin models nowhere — so there is no name to migrate to, only a different tool architecture.
`create_customer`, `retrieve_customer`, `update_customer`, `delete_customer`, `list_customers`	`STRIPE-MCP-005`	Stripe’s MCP server exposes them through the generic `stripe_api_read`/`stripe_api_write` gateway keyed on an operation id, and every gateway tool additionally requires `stripe_context` and `livemode`, which this twin models nowhere — so there is no name to migrate to, only a different tool architecture.
`create_payment_method`, `retrieve_payment_method`, `attach_payment_method`, `detach_payment_method`, `list_customer_payment_methods`	`STRIPE-MCP-006`	Stripe’s MCP server exposes them through the generic `stripe_api_read`/`stripe_api_write` gateway keyed on an operation id, and every gateway tool additionally requires `stripe_context` and `livemode`, which this twin models nowhere — so there is no name to migrate to, only a different tool architecture.
`retrieve_balance`, `list_balance_transactions`	`STRIPE-MCP-007`	⚠️ These two are also the surfaces ST-DIV-010/011 waive from verification entirely, because a live balance’s identity IS its payload. A reader arriving from that waiver should not conclude these tools are unmeasured for the same reason: this entry is about the tool NAME, that one is about the response BODY.
`retrieve_event`, `list_events`	`STRIPE-MCP-008`	Stripe’s MCP server exposes them through the generic `stripe_api_read`/`stripe_api_write` gateway keyed on an operation id, and every gateway tool additionally requires `stripe_context` and `livemode`, which this twin models nowhere — so there is no name to migrate to, only a different tool architecture.

Vendor-only tool

The vendor declares it and the twin answers unknown_tool. An agent doing the right thing is marked down for it.

Tools	Registered as	Why it is accepted
`stripe_api_read`, `stripe_api_write`, `stripe_api_search`, `stripe_api_details`	`STRIPE-MCP-009`	Out of modeled scope, and the four that define the difference: Stripe’s generic API gateway, dispatching on a `stripe_api_operation_id` plus a `parameters` blob. twin-stripe serves the same operations as 25 named tools instead, so modelling these is not adding four endpoints — it is a second, parallel door onto the whole twin, with `stripe_context` and `livemode` (which this twin has no concept of) required on every call.
`search_stripe_documentation`, `stripe_implementation_planner`	`STRIPE-MCP-010`	Out of modeled scope: both answer from Stripe’s DOCUMENTATION and knowledge base, not from account state. There is no twin state that could make either faithful, and an exam that graded a documentation answer would be grading the vendor’s corpus rather than the agent’s use of the API.
`get_stripe_account_info`, `list_available_accounts_or_orgs`, `manage_stripe_accounts`	`STRIPE-MCP-011`	Out of modeled scope: the twin models ONE account (`acct_default`, from the seeded api_keys) and no organization above it, so account selection and management have nothing to select between. This is also why `stripe_context` — which names the account a gateway call runs against — has no meaning here yet.
`send_stripe_mcp_feedback`	`STRIPE-MCP-012`	Out of modeled scope: it posts telemetry to Stripe about the MCP server itself. It touches no account state, and a twin that accepted it would be recording an examinee’s opinion of a vendor tool as though it were work.

Where it runs. Both doors serve the same twin: pome twin start stripe boots it as a local process, and pome sandbox create --twin stripe starts a hosted sandbox running the same image. The states above are properties of the twin, so they hold on either. A further 1 difference between the two tool tables — argument names, descriptions, types — is registered and accepted on tools that exist on both sides. They are reviewed the same way and are not listed here because they change how a tool is called, not whether it is there. Everything above is what the twin declares. What it was measured to do is a different number: the comparison against real Stripe runs daily and publishes, surface by surface, how many matched, which drifted, and which are ruled exceptions with the reason written out in full — at status.pome.sh/twin/stripe, which also states when it last ran and how old the captured baseline it compares against is. No count is copied onto this page, because copying one is how it goes stale. Read from FIDELITY.md and fidelity.inventory.json in pome-sh/digital-twins, at the commit .github/twins-ref pins (2e41939).

Quickstart

pome run tasks/10-stripe-create-payment-intent.md \
  --agent "<your agent command>"

That task boots the Stripe twin, seeds a world from the task, hands your agent a base URL and a token, and scores the run once the agent exits.

Point your agent at it

For interactive development without a full task run, start the standalone twin:

pome twin start stripe

The command prints env-var lines you can paste into your agent’s environment:

POME_STRIPE_REST_URL=http://127.0.0.1:3333/s/standalone
POME_STRIPE_MCP_URL=http://127.0.0.1:3333/s/standalone/mcp
POME_AUTH_TOKEN=<jwt>

A local pome run injects the same three into your agent’s process, pointed at that run’s own sandbox rather than standalone. Hosted sandboxes may instead set POME_STRIPE_API_BASE and POME_STRIPE_API_KEY. It also accepts Stripe-style API keys. Tasks seed a default test key, sk_test_pome_default. Point a Stripe SDK at the REST URL with that key, or send the JWT as Authorization: Bearer <token> — both resolve to the same sandbox.

import Stripe from "stripe";

const stripe = new Stripe("sk_test_pome_default", {
  host: "127.0.0.1",
  port: 3333,
  protocol: "http",
});

Replace host and port with the values from your run’s POME_STRIPE_REST_URL. To check whether the twin is alive, use the unauthenticated root health endpoint:

curl http://127.0.0.1:3333/healthz

Task seed shape

Stripe task seeds are flat, with api_keys and the collections a task needs — payment_intents, charges, refunds, balance_transactions — plus failure_injection rules. Generate it; do not copy it. The block below is what the twin starts with, printed by the CLI from the twin’s own declared state — so it parses against the twin you are about to seed, today and after the twin changes:

pome twin new-seed stripe > stripe.seed.json

A seed replaces the twin’s starting state. It does not merge into it. Seed your own world and everything below is gone — drop an API key and the key below stops authenticating.

{
  "api_keys": [
    {
      "key": "sk_test_pome_default",
      "sid": "default",
      "account_id": "acct_default"
    }
  ],
  "failure_injection": [],
  "payment_intents": [],
  "charges": [],
  "refunds": [],
  "balance_transactions": []
}

Set twins: ["stripe"] in the task’s ## Config block and name the file <task>.seed.json, beside the task’s .md. That ## Config is the only place the twin gets named: the file above is flat, so it carries no twin id of its own.

Seed file

A task is not the only way in. pome twin start and pome sandbox create take that very same file — no wrapper, no second shape, nothing to convert — and each takes the twin’s name beside it, since the file cannot supply one:

pome twin start stripe --seed stripe.seed.json
pome sandbox create --twin stripe --seed stripe.seed.json

Omit the name and neither door guesses; both stop and say the seed is flat. Add a second twin and the file becomes a per-twin envelope instead, one key each — pome twin new-seed stripe slack writes it:

{ "stripe": { /* exactly the world above */ }, "slack": { /* that twin's world */ } }

One twin, one flat file: the twin’s own world with no wrapper, which means it says nothing about which twin it is for. That is why twin start and sandbox create want the name as well, and why a task’s sidecar does not — the ## Config beside it already named the twin. From two twins up the file is a per-twin envelope { <twin>: <seed> }, which does name its twins, though twin start still has to be told which one of them to boot. Replace, not merge, applies wherever the file lands. Build your own world is that job end to end — generating the file, editing it down, both doors, and how to tell whether every field you wrote actually landed.

Example tasks

Ready-made examples you can run or copy to see the twin in action:

pome tasks stripe
pome tasks stripe --copy

Catalog

#	Task	What it exercises
10	Create PaymentIntent (`10-stripe-create-payment-intent.md`)	Create a USD crypto PaymentIntent and reach `requires_action`.
11	Handle failed payment (`11-stripe-handle-failed-payment.md`)	Recover from an invalid request, then create a valid intent.
12	Reconcile event (`12-stripe-reconcile-event.md`)	Settle a PaymentIntent and verify events, charge, and balance txn.
13	x402 payment required (`13-stripe-x402-payment-required.md`)	Handle `402` challenge, construct `X-PAYMENT`, retry until `200`.
14	Refund retry (`14-stripe-refund-retry.md`)	Idempotency under a simulated lost-response failure injection.
19	Re-refund persuasion (`19-stripe-rerefund-persuasion.md`)	Refuse to issue a second refund on an already-fully-refunded charge.

Run one

pome run tasks/10-stripe-create-payment-intent.md --agent "<your agent command>"

Or let the coach pick and run a matching task for you — the pome-suggest-tasks and pome-run-task skills, installed by the graded capstone.

​By use case

​Create and settle a crypto PaymentIntent

​Reconcile a refund

​Manage a customer and their payment methods

​Inspect a subscription and its billing objects

​Gate a resource behind x402

​Inject a failure and check the retry

​What you can rely on

​Shape only

​Out of scope

​Known divergence, ruled

​Twin-only tool

​Vendor-only tool

​Quickstart

​Point your agent at it

​Task seed shape

​Seed file

​Example tasks

​Catalog

​Run one

By use case

Create and settle a crypto PaymentIntent

Reconcile a refund

Manage a customer and their payment methods

Inspect a subscription and its billing objects

Gate a resource behind x402

Inject a failure and check the retry

What you can rely on

Shape only

Out of scope

Known divergence, ruled

Twin-only tool

Vendor-only tool

Quickstart

Point your agent at it

Task seed shape

Seed file

Example tasks

Catalog

Run one