Skip to content

Quick Start

Prerequisites

  • Python 3.12+
  • uv
  • Docker + Docker Compose

1. Clone and install

git clone https://github.com/your-org/payments-service.git
cd payments-service
uv sync
cp .env.example .env

Generate required secrets:

# API key pepper
python -c "import secrets; print(secrets.token_hex(32))"

# Encryption key (for merchant credentials)
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Add both to your .env file.

2. Start infrastructure

docker compose up -d postgres redis

3. Run migrations

make migrate

4. Create the first admin

make createsuperadmin

Save the API key

The key is printed once. Store it securely.

5. Start the server

make run          # API server on :8080
make worker       # ARQ worker (separate terminal)

6. Verify

curl http://localhost:8080/docs    # Scalar API docs

End-to-end flow

sequenceDiagram
    participant Admin
    participant API
    participant DB

    Admin->>API: make createsuperadmin
    API->>DB: Create admin merchant + API key
    API-->>Admin: sk_test_... (save this!)

    Admin->>API: PUT /v1/merchant/providers<br/>(configure Stripe keys)
    API->>DB: Encrypt + store credentials

    Admin->>API: PUT /v1/merchant/webhook<br/>(register callback URL)
    API-->>Admin: webhook_secret (save this!)

    Admin->>API: POST /v1/payments<br/>(create a payment)
    API-->>Admin: { status: "pending" }