Mock payment gateway for testing payment integrations without real money.

Stop using real payment providers in development. AcquireMock simulates complete payment flows including OTP verification, webhooks, and card storage.

# Clone and start
git clone https://github.com/illusiOxd/acquiremock.git
cd acquiremock
docker-compose up

Visit http://localhost:8000

# Clone repository
git clone https://github.com/illusiOxd/acquiremock.git
cd acquiremock

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Copy configuration
cp .env.example .env

# Edit configuration
nano .env

# Start application
uvicorn main:app --port 8000 --reload

AcquireMock simulates a real payment gateway with complete payment lifecycle:

Basic Flow:

# 1. Create payment
curl -X POST http://localhost:8000/api/create-invoice \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "reference": "ORDER-123",
    "webhookUrl": "https://your-site.com/webhook"
  }'

# 2. User completes checkout (UI)
# 3. OTP verification via email
# 4. Webhook sent to your server
# 5. Payment confirmed

Test Card:

Card:   4444 4444 4444 4444
CVV:    any 3 digits
Expiry: any future date (MM/YY)

• Complete Payment Flow - From invoice creation to webhook delivery
• OTP Verification - Email-based payment confirmation
• Webhook Delivery - HMAC-SHA256 signed callbacks with retry logic
• Card Storage - Save cards for returning customers
• Transaction History - Track all operations per user
• Auto-Expiry - Payments automatically expire after 15 minutes
• Idempotency - Prevent duplicate payment processing
• Multi-Language UI - Support for UK/EN/DE/RU with dark mode
• Interactive Test Page - Built-in testing interface

Create .env file with these settings:

# Database (Required)
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/payment_db
# For development: sqlite+aiosqlite:///./payment.db

# Security (Required)
WEBHOOK_SECRET=your-secret-key-min-32-chars
BASE_URL=http://localhost:8000

# Email (Optional - logs to console if not configured)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASS=your-app-password

Production (PostgreSQL):

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/payment_db

Development (SQLite):

DATABASE_URL=sqlite+aiosqlite:///./payment.db

Email is optional. If not configured, OTP codes will be logged to console for testing.

For Gmail, generate an app-specific password at: https://myaccount.google.com/apppasswords

curl -X POST http://localhost:8000/api/create-invoice \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "reference": "ORDER-123",
    "webhookUrl": "https://your-site.com/webhook",
    "redirectUrl": "https://your-site.com/success"
  }'

Response:

{
  "pageUrl": "http://localhost:8000/checkout/{payment_id}"
}

import hmac
import hashlib
import json
from fastapi import Request, HTTPException

def verify_webhook(payload: dict, signature: str, secret: str) -> bool:
    """Verify HMAC-SHA256 signature"""
    message = json.dumps(payload, sort_keys=True)
    expected = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/webhook")
async def payment_webhook(request: Request):
    signature = request.headers.get("X-Signature")
    payload = await request.json()
    
    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=403, detail="Invalid signature")
    
    # Process payment
    if payload["status"] == "paid":
        order = await Order.get(payment_id=payload["payment_id"])
        order.status = "paid"
        await order.save()
    
    return {"status": "ok"}

{
  "payment_id": "pay_abc123",
  "reference": "ORDER-123",
  "amount": 25000,
  "status": "paid",
  "timestamp": "2024-12-20T10:30:00Z"
}

Users can save cards for future payments:

# Payment with card storage
POST /api/create-invoice
{
  "amount": 10000,
  "reference": "ORDER-456",
  "email": "[email protected]",
  "saveCard": true
}

Saved cards are hashed using bcrypt and never stored in plain text.

View all transactions for a user:

GET /api/transactions?[email protected]

Visit http://localhost:8000/test for built-in test interface with:

• Payment creation form
• Webhook URL testing
• Response inspection
• Status tracking

AcquireMock implements production-grade security practices:

• HMAC-SHA256 Signatures - All webhooks are cryptographically signed
• CSRF Protection - Token validation on all forms
• Bcrypt Hashing - Secure card data storage
• Security Headers - XSS protection, frame options, content-type sniffing prevention
• Rate Limiting - 5 requests per minute per IP
• Input Sanitization - All user input validated and sanitized
• Secure Cookies - HTTPOnly, Secure, SameSite attributes
• No Plaintext Storage - Card data always hashed

acquiremock/
├── main.py                          # FastAPI application entry point
├── database/
│   ├── models/                      # SQLModel schemas
│   │   ├── payment.py              # Payment entity
│   │   ├── saved_card.py           # Saved cards
│   │   └── webhook_log.py          # Webhook delivery logs
│   └── functional/                  # Database operations
│       ├── payment_crud.py         # Payment CRUD
│       ├── card_crud.py            # Card operations
│       └── webhook_crud.py         # Webhook logging
├── services/
│   ├── smtp_service.py             # Email delivery
│   ├── webhook_service.py          # Webhook HTTP calls
│   └── background_tasks.py         # Async job processing
├── security/
│   ├── crypto.py                   # Hashing & HMAC
│   └── middleware.py               # Security headers
├── templates/                       # Jinja2 HTML templates
│   ├── checkout.html               # Payment page
│   ├── otp.html                    # OTP verification
│   └── test.html                   # Test interface
└── static/                          # CSS, JS, images

• payment_id (PK)
• amount
• reference
• status (pending/paid/failed/expired)
• email
• webhook_url
• created_at
• expires_at

• card_id (PK)
• email
• card_last4
• card_hash (bcrypt)
• created_at

• log_id (PK)
• payment_id (FK)
• url
• status_code
• response_body
• attempt_number
• created_at

• Basic payment flow with OTP verification
• Webhook delivery with HMAC signatures
• Card storage and transaction history
• Multi-language UI with dark mode

• Multi-PSP Emulation - Switch between Stripe, PayPal, Square response formats
• Custom Response Builder - Define success/failure scenarios
• Advanced Webhook Testing - Simulate delays, failures, retries with custom timing
• 3D Secure Flow - Mock authentication pages
• Refund & Chargeback Simulation - Test full payment lifecycle

• Visual Flow Builder - Drag-and-drop payment scenario designer
• Plugin System - Add custom payment methods (crypto, BNPL, etc.)
• API Playground - Interactive testing without writing code
• Multi-Currency Support - Test currency conversion scenarios
• Fraud Detection Simulator - Test suspicious transaction handling
• Dashboard UI - Visual transaction monitoring

When ready to use a real payment provider (Stripe, PayPal, etc.):

1. Replace Card Validation - Switch from mock validation to PSP API calls
2. Implement Tokenization - Use PSP tokens instead of card storage
3. Add 3D Secure - Implement authentication flow
4. Add Refund Endpoint - Handle refund requests
5. PCI DSS Compliance - Remove any card data handling
6. Update Webhooks - Adapt to PSP webhook format

AcquireMock's structure makes this transition straightforward - most business logic remains the same.

# Clone repository
git clone https://github.com/illusiOxd/acquiremock.git
cd acquiremock

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest tests/ -v

# Format code
black .
isort .

# Type checking
mypy .

# All tests
pytest tests/ -v

# Specific test file
pytest tests/test_webhooks.py -v

# Coverage report
pytest --cov=. --cov-report=html

docker-compose up

version: '3.8'
services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://user:password@db:5432/payment_db
      - WEBHOOK_SECRET=${WEBHOOK_SECRET}
      - BASE_URL=https://your-domain.com
    depends_on:
      - db
  
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=payment_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

• Python: 3.11+
• Database: PostgreSQL 12+ (recommended) or SQLite
• Docker: Optional but recommended

• Development Testing - Test payment flows without real payment providers
• Integration Testing - Automated tests for payment workflows
• Learning - Understand payment gateway integration patterns
• MVP Development - Build prototypes without payment provider setup
• Educational Projects - Demonstrate payment processing concepts
• QA Environment - Isolated payment testing

Contributions welcome! Please read CONTRIBUTING.md first.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Apache License 2.0

This project is free and open-source software. See LICENSE for details.

Key points:

• Free to use, modify, and distribute
• Must preserve copyright notices
• Provides patent grant
• No trademark rights granted

This is a MOCK payment gateway for testing purposes only.

• Do NOT use in production with real payment data
• Do NOT store real credit card information
• Do NOT use for actual financial transactions
• Do NOT use for PCI DSS compliance testing

For production use, integrate with certified payment providers like Stripe, PayPal, Square, or your regional payment service provider.

• GitHub: https://github.com/illusiOxd/acquiremock
• Issues: https://github.com/illusiOxd/acquiremock/issues
• Discussions: https://github.com/illusiOxd/acquiremock/discussions
• Documentation: Wiki

Safe payment testing for serious development.

Built with FastAPI, SQLModel, and Jinja2 for developers who need reliable payment mocking.