API Reference

The main endpoints, grouped by module. For every endpoint with its full request and response schemas, see the generated OpenAPI spec at https://api.finveil.money/v3/api-docs, or browse it in the live API reference.

Base URL & authentication

Base URL

https://api.finveil.money

There is no separate sandbox host. Test mode runs on the production API, and the key or account mode decides whether a request is TEST or LIVE.

Authentication

Server-to-server calls use an API key, sent as X-API-Key: fvk_test_… or Authorization: Bearer fvk_test_…. Keys are fvk_test_… or fvk_live_…. Mint them in the dashboard or with POST /api/api-keys. Admin actions, such as minting keys or activating Connect accounts, need a signed-in ADMIN session (JWT).

The free Sandbox plan covers payment links, Connect splits, payment status and API keys. Paid-plan routes, including /v1/**, return 403 FV-1003 on the Sandbox plan.

Authentication & API keys

Register, sign in for a JWT session (1-hour access token, 7-day refresh token), and mint API keys. Only an ADMIN session can mint, rotate or revoke keys.

POST/api/auth/registerCreate an account and its ADMIN user. The account starts in TEST mode.

POST/api/auth/loginExchange email and password for an access and refresh token pair.

POST/api/auth/refreshExchange a refresh token for a new token pair.

POST/api/api-keysMint an API key (fvk_test_… or fvk_live_…). The raw key is shown once.

POST/api/api-keys/{id}/rotateRotate an API key.

POST/api/api-keys/{id}/revokeRevoke an API key.

GET/api/account/statusActivation status, mode (TEST or LIVE) and the next step to go live.

Payment links

A payment link returns a Paystack hosted-checkout URL. Available on the free Sandbox plan. FinVeil does not yet send webhooks for link payments, so poll the payment status.

POST/api/payment-linksCreate a link (amountCents, currency, provider PAYSTACK, optional splitCode).

GET/api/payment-linksList your payment links.

GET/api/payment-links/{id}Retrieve a link. Public, no credential, so a payment page can render it.

DELETE/api/payment-links/{id}Cancel a link (ADMIN session).

Connect: split payments

Connected accounts become Paystack subaccounts, and a split becomes a Paystack split code. Paystack settles each party’s share to its subaccount. Activating accounts and splits needs an ADMIN session.

POST/api/connect/accountsCreate a connected account (name, bank code, account number).

POST/api/connect/accounts/{id}/activateCreate the Paystack subaccount (ADMIN session).

POST/api/connect/splitsDefine a percentage split across connected accounts.

POST/api/connect/splits/{id}/activateCreate the Paystack split and return its SPL_ code (ADMIN session).

GET/api/connect/splits/{id}Retrieve a split.

Payment status & history

Available on the free Sandbox plan. Another business’s id or reference returns 404.

GET/api/payments/historyPaginated transaction history, most recent first.

GET/api/payments/{transactionId}Retrieve a single transaction you own.

GET/api/payments/by-reference/{reference}/statusPoll a payment’s status by provider reference. Also checks with Paystack.

Direct collections & refunds (paid plan)

Collect against a provider you name. Paystack is verified end to end in test mode. Yoco and PayFast run against sandbox credentials. Ozow is not connected.

POST/api/payments/collectStart a collection (provider, paymentMethod, amount, email).

POST/api/payments/refundFull or partial refund of a SUCCEEDED transaction.

Orchestration API /v1 (paid plan)

The routing engine scores eligible providers and rails, picks one, and records the decision and its fallback order. Failover along that order runs in test mode only.

POST/v1/paymentsCreate a payment.

POST/v1/payoutsCreate a payout. No payout rail is connected for live money yet.

POST/v1/refundsCreate a refund.

GET/v1/transactions/{id}Retrieve a transaction.

POST/v1/recipientsCreate a payout recipient.

Webhook endpoints (paid plan)

POST/v1/webhook_endpointsRegister a URL and the event types it subscribes to.

GET/v1/webhook_endpointsList your webhook endpoints.

DELETE/v1/webhook_endpoints/{id}Disable an endpoint.

POST/v1/webhook_endpoints/deliveries/{id}/replayQueue a delivery to be sent again.

Proof receipts

Settled transactions get a SHA-256 proof receipt. Receipts are batched hourly into a Merkle root that FinVeil stores in its own database. Verification goes through FinVeil’s API. Public-ledger anchoring is not live.

GET/api/tokens/{tokenId}/verifyVerify a receipt and see its anchoring status. Public.

GET/api/verify/receipt/{receiptId}Verify a disbursement receipt. Public.

Rates & tax

SARB rates are a daily snapshot with source and observation date. They are not real-time.

GET/api/rates/sarb/latestLatest SARB rates snapshot. Public.

GET/api/rates/cpi/headlineLatest headline CPI. Public.

GET/api/rates/fxLatest SARB exchange rates. Public.

GET/api/tax/public/compareYear-on-year SA income tax comparison for an annual income. Public.

POST/api/tax/estimateCreate a tax estimate (paid plan).

Errors

Errors come back as JSON with a single error object containing:

code: a stable FinVeil error code, such as FV-1003.
message: a human-readable summary.
traceId: quote it when you contact support.
timestamp: when the error was produced, in ISO-8601.
retryable: whether retrying makes sense.
retryAfterSeconds: a suggested wait when the error is retryable, otherwise null.
details: extra context for this error.

A 429 means you hit a rate limit: wait for the Retry-After seconds. Send an Idempotency-Key header on any POST you might retry. Reusing a key with a different body returns 409.

FV-3003.httphttp

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code":      "FV-3003",
    "message":   "Invalid amount",
    "traceId":   "trace_42cb62e80e94440b",
    "timestamp": "2026-09-14T09:12:44.091Z",
    "retryable": false,
    "retryAfterSeconds": null,
    "details":   {}
  }
}