Skip to main content
All configuration for the web app lives in apps/web/.env.local. Copy from apps/web/.env.example and adjust values for your machine.
Restart npm run dev after changing environment variables.

​
Auth

VariableRequiredDescription
AUTH_SECRETYesSession encryption secret. Generate with openssl rand -base64 32
AUTH_URLYesPublic app URL. Local: http://localhost:3000
AUTH_GOOGLE_IDFor Google sign-inGoogle OAuth client ID
AUTH_GOOGLE_SECRETFor Google sign-inGoogle OAuth client secret
Users can register with email and password, or sign in with Google when OAuth is configured.

​
Database

VariableRequiredDefault (local)
DATABASE_URLYespostgresql://payoes:payoes@localhost:5432/payoes
Must match the credentials in docker-compose.yml.

​
Object storage (MinIO)

VariableRequiredDefault (local)
S3_ENDPOINTYeshttp://localhost:9000
S3_PUBLIC_URLYeshttp://localhost:9000/payoes-uploads
S3_ACCESS_KEYYespayoes
S3_SECRET_KEYYespayoessecret
S3_BUCKETYespayoes-uploads
S3_REGIONYesus-east-1
Used for organization logo uploads.

​
Stellar

VariableRequiredDescription
STELLAR_TESTNET_USDC_ISSUERFor USDC sandboxTestnet USDC issuer public key
STELLAR_MAINNET_USDC_ISSUERFor USDC productionMainnet USDC issuer public key
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_IDNoEnables WalletConnect in Stellar Wallet Kit
XLM payments work without USDC issuer variables. Set the issuer for the network you test when accepting USDC.

​
Email (SMTP)

VariableRequiredDescription
SMTP_HOSTFor invitesSMTP server hostname
SMTP_PORTFor invitesUsually 587
SMTP_USERFor invitesSMTP username
SMTP_PASSWORDFor invitesSMTP password
SMTP_FROMFor invitesFrom header, e.g. Payoes <noreply@yourdomain.com>
Team invitation emails are sent only when SMTP is configured. Without SMTP, you can still test invites by copying the invite URL from the database or API response.

​
KYC (Persona)

VariableRequiredDescription
PERSONA_API_KEYFor production gateServer-side Persona API key (persona_sandbox_...)
PERSONA_WEBHOOK_SECRETFor webhooksWebhook signing secret from Persona dashboard
PERSONA_INQUIRY_TEMPLATE_IDFor production gateKYC inquiry template ID (itmpl_...)
NEXT_PUBLIC_PERSONA_ENVIRONMENT_IDFor production gatePersona environment ID (env_...)
NEXT_PUBLIC_PERSONA_INQUIRY_TEMPLATE_IDSDK onlyClient-side template ID for the Persona SDK
See KYC verification for Persona sandbox setup.

​
Background jobs

Self-hosted deployments only.
VariableWhen to setDescription
CRON_SECRETRunning cron workersBearer token for protected cron endpoints
See Webhook retry worker for scheduling setup.

​
Soroban escrow (required for payments)

Payments and checkout require a deployed and initialized Payoes Soroban contract.
VariableRequiredDescription
STELLAR_TESTNET_OPERATOR_SECRETYes (sandbox)Operator secret (S...). Printed by the deploy script
SOROBAN_TESTNET_RPC_URLYes (sandbox)Soroban RPC URL. Default: https://soroban-testnet.stellar.org
SOROBAN_TESTNET_CONTRACT_IDYes (sandbox)Contract ID (C...). Printed by the deploy script
STELLAR_MAINNET_OPERATOR_SECRETProduction onlyMainnet operator account
SOROBAN_MAINNET_RPC_URLProduction onlyMainnet Soroban RPC URL
SOROBAN_MAINNET_CONTRACT_IDProduction onlyMainnet Payoes contract ID
Deploy and initialize with one command: 
./scripts/soroban-deploy-contract.sh \
  --operator-account payoes-operator \
  --source-account payoes-operator
See Soroban escrow setup for the full walkthrough.

​
Docs

VariableRequiredDescription
NEXT_PUBLIC_DOCS_URLRecommendedURL opened by dashboard documentation links. Local: http://localhost:3001

​
Example: minimal local file

AUTH_SECRET=<openssl rand -base64 32>
AUTH_URL=http://localhost:3000
AUTH_GOOGLE_ID=your-client-id.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=your-client-secret

DATABASE_URL=postgresql://payoes:payoes@localhost:5432/payoes

S3_ENDPOINT=http://localhost:9000
S3_PUBLIC_URL=http://localhost:9000/payoes-uploads
S3_ACCESS_KEY=payoes
S3_SECRET_KEY=payoessecret
S3_BUCKET=payoes-uploads
S3_REGION=us-east-1

NEXT_PUBLIC_DOCS_URL=http://localhost:3001

​
Example: with Google OAuth

Set AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local. In Google Cloud Console, set the authorized redirect URI to: 
http://localhost:3000/api/auth/callback/google