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

# experimental_StripePaymentIntentPlugin

> Add Stripe PaymentIntent-based payments to your agent server

Adds Stripe PaymentIntent creation and validation to an `AixyzApp`, providing an alternative payment method alongside [x402](/protocols/x402).

```typescript theme={null}
import { experimental_StripePaymentIntentPlugin } from "@aixyz/stripe";
```

<Warning>This API is experimental and may change significantly in future releases.</Warning>

## Installation

```bash theme={null}
bun add @aixyz/stripe
```

## Usage

```typescript theme={null}
await server.withPlugin(new experimental_StripePaymentIntentPlugin());
```

## Environment Variables

| Variable             | Required | Default | Description                    |
| -------------------- | -------- | ------- | ------------------------------ |
| `STRIPE_SECRET_KEY`  | Yes      | —       | Stripe secret key              |
| `STRIPE_PRICE_CENTS` | No       | `100`   | Price per request in USD cents |

If `STRIPE_SECRET_KEY` is not set, the function is a no-op — no endpoints or middleware are registered.

## Registered Endpoints

### `POST /stripe/create-payment-intent`

Creates a new Stripe PaymentIntent for the configured price.

**Response:**

```json theme={null}
{
  "clientSecret": "pi_xxx_secret_xxx",
  "paymentIntentId": "pi_xxx"
}
```

## Payment Middleware

After registering the `experimental_StripePaymentIntentPlugin`, the server checks incoming requests for the `x-stripe-payment-intent-id` header:

1. If the header is present, it validates the PaymentIntent:
   * Status must be `succeeded`
   * Amount must meet the configured `STRIPE_PRICE_CENTS`
   * Payment must not have been already consumed
2. Valid payments are marked as consumed (one-time use) and the request proceeds
3. Invalid payments return `402 Payment Required`
4. If no header is present, the request falls through to x402 middleware

## Usage

Use in a [custom server](/api-reference/agent) (`app/server.ts`):

```typescript title="app/server.ts" theme={null}
import { AixyzApp } from "aixyz/app";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import { experimental_StripePaymentIntentPlugin } from "@aixyz/stripe";
import * as agent from "./agent";

const server = new AixyzApp();

await server.withPlugin(new IndexPagePlugin());

// Register Stripe before other plugins so the Stripe middleware runs first
await server.withPlugin(new experimental_StripePaymentIntentPlugin());

await server.withPlugin(new A2APlugin([{ exports: agent }]));

await server.initialize();

export default server;
```

<Note>
  Register the `experimental_StripePaymentIntentPlugin` **before** A2A or MCP plugins so the Stripe middleware runs
  first. If a valid Stripe payment is found, x402 verification is skipped.
</Note>