API Docs

REST + JWT auth. Idempotency keys on writes. HMAC-signed webhooks. Built for production from day one.

Base URL

https://paya.fund/api/v1

Authentication

All endpoints except registration, login, and the public payment-link / shared-invoice viewers require a Bearer token.

$ curl https://paya.fund/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email": "you@example.com", "password": "…"}'

→ {"token": "eyJ0eXAi…", "refresh_token": "…"}

Use the token in subsequent requests: Authorization: Bearer <token>.

Endpoint groups

• Auth. /auth/{register, login, refresh, me, logout, change-password}
• Profile + wallets. /profile, /wallets, /wallets/{id}/{balance,default,label}
• Payments. /payments, /payments/{id}/cancel, /payments/received
• Payment links. /payment-links (auth) + /pay/{slug} (public HTML checkout)
• Invoices. /invoices, /invoices/{id}/{lines, send, share, cancel} + /i/{token} (public)
• Payroll. Bulk CSV upload, screening, then payouts.
• Cashout. USDC → fiat via partnered providers.
• Webhooks. /webhooks CRUD + {id}/test. HMAC-SHA256 signed; events: payment.completed, payment.received, payment.failed, invoice.paid, payroll.completed, deposit.received.
• Billing. Stripe checkout + portal + webhook.
• KYC. Persona inquiries, status, limits.
• Export. CSV transactions + ledger.

Idempotency

Pass Idempotency-Key: <your-uuid> on POST /payments to safely retry on network failure.

Webhook signing

X-Paya-Event: payment.completed
X-Paya-Signature: 7c4a8d09ca3762af61e59520943dc26494f8941b
Content-Type: application/json

{"id": "…", "amount": 120.50, "status": "completed"}

Verify: hmac_sha256(secret, body) == X-Paya-Signature. Constant-time compare.

Rate limits

• Auth: 10 requests/minute per IP.
• Standard endpoints: 120/minute per IP.
• Per-user payment creation: 30/minute (in addition to per-IP).

Errors

JSON: {"error": {"code": "fraud_blocked", "message": "…"}}. Status codes follow REST conventions; 5xx never leak server detail.

Need help? dev@paya.fund.