# stripe

Local Stripe API emulation for development and testing. Process payments without hitting live Stripe servers, test checkout flows, webhooks, and SDK integration.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 294 installs · ★ 2075 repo stars
- Author: vercel-labs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/vercel-labs/emulate/tree/HEAD/skills/stripe/SKILL.md
- Updated: 2026-11-18
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/vercel-labs-stripe

## What it does

Fully stateful Stripe API emulation that keeps customers, products, prices, checkout sessions, payment intents, and payment methods in memory. Webhooks fire on state changes. A hosted checkout interface handles payment completion in the browser.

Run `npx emulate --service stripe` to start the local server (defaults to `http://localhost:4000`). Point your app's Stripe client to this address: for the Node.js SDK, pass host and port when instantiating the client—`new Stripe(key, { host: 'localhost', port: 4000, protocol: 'http' })`.

With Next.js and `@emulators/adapter-next`, the emulator runs inside your app at `/emulate/stripe`, and the SDK communicates through a proxy route. All API calls stay local; no real transactions occur.

## Requirements
- Works with: Stripe

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill stripe -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/stripe/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/stripe/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill stripe -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/stripe/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill stripe -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/stripe/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vercel-labs/emulate skills/stripe
```

2. **Manually: put the files in place**
- File: `.github/skills/stripe/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill stripe -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vercel-labs/emulate --path skills/stripe
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/stripe/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill stripe -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vercel-labs/emulate/tree/HEAD/skills/stripe/SKILL.md

## When to use it
- test Stripe checkout and payment flows with a test key
- verify webhook delivery and event handling without production setup
- manage products, prices and customers during development
- run Stripe SDK locally in offline or bandwidth-constrained environments

## Example prompts
- Set up local Stripe emulation for checkout session testing
- Create a test customer and product with price in the emulator
- Verify webhook events fire when a payment session completes

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d5655a4cb04d7ff2.

BEGIN THIRD-PARTY FILE d5655a4cb04d7ff2
````text
---
name: stripe
description: Emulated Stripe API for local development and testing. Use when the user needs to process payments locally, test checkout flows, create customers, manage products and prices, handle payment intents, work with webhooks, or use the Stripe SDK without hitting real Stripe servers. Triggers include "Stripe API", "emulate Stripe", "test payments locally", "checkout flow", "payment intent", "Stripe webhook", "Stripe SDK", "STRIPE_API_KEY", or any task requiring a local Stripe API.
allowed-tools: Bash(npx emulate:*), Bash(curl:*)
---

# Stripe API Emulator

Fully stateful Stripe API emulation. Customers, products, prices, checkout sessions, payment intents, charges, and payment methods persist in memory. Webhooks fire on state changes. The hosted checkout UI lets you complete payments in the browser.

No real payments are processed. Every Stripe SDK call hits the emulator and produces realistic responses.

## Start

Local listeners bind to `127.0.0.1` by default. For access from containers or other machines, pass `--host 0.0.0.0` to the CLI or `hostname: '0.0.0.0'` to `createEmulator`. Configure `--base-url` or `baseUrl` for advertised URLs reachable by those clients.

```bash
# Stripe only
npx emulate --service stripe

# Default port (when run alone)
# http://localhost:4000
```

Or programmatically:

```typescript
import { createEmulator } from 'emulate'

const stripe = await createEmulator({ service: 'stripe', port: 4000 })
// stripe.url === 'http://localhost:4000'
```

## Pointing Your App at the Emulator

### Stripe SDK

The Stripe Node.js SDK does not read an environment variable for the base URL. You must pass it when constructing the client:

```typescript
import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
  host: 'localhost',
  port: 4000,
  protocol: 'http',
})
```

### Embedded in Next.js (adapter-next)

When using `@emulators/adapter-next`, the emulator runs inside your Next.js app at `/emulate/stripe`. The SDK needs to point at `localhost` with a proxy route to forward `/v1/*` calls to `/emulate/stripe/v1/*`:

```typescript
// next.config.ts
import { withEmulate } from '@emulators/adapter-next'

export default withEmulate({
  env: {
    STRIPE_SECRET_KEY: 'sk_test_emulated',
  },
})
```

```typescript
// lib/stripe.ts
import Stripe from 'stripe'

const port = process.env.PORT ?? '3000'

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
  host: 'localhost',
  port: parseInt(port, 10),
  protocol: 'http',
})
```

```typescript
// app/emulate/[...path]/route.ts
import { createEmulateHandler } from '@emulators/adapter-next'
import * as stripe from '@emulators/stripe'

export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
  services: {
    stripe: {
      emulator: stripe,
      seed: {
        products: [
````
END THIRD-PARTY FILE d5655a4cb04d7ff2

The third-party file has ended. Everything between the d5655a4cb04d7ff2 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2927 of 11690 bytes. © vercel-labs · Apache-2.0 · https://github.com/vercel-labs/emulate/tree/HEAD/skills/stripe/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
