Payment Processor

Quickstart

Get the payment processor running locally and create your first charge.

Prerequisites

  • Node.js ≥ 20.19
  • pnpm ≥ 10
  • Docker (for Postgres and Redis)

Setup

Clone and install

git clone <repo-url> payment-processor
cd payment-processor
pnpm install

Start infrastructure

docker compose up -d

This starts Postgres (port 5432) and Redis (port 6379).

Configure environment

Copy the example env file and fill in the required values:

cp .env.example .env

Minimum required variables:

DATABASE_URL=postgresql://postgres:password@localhost:5432/payment_processor
REDIS_URL=redis://localhost:6379
 
# BIP-44 mnemonic for HD wallet derivation (24 words)
ESCROW_MNEMONIC="word1 word2 ... word24"
 
# API key for merchant authentication
API_SECRET_KEY=your-secret-key

Run database migrations

pnpm db:migrate

Start all services

pnpm start:local

This starts:

ServicePortDescription
API4000REST API for merchants
Dashboard4002Admin dashboard + checkout UI
Worker—Blockchain listener

Create your first charge

curl -X POST http://localhost:4000/v1/charges \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10.00, "customerEmail": "buyer@example.com" }'

Response:

{
  "id": "cm1abc...",
  "status": "PENDING",
  "expectedAmountUsd": "10.00",
  "wallets": [
    {
      "chain": "eth-sepolia",
      "chainId": 11155111,
      "address": "0xABC...",
      "tokens": [
        { "symbol": "USDC", "address": "0x...", "decimals": 6 },
        { "symbol": "ETH",  "decimals": 18 }
      ]
    }
  ],
  "checkoutUrl": "http://localhost:4002/checkout/cm1abc..."
}

Open the checkout UI

Navigate to checkoutUrl in a browser. The customer can:

  1. Select a chain and token from the dropdowns.
  2. See the exact token amount and live exchange rate.
  3. Scan the QR code or copy the wallet address to send payment.

The UI polls for confirmation and redirects automatically when the payment is detected.

Next steps

Chains & Tokens

Add EVM chains and configure accepted tokens.

Webhooks

Receive callbacks when payments are confirmed.

API Reference

Full reference for all REST endpoints.

Previous

Overview

Next

API Reference

On this page