Frequently asked questions

The backend runs on Spring Boot 4 with Java 25, backed by PostgreSQL for primary storage. The frontend is Next.js 15 with React 19 and TypeScript in strict mode, styled with Tailwind CSS. The backend, frontend and database are all deployed on Railway.

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.

Designated personal-information fields (user, employer, employee and payroll data) are encrypted at rest using AES-256-GCM via a custom JPA AttributeConverter. Not every column is encrypted yet: for example, sub-merchant bank account details on Connect accounts are stored unencrypted. Traffic is served over TLS. Authentication uses short-lived JWT access tokens (60 minutes) and 7-day refresh tokens.

Production data lives in PostgreSQL on Railway, in Railway's US West region (United States). Data is therefore stored outside South Africa; see section 6 of the privacy policy. Tenant isolation is enforced in the application layer (tenant-scoped queries are filtered by tenant, with automated cross-tenant tests); PostgreSQL row-level security is not enabled.

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, and re-uploading a file with identical bytes is rejected as a duplicate. Key actions are audit-logged with timestamp, user, and IP address.

A proof receipt. Each payroll upload or settled payment receives a SHA-256 proof receipt. Receipts are batched hourly into a Merkle root that FinVeil stores in its own database, and a receipt can be checked without a FinVeil account at /verify/:tokenId, which queries FinVeil's verification service. Anchoring to a public ledger is not live. 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 SARB sources on a daily schedule. Rates (repo rate, prime lending rate, CPI) are stored as a snapshot and served until the next poll; if a poll fails, the most recent stored values continue to be served. Rates are not real-time.

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. Tax tables are defined in code and updated through normal releases. The calculator has not been independently checked against SARS.

The platform was designed with POPIA in mind, and our compliance programme is under legal review. Consent: consent status and version are recorded per employee. Audit log: key actions are recorded (the log is not yet hash-chained or write-once). Data subject requests: access, correction and deletion requests are handled via privacy@finveil.money. Hosting: production data is stored in the United States (Railway, US West). Full details on the privacy page.

FinVeil is not PCI DSS certified and does not store card numbers. Card details are entered on the payment provider's hosted checkout (Paystack; Yoco and PayFast hosted pages), so card data is handled by PCI DSS-certified providers rather than by FinVeil's servers.

Paystack is verified end to end in test mode. Yoco and PayFast run against sandbox credentials. Ozow and Stitch (PayShap, RTC) adapters are built but not yet connected. FinVeil has not processed live customer volume yet. The routing engine scores eligible providers and rails, selects one, and records the decision and its fallback order; failover along that order runs in test mode only, and automatic live failover is on the roadmap.

Payment providers send webhooks to FinVeil endpoints. Paystack webhooks are verified with HMAC-SHA512 using the X-Paystack-Signature header, and invalid signatures are rejected. Outbound webhooks to your systems are signed with HMAC-SHA256 (hex) in the X-FinVeil-Signature header so you can verify they came from FinVeil.

Rate limiting is applied per client IP address, per minute:

• Auth endpoints: 10 requests/minute (login, register, MFA)
• Token refresh: 60 requests/minute
• Public endpoints: 60 requests/minute
• Authenticated API: 200 requests/minute

API responses include X-RateLimit-Limit and X-RateLimit-Remaining headers; a 429 response also includes Retry-After.

SDK source code exists for nine languages: Node/TypeScript, Python, Java, Go, Rust, PHP, C#, Kotlin, and Flutter/Dart. None is published to a package registry yet; SDKs are available on request. See the SDK documentation.

REST + JSON with an OpenAPI specification available at https://api.finveil.money/v3/api-docs. Errors use one consistent body: {"error":{"code","message","traceId","timestamp","retryable","details"}}.

Register an account, then navigate to Settings → API Keys → Create (an ADMIN session is required). Test keys are prefixed fvk_test_ and live keys are prefixed fvk_live_. New accounts start in test mode; live access requires FinVeil's approval.

Webhook endpoints registered on the /v1 API (a paid-plan feature) receive canonical events: payment.*, payout.* and refund.* (created, succeeded, failed). Payment-link and Connect payments do not emit webhooks yet. Webhook documentation.

Yes. The Sandbox tier is R0 — no credit card required. It runs in test mode with 1,000 API calls a month. Paid-plan features, such as the /v1 orchestration API, payroll upload and stress scoring, are not included.

FinVeil uses a metered API-call subscription 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.

Per-tenant branding (platform name, logo, colours, favicon and support email) is built. White-label and partner mode are offered as an add-on; see the pricing page or contact sales for details.