KYC verification (Persona)

Production mode requires identity verification through Persona. Persona automatically reviews government ID and selfie/liveness checks. Payoes does not manually review applications.

What you need

Item	Where to get it
Persona sandbox account	app.withpersona.com
API key	Dashboard → API → API Keys (`persona_sandbox_...`)
KYC inquiry template	Dashboard → Inquiries → Templates (`itmpl_...`)
Environment ID	Dashboard → Environments (`env_...`)
Webhook secret	Dashboard → Webhooks

Environment variables

Add to .env.local at the repository root:

PERSONA_API_KEY=persona_sandbox_...
PERSONA_WEBHOOK_SECRET=whsec_...
PERSONA_INQUIRY_TEMPLATE_ID=itmpl_...
NEXT_PUBLIC_PERSONA_ENVIRONMENT_ID=env_...
NEXT_PUBLIC_PERSONA_INQUIRY_TEMPLATE_ID=itmpl_...

Restart npm run dev after updating env vars.

Webhook setup (local)

Persona sends webhooks when verification status changes. For local development, expose your app with a tunnel:

cloudflared tunnel --url http://localhost:3000
# or
ngrok http 3000

Set the webhook URL in Persona to:

https://<your-tunnel-host>/api/webhooks/persona

Enable events: inquiry.completed, inquiry.approved, inquiry.declined, inquiry.failed.

If webhooks cannot reach your machine, use Refresh status on the Production page. Payoes also syncs status when the Persona flow completes.

Test the flow

Sign in to Payoes as organization owner
Open Settings → Production
Choose Personal or Business
Fill name, country, and business description (if business)
Click Verify identity with Persona
Complete the Persona sandbox flow (use Persona test documents)
After approval, configure a mainnet settlement wallet
Click Switch to production

Sandbox test documents

Persona sandbox accepts test ID images documented in the Persona dashboard. Real documents are only required in production.

Troubleshooting

Persona flow does not open

Confirm NEXT_PUBLIC_PERSONA_ENVIRONMENT_ID is set
Confirm PERSONA_API_KEY and PERSONA_INQUIRY_TEMPLATE_ID are set on the server
Restart the dev server

Status stays pending after completing Persona

Click Refresh status on the Production page
Check webhook delivery in the Persona dashboard
Ensure PERSONA_WEBHOOK_SECRET matches your webhook configuration

Switch to production is disabled

Verification status must be verified
Configure a production settlement wallet first

​What you need

​Environment variables

​Webhook setup (local)

​Test the flow

​Sandbox test documents

​Troubleshooting

What you need

Environment variables

Webhook setup (local)

Test the flow

Sandbox test documents

Troubleshooting