Overview - Payoes

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

Component	Purpose	How it starts
Web app (`apps/web`)	Dashboard, checkout, REST API	`npm run dev`
PostgreSQL	Organizations, payments, verification data	`docker compose up -d`
MinIO	Organization logos	`docker compose up -d`
Docs	Mintlify preview on port 3001	`npm run docs:dev`

After setup, open:

http://localhost:3000 — web app
http://localhost:3001 — docs (if you start them)
http://localhost:9001 — MinIO console (payoes / payoessecret)

Prerequisites

Install these before you start:

Required for the core app

Node.js 20+ and npm
Git
Docker Desktop (or Docker Engine + Compose) for PostgreSQL and MinIO

Additional features

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)

Stellar / Soroban (payments)

Stellar CLI (stellar) and Rust (cargo) for contract deploy
See Soroban escrow setup

Repository layout

payoes/
├── apps/web/          # Next.js app (dashboard + API)
├── apps/docs/         # Mintlify documentation (this site)
├── packages/sdk/      # @payoes/sdk checkout embed (iframe modal)
├── docker-compose.yml # PostgreSQL + MinIO

Dashboard Integrations connects Shopify or WooCommerce stores when you use them.

Recommended path

Getting started

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

Soroban escrow

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

Environment variables

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

KYC verification

Needed to test production mode — see KYC verification.

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.

​What you will run locally

​Prerequisites

​Repository layout

​Recommended path

What you will run locally

Prerequisites

Repository layout

Recommended path