Skip to main content

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>.

MethodPathAuthenticationPurpose
GET/api/v1/healthNoneLiveness and database reachability.
POST/api/v1/payments/checkoutSession or bearerStart a hosted checkout for a booking or a payable fee. The amount comes from the database.
POST/api/v1/payments/webhooks/{provider}Provider signatureVerified, idempotent payment, refund, chargeback and payout events.
POST/api/v1/payments/sandbox/completeSession or bearerSimulate a sandbox payment outcome (no real money).
GET/api/v1/payouts/banksNoneSouth African banks for payout accounts.
POST/api/v1/payouts/accountSession or bearerSave a payout account. The account number goes only to the payment provider.
POST/api/v1/admin/refunds/{id}/processFinance staff with MFASend an approved refund to the provider.
POST/api/v1/admin/payouts/{id}/processFinance staff with MFASubmit an initiated payout to the provider.
GET/api/v1/geocode?q=Session or bearerAddress search for meeting points (OpenStreetMap).
POST/api/v1/internal/dispatchInternal secretDeliver 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.