Skip to main content
This section is for developers who clone the Payoes repository and want to run the stack locally. It is separate from merchant guides (Quickstart, API usage, checkout).

​
What you will run locally

ComponentPurposeHow it starts
Web app (apps/web)Dashboard, checkout, REST APInpm run dev
PostgreSQLOrganizations, payments, verification datadocker compose up -d
MinIOOrganization logosdocker compose up -d
DocsMintlify preview on port 3001npm run docs:dev
After setup, open:

​
Prerequisites

Install these before you start:
  • Node.js 20+ and npm
  • Git
  • Docker Desktop (or Docker Engine + Compose) for PostgreSQL and MinIO
  • Google OAuth credentials — sign in with Google
  • SMTP settings — send team invitation and verification emails
  • Persona API keys — identity verification for production mode (KYC setup)

​
Repository layout

payoes/
├── apps/web/          # Next.js app (dashboard + API)
├── apps/docs/         # Mintlify documentation (this site)
├── packages/sdk/      # TypeScript SDK (placeholder)
├── docker-compose.yml # PostgreSQL + MinIO
1

Getting started

Follow Getting started to install dependencies, start Docker, configure .env.local, run migrations, and sign in.
2

Soroban escrow

Deploy the contract before creating payments. See Soroban escrow setup.
3

Environment variables

Use Environment variables as a reference when you enable OAuth, SMTP, or Persona KYC.
4

KYC verification

Needed to test production mode — see KYC verification.
5

Webhook retry worker

For self-hosted production with low traffic — see Webhook retry worker.
Sandbox payments and checkout require a deployed Soroban escrow contract. Persona is only needed for production mode.