Stripe Mock Server

beginner

Local Stripe API mock for testing.

Overview

Stripe-mock is an official testing server developed by Stripe that simulates the complete Stripe API locally without making real API calls or processing actual payments. Created to solve the challenge of testing payment integrations during development, stripe-mock returns realistic HTTP responses that match Stripe's production API behavior, including proper status codes, response structures, and error conditions. This eliminates the need for test API keys and prevents cluttering your Stripe dashboard with test data during rapid development cycles. This Docker configuration deploys stripe-mock with both HTTP and HTTPS endpoints, allowing developers to test payment flows, webhook handling, and subscription management without external dependencies. The server operates statelessly, meaning each request is processed independently without persisting data between calls, making it perfect for unit tests and continuous integration pipelines. The dual-port setup enables testing of both secure and non-secure integrations depending on your application's requirements. Development teams building e-commerce platforms, SaaS applications with subscription billing, or any payment-enabled application will benefit from this local testing environment. Unlike Stripe's test mode which still requires network calls and can be affected by API rate limits, stripe-mock provides instant responses and unlimited request capacity. This makes it invaluable for automated testing suites, offline development, and scenarios where you need predictable, fast payment processing simulation.

Key Features

Complete Stripe API v1 compatibility with all endpoints including PaymentIntents, SetupIntents, Customers, and Subscriptions
Dual HTTP (port 12111) and HTTPS (port 12112) server support for testing different security configurations
Stateless operation ensuring clean test environments with no data persistence between requests
Realistic error simulation including card decline scenarios, authentication failures, and rate limiting responses
Webhook endpoint simulation for testing payment status updates and subscription lifecycle events
Zero external dependencies allowing completely offline payment integration testing
Instant response times eliminating network latency from development and testing workflows
Support for all Stripe SDK languages with simple base URL configuration changes

Common Use Cases

1E-commerce platform development requiring extensive payment method testing without processing real transactions
2SaaS application subscription billing integration testing including plan changes, upgrades, and cancellations
3Continuous integration pipelines needing fast, reliable payment API responses for automated test suites
4Offline development environments where internet connectivity is limited or unreliable
5Payment integration workshops and training sessions requiring consistent, predictable API responses
6Load testing payment workflows without hitting Stripe's API rate limits or generating test charges
7Multi-developer teams needing isolated payment testing without shared test account conflicts

Prerequisites

Docker and Docker Compose installed with at least 512MB available memory for the container
Ports 12111 and 12112 available on the host system for HTTP and HTTPS endpoints
Basic understanding of Stripe API concepts including PaymentIntents, Customers, and webhook handling
Existing application code using Stripe SDK or direct API calls that can be reconfigured to use local endpoints
Development environment setup allowing modification of API base URLs in your payment integration code

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  stripe-mock: 
3    image: stripe/stripe-mock:latest
4    container_name: stripe-mock
5    restart: unless-stopped
6    ports: 
7      - "12111:12111"
8      - "12112:12112"

.env Template

.env

1# No configuration needed

Usage Notes

1Docs: https://github.com/stripe/stripe-mock
2HTTP API at http://localhost:12111, HTTPS at :12112
3Point Stripe SDK: stripe.api_base = 'http://localhost:12111'
4Returns realistic mock responses for all Stripe endpoints
5Test PaymentIntents, Customers, Subscriptions, Webhooks
6Stateless - each request is independent

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  stripe-mock:
5    image: stripe/stripe-mock:latest
6    container_name: stripe-mock
7    restart: unless-stopped
8    ports:
9      - "12111:12111"
10      - "12112:12112"
11EOF
12
13# 2. Create the .env file
14cat > .env << 'EOF'
15# No configuration needed
16EOF
17
18# 3. Start the services
19docker compose up -d
20
21# 4. View logs
22docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/stripe-mock/run | bash

Troubleshooting

Connection refused on ports 12111/12112: Verify ports are not in use by other applications and check firewall settings allowing local connections
SSL certificate errors on HTTPS port 12112: stripe-mock uses self-signed certificates, configure your HTTP client to accept invalid certificates for testing
Stripe SDK not connecting to mock server: Ensure you've set stripe.api_base to 'http://localhost:12111' before making API calls
Webhook endpoints not receiving events: stripe-mock doesn't automatically send webhooks, manually trigger them using the mock server's webhook simulation endpoints
Inconsistent test results between runs: Remember stripe-mock is stateless, recreate any required objects (customers, payment methods) in each test case
Container exits immediately: Check Docker logs for port binding conflicts or insufficient memory allocation for the stripe-mock process

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

stripe-mock

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download