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

# Stripe

> Stripe Scenario seeding parameters, nested fields, and examples

Use `stripe` in `twins` and put this configuration under `seed_config.stripe`.

Stripe account with customers, products, prices, billing meters, and meter events.

## Example seed

This is the complete Scenario request body for [creating a Scenario](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`.

```json theme={null}
{
  "name": "Stripe eval fixture",
  "twins": [
    "stripe"
  ],
  "seed_config": {
    "stripe": {
      "base_time": null,
      "assistant": {
        "enabled": false,
        "mode": "scenario",
        "display_name": "there",
        "business_name": "your business",
        "responses": []
      },
      "access": {
        "api_keys": {
          "sk_test_twin_scenario": {
            "permissions": {
              "*": "write"
            }
          }
        },
        "users": {
          "user_twin": {
            "name": "Test user",
            "roles": [
              "administrator"
            ]
          }
        },
        "sessions": {
          "stripe_fixture_session": "user_twin"
        },
        "default_session": "stripe_fixture_session"
      },
      "settlement": {},
      "account_settings": {
        "type": "standard",
        "country": "US"
      },
      "advanced": {
        "accounts": [],
        "cardholders": [],
        "cards": [],
        "locations": [],
        "readers": [],
        "registrations": [],
        "rules": [],
        "apps": []
      },
      "support": {
        "customers": [
          {
            "id": "cus_support_customer",
            "name": "Support Customer",
            "email": "support-customer@example.com"
          }
        ],
        "payments": [
          {
            "id": "pi_support_payment",
            "charge_id": "ch_support_payment",
            "customer": "cus_support_customer",
            "amount": 4900,
            "currency": "usd",
            "description": "Original customer purchase",
            "created": null
          }
        ],
        "refunds": [
          {
            "id": "re_support_prior",
            "payment_intent": "pi_support_payment",
            "amount": 1200,
            "created": null
          }
        ]
      },
      "customers": [
        {
          "name": "Customer Name",
          "email": "customer@example.com"
        }
      ],
      "products": [
        {
          "name": "Product Name",
          "prices": [
            {
              "unit_amount": 2000,
              "currency": "usd"
            }
          ]
        }
      ],
      "meters": [
        {
          "display_name": "API Calls",
          "event_name": "api_calls",
          "aggregation": "sum",
          "events": [
            {
              "customer": "cus_seed_customer",
              "value": 42
            }
          ]
        }
      ]
    }
  }
}
```

## Parameters

The following fields belong directly inside `seed_config.stripe`. Required nested fields are marked in their tables. Provider-native objects can contain service-specific fields beyond the representative record shapes below.

| Parameter | Type | Description |
| - | - | - |
| `base_time` | `string` | Reference clock for repeatable fixtures. Omit to use the current clock. |
| `assistant` | `AssistantConfig` | Configured Stripe dashboard Help responses. |
| `access` | `object` | Stripe API-key and Dashboard-user permissions. |
| `settlement` | `object` | Settlement currencies, conversion rates, and fees. |
| `account_settings` | `object` | Stripe account settings for the configured fixture. |
| `advanced` | `object` | Additional Stripe Connect, Issuing, Terminal, Tax, Radar, and app-installation fixtures. |
| `support` | `SupportSeed` | Historical support-payment fixtures with stable customer, payment, charge, and refund identifiers. |
| `customers` | `object[]` | Customers fixtures in provider-native format. |
| `products` | `object[]` | Products fixtures in provider-native format. |
| `meters` | `object[]` | Meters fixtures in provider-native format. |

## Resource fields

These tables describe the record shapes used by the example. Keep native field names and casing. Map keys such as property names, IDs, and metadata keys are supplied by your fixture.

### `customers[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `email` | `string` | Main account email address. |
| `description` | `string` | Description. |
| `metadata` | `object` | Metadata. |
| `phone` | `string` | Phone. |
| `address` | `object` | Address. |

### `products[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `prices` | `object[]` | Prices fixtures in provider-native format. |
| `active` | `boolean` | Enable or set active behavior. |
| `description` | `string` | Description. |
| `metadata` | `object` | Metadata. |

### `products[].prices[]`

| Parameter | Type | Description |
| - | - | - |
| `unit_amount` | `integer` | Unit amount. |
| `currency` | `string` | Currency. |
| `recurring` | `object` | Recurring. |
| `active` | `boolean` | Enable or set active behavior. |
| `nickname` | `string` | Nickname. |
| `lookup_key` | `string` | Lookup key. |
| `metadata` | `object` | Metadata. |

### `meters[]`

| Parameter | Type | Description |
| - | - | - |
| `display_name` | `string` | Display name. |
| `event_name` | `string` | Event name. |
| `aggregation` | `string` | Aggregation. |
| `events` | `object[]` | Events fixtures in provider-native format. |

### `meters[].events[]`

| Parameter | Type | Description |
| - | - | - |
| `customer` | `string` | Customer. |
| `value` | `integer` | Value. |

### `settlement`

| Parameter | Type | Description |
| - | - | - |
| `currency` | `string` | Currency. |
| `currencies` | `string[]` | Currencies fixtures in provider-native format. |
| `rates` | `map<string, number>` | Rates keyed by identifier or resource name. |
| `fees` | `object` | Fees. |

### `settlement.fees.<currency>`

| Parameter | Type | Description |
| - | - | - |
| `fixed` | `integer` | Fixed. |
| `percent` | `number` | Percent. |
| `conversion_percent` | `number` | Conversion percent. |

### `account_settings`

| Parameter | Type | Description |
| - | - | - |
| `type` | `standard / custom / express` | Type. |
| `country` | `string` | Country. |

## Typed configuration objects

Named object types in the parameter table use these fields.

### AssistantConfig

| Parameter | Type | Description |
| - | - | - |
| `enabled` | `boolean` | Enable or set enabled behavior. |
| `mode` | `"scenario" / "live"` | Mode. |
| `display_name` | `string` | Display name. Minimum length: 1. Maximum length: 200. |
| `business_name` | `string` | Business name. Minimum length: 1. Maximum length: 200. |
| `delay_ms` | `integer` | Delay ms. Minimum: 0. Maximum: 30000. |
| `responses` | `AssistantResponse[]` | Responses fixtures in provider-native format. Maximum entries: 250. |

### AssistantResponse

| Parameter | Type | Description |
| - | - | - |
| `prompt` | `string` | **Required.** Prompt. Minimum length: 1. Maximum length: 12000. |
| `text` | `string` | **Required.** Text content. Minimum length: 1. Maximum length: 50000. |
| `links` | `AssistantLink[]` | Links fixtures in provider-native format. Maximum entries: 12. |

### AssistantLink

| Parameter | Type | Description |
| - | - | - |
| `label` | `string` | **Required.** Label. Minimum length: 1. Maximum length: 200. |
| `path` | `string` | **Required.** Path. |

### SupportSeed

| Parameter | Type | Description |
| - | - | - |
| `customers` | `Customer[]` | Customers fixtures in provider-native format. Maximum entries: 50. |
| `payments` | `Payment[]` | Payments fixtures in provider-native format. Maximum entries: 100. |
| `refunds` | `Refund[]` | Refunds fixtures in provider-native format. Maximum entries: 100. |

### Customer

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | **Required.** Explicit resource identifier, when supported. Maximum length: 128. |
| `name` | `string` | **Required.** Human-readable name. Maximum length: 200. |
| `email` | `string` | **Required.** Main account email address. Maximum length: 254. |

### Payment

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | **Required.** Explicit resource identifier, when supported. Maximum length: 128. |
| `charge_id` | `string` | **Required.** Charge id. Maximum length: 128. |
| `customer` | `string` | **Required.** Customer. Maximum length: 128. |
| `amount` | `integer` | **Required.** Amount. Minimum: 1. Maximum: 99999999. |
| `currency` | `string` | **Required.** Currency. |
| `description` | `string` | Description. Maximum length: 1000. |
| `created` | `integer or null` | Created. |

### Refund

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | **Required.** Explicit resource identifier, when supported. Maximum length: 128. |
| `payment_intent` | `string` | **Required.** Payment intent. Maximum length: 128. |
| `amount` | `integer` | **Required.** Amount. Minimum: 1. |
| `created` | `integer or null` | Created. |

## API coverage and limitations

**Twin name:** `stripe`

**Supports**

* Stripe API v1 resources for customers, payment methods, payment intents, setup intents, charges, refunds, disputes, subscriptions, invoices, invoice items, credit notes, products, prices, plans, coupons, promotion codes, tax rates, shipping rates, tokens, sources, payouts, balance, balance transactions, billing meters, meter events, events, files, checkout sessions, payment links, quotes, billing portal sessions, subscription items, schedules, usage records, tax IDs, webhook endpoints, mandates, and test clocks.
* Stripe-compatible authentication errors, idempotency keys, signed webhooks, test cards for declines and 3D Secure, checkout pages, billing portal pages, dashboard pages, product catalog, and customer management.
* Seed endpoint for starter product, price, and webhook setup.
* Stripe MCP-compatible JSON-RPC server at `POST /mcp` (and `POST /mcp/v1`) for use by MCP clients and the `@stripe/mcp` CLI bridge. The twin routes `mcp.stripe.com` through this endpoint and serves Stripe's OAuth discovery documents at `GET /.well-known/oauth-protected-resource`, `GET /.well-known/oauth-protected-resource/mcp`, and `GET /.well-known/oauth-authorization-server`. Implements `initialize`, `notifications/initialized`, `tools/list`, and `tools/call`, advertising the same 31 tools as the official Stripe MCP server (`search_stripe_documentation`, `get_stripe_account_info`, `create_customer`, `list_customers`, `create_product`, `list_products`, `create_price`, `list_prices`, `create_payment_link`, `create_invoice`, `list_invoices`, `create_invoice_item`, `finalize_invoice`, `retrieve_balance`, `create_refund`, `list_refunds`, `list_payment_intents`, `list_subscriptions`, `cancel_subscription`, `update_subscription`, `list_coupons`, `create_coupon`, `update_dispute`, `list_disputes`, `search_stripe_resources`, `fetch_stripe_resources`, `stripe_integration_recommender`, `send_stripe_mcp_feedback`, `stripe_api_search`, `stripe_api_details`, `stripe_api_execute`). MCP tool calls share state with the Stripe API and Checkout surfaces — resources created via MCP are visible through the API, dashboard, and webhooks. Requests without a `Authorization: Bearer <token>` header return `401 Unauthorized`.

**Known limitations**

* Stripe resources start empty unless seeded or created by the app under test.
* API key validation recognizes Stripe-style key prefixes and simulates authentication behavior; no real Stripe account is contacted.
* The twin models the API resources listed above; newer or specialized Stripe products outside that surface may be absent or approximated.

**MCP tools:** `get_twin_catalog`, `provision_twins`, `start_url_validation`, `get_validation_results`.

See [Scenario seeding](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.