Frequently asked questions

The backend runs on Spring Boot 4 with Java 25, backed by PostgreSQL for primary storage and Redis for caching and rate limiting. The frontend is Next.js 15 with React 19 and TypeScript in strict mode, styled with Tailwind CSS. The entire platform is containerised with Docker and deployed via CI/CD on Railway (backend) and Vercel (frontend).

Enterprise-grade, type-safe, and battle-tested in financial services. Spring Boot gives us mature transaction management, proven security primitives (Spring Security + JWT), and a rich ecosystem of production-hardened libraries. Java's strong typing catches entire classes of bugs at compile time rather than in production, and the JVM has decades of optimisation behind it for high-throughput workloads.

Server-side rendering for SEO and fast first-paint, an API proxy layer that keeps backend URLs off the client, and the full React ecosystem for building complex dashboards. Next.js App Router gives us server components by default, reducing the JavaScript shipped to the browser while keeping the developer experience productive.

All personally identifiable information (PII) is encrypted at rest using AES-256-GCM via custom JPA AttributeConverters. Data in transit is protected by TLS 1.3. Authentication uses short-lived JWT access tokens paired with rotating refresh tokens. Database connections use SSL with certificate pinning.

All production data lives in PostgreSQL on Railway, hosted in the South African region. No data leaves South Africa. Backups are encrypted and stored in the same region. Row-level security ensures strict tenant isolation at the database layer.

Database schema changes are managed by Flyway migrations with version-controlled, checksummed SQL files that guarantee every environment runs the identical schema. Every payroll CSV upload is hashed with SHA-256 before processing — if the file is modified after upload, the checksums will not match and the system rejects the change. All mutations are audit-logged with timestamp, user, and IP address.

A cryptographic proof layer. Each payroll upload or payment transaction receives a Merkle-tree-anchored receipt. The receipt hash is bundled into a Merkle tree and can be independently verified without a FinVeil account at /verify/:receiptId. This gives auditors, regulators, and counterparties tamper-evident proof that the data has not been altered since it was recorded. More on Transaction Proof.

The v1 scoring engine uses a deterministic, rule-based algorithm with six weighted factors:

• Garnishee orders present: +30 points
• Loan deductions > 25% of gross: +20 points
• Net pay < 40% of gross: +15 points
• Multiple loan deductions: +10 points
• Salary band in lowest 3 bands: +10 points
• Declining net pay trend (3+ months): +15 points

Risk levels: LOW (0-25), MODERATE (26-50), HIGH (51-75), CRITICAL (76-100). Future versions will layer machine-learning models on top of these base rules.

FinVeil polls the SARB WebIndicators API daily at 06:00 SAST. Rates (repo rate, prime lending rate, CPI) are cached in Redis with a 24-hour TTL and served from cache for all subsequent requests until the next poll cycle. If the SARB endpoint is unavailable, the system falls back to the most recent cached values and raises an ops alert.

Tax brackets and rebates are sourced from the SARS 2027 Year of Assessment tables, updated annually following the Budget Speech (typically in February). The tax engine applies the correct bracket based on the employee's annualised income and age-based rebates. Updates are shipped as Flyway migrations to ensure consistency across all environments.

POPIA compliance is built into the architecture, not bolted on. Consent-first: no data is processed without explicit consent, tracked per employer and employee. Audit-logged: every API call touching personal data creates an immutable audit trail. Right to be forgotten: data subjects can request deletion, and the system cryptographically shreds the relevant encryption keys. Data minimisation: we only collect what is strictly necessary for stress scoring. Full details on the privacy page.

FinVeil never stores card data. All card processing is handled by our PCI-DSS-certified payment providers (Paystack, Yoco, PayFast, Ozow). Card numbers never touch our servers — they go directly from the client to the provider's tokenisation endpoint. This keeps us out of PCI scope entirely.

Paystack (cards, bank transfers), Yoco (cards, QR), PayFast (instant EFT, cards), Ozow (instant EFT). All are FSCA-registered and PCI-DSS compliant. FinVeil routes across all of them from a single API, with automatic failover if one provider is degraded.

Each payment provider sends webhooks to FinVeil endpoints. Every incoming webhook is verified using HMAC signature verification specific to each provider (Paystack uses X-Paystack-Signature, Ozow uses a hash of the payload fields, etc.). Invalid signatures are rejected and logged. Outbound webhooks to your systems are also HMAC-signed so you can verify they came from FinVeil.

Rate limiting is enforced at three tiers:

• Auth endpoints: 10 requests/minute (login, register, password reset)
• Public endpoints: 60 requests/minute (marketing pages, health checks)
• Authenticated API: 200 requests/minute per API key

Enterprise customers can request higher limits. All rate-limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Nine first-party SDKs: Node/TypeScript, Python, Java, Go, Rust, PHP, C#, Kotlin, and Flutter/Dart. Each ships with typed clients for every API surface, built-in retries with exponential backoff, webhook signature verification helpers, and sandbox mode. Browse them in the SDK documentation.

REST + JSON with an OpenAPI 3.1 specification available at /v3/api-docs. Interactive documentation is served via Scalar. All responses follow a consistent envelope format with data, meta, and errors fields.

Register an account, then navigate to Settings → API Keys → Create. Test keys are prefixed sk_test_ and live keys are prefixed sk_live_. No sales call or approval process required — you can hit the sandbox immediately after registration.

Regardless of which payment provider originated the event, FinVeil normalises all webhooks into a canonical event shape. Every event includes event_type, timestamp, payload, and an HMAC signature. This means you write one webhook handler, not four. Webhook documentation.

Yes. The Sandbox tier is R0 — no credit card required. You get full API access in test mode, all SDKs, webhook testing, and the developer dashboard. It is free forever, not a time-limited trial.

FinVeil uses a per-employee/month SaaS model plus per-transaction fees for payment processing. Monthly tiers: Sandbox R0, Starter R3,500/mo, Growth R12,500/mo, Scale R35,000/mo, Enterprise R75,000+/mo (custom). Disbursements are priced per rail per transaction, and FinVeil Tokens are priced per mint. See the pricing page for the full schedule.

Yes, on the Enterprise tier. White-label includes custom branding (your logo, colours, email templates), your own domain for the dashboard, and removal of all FinVeil branding from employee-facing surfaces. Contact sales for details.