Developer Documentation

Authentication

Protected endpoints require:

Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json
X-Device-ID: {device-id}
X-App-Version: {app-version}

Access tokens are HMAC-signed JWTs with a short TTL configured by JWT_ACCESS_TTL. Refresh tokens are random opaque secrets, stored as SHA-256 hashes in refresh_tokens, and rotated on every refresh.

New customer and merchant accounts start as pending_verification. Use POST /auth/verify-phone with the OTP code before login and financial access.

Financial POST endpoints also require:

Idempotency-Key: {unique-client-generated-key}

The same user, endpoint, and idempotency key can only be processed once. If the same request body is repeated, the original response is returned. If the same key is reused with a different body, the API returns 409 IDEMPOTENCY_CONFLICT.

Roles:

customer: customer wallet, payment, withdrawal initiation, personal history.
merchant: merchant profile, QR, wallet, withdrawal approval, merchant history.
support: read-oriented operational/admin access.
compliance: audit, webhook, risk, and transaction oversight.
finance: transaction, settlement, and financial reporting access.
admin: operational administration.
super_admin: full platform administration and API key management.

Passwords and transaction PINs are hashed separately with password_hash(). Hashes are never returned.

Transaction PIN confirmation is required for:

POST /payments/confirm
POST /withdrawals/confirm
POST /merchants/me/qr/regenerate