Developer Documentation

Security

Security

Stage 5 hardening adds:

• Request IDs returned as X-Request-ID.
• Secure headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy, restrictive Permissions-Policy, CSP, and production HSTS.
• Production-safe exception responses when APP_DEBUG=false.
• DB-backed rate limiting by IP, bearer token, API key, endpoint, and stricter auth/OTP/PIN policies.
• Admin IP allowlist support through ADMIN_IP_ALLOWLIST.
• Direct-access blocking for .env, config, database, storage, docs, deploy, tests, and hidden files through .htaccess.

Phone Verification

Customers and merchants register as pending_verification. Phone OTP verification activates customers and moves merchants to KYC.

OTP rules:

• raw OTP codes are never stored
• codes are stored using password_hash()
• default expiry is OTP_TTL
• resend frequency is limited
• attempts are counted
• consumed codes cannot be reused

Device Security

Every login captures:

• device_id
• device_name
• platform
• app_version
• IP address
• user agent

New devices trigger a device-trust OTP and risk alert. Financial actions require X-Device-ID.

Device endpoints:

• GET /devices
• POST /devices/trust
• DELETE /devices/{id}
• POST /auth/verify-device

Transaction PIN

Transaction PINs are hashed separately from passwords.

PIN is required for:

• payment confirmation
• withdrawal confirmation
• withdrawal approval where configured
• QR regeneration
• changing transaction PIN
• changing sensitive payout or wallet settings

Failed PIN attempts are counted and can temporarily lock financial actions.

Fraud Signals

Risk alerts may be created for:

• multiple accounts using the same device
• repeated failed OTP attempts
• repeated failed PIN attempts
• QR verification anomalies
• high transaction velocity
• same Ghana Card on multiple accounts
• same KYC document hash on multiple accounts