For developers and integration partners
Built in the open
How Peaceful Hire works under the hood
The platform exposes database functions under row level security, plus a small set of server routes for payments, notifications and maps. The full specification is published in OpenAPI format.
Design principles
Rules live in the database
Every state change is a database function that checks who is calling, their role and permissions, and (for staff) a two-step verified session. Row level security applies to every table.
One backend for every app
The website, the admin portal and the mobile app call the same functions, so a worker or employer sees the same truth everywhere.
Trusted payment events only
Bookings are confirmed only by verified provider events. Duplicate events are ignored and amount mismatches are flagged.
No secrets in the apps
Provider keys live on the server. Apps use the public key plus the signed-in user's session.
Server routes
Web clients authenticate with their session cookie. The mobile app sends Authorization: Bearer <access token>.
| Method | Path | Authentication | Purpose |
|---|---|---|---|
| GET | /api/v1/health | None | Liveness and database reachability. |
| POST | /api/v1/payments/checkout | Session or bearer | Start a hosted checkout for a booking or a payable fee. The amount comes from the database. |
| POST | /api/v1/payments/webhooks/{provider} | Provider signature | Verified, idempotent payment, refund, chargeback and payout events. |
| POST | /api/v1/payments/sandbox/complete | Session or bearer | Simulate a sandbox payment outcome (no real money). |
| GET | /api/v1/payouts/banks | None | South African banks for payout accounts. |
| POST | /api/v1/payouts/account | Session or bearer | Save a payout account. The account number goes only to the payment provider. |
| POST | /api/v1/admin/refunds/{id}/process | Finance staff with MFA | Send an approved refund to the provider. |
| POST | /api/v1/admin/payouts/{id}/process | Finance staff with MFA | Submit an initiated payout to the provider. |
| GET | /api/v1/geocode?q= | Session or bearer | Address search for meeting points (OpenStreetMap). |
| POST | /api/v1/internal/dispatch | Internal secret | Deliver queued email, SMS and push notifications. |
The database functions (registration, verification, bookings, attendance, payments, reviews, messaging and administration) are documented in the repository under docs/CONVENTIONS.md and docs/DATABASE.md.