API Reference

One REST API for payment collections, disbursements, splits, cryptographic receipts, reconciliation, conditional payouts, payment links, tax, rates, and webhooks.

Base URL & authentication

Base URL

https://api.finveil.money

Authentication

Every request must include an Authorization: Bearer <API_KEY> header (public endpoints such as /verify/:receiptId are the only exception).

API keys come in two flavours: sk_test_… keys hit the sandbox, sk_live_… keys hit production. Provision them from the dashboard or via POST /api/auth/api-keys.

Authentication

POST/api/auth/registerRegister a new merchant account + admin user.

POST/api/auth/loginExchange email/password for a JWT access + refresh pair.

POST/api/auth/refreshRotate an access token using the refresh token.

POST/api/auth/api-keysProvision a new API key (sk_test_… or sk_live_…).

Payments — Collections

Collect money from customers via card, EFT, instant EFT, or QR. One API over Paystack, Ozow, PayFast, Yoco.

POST/api/payments/collectInitiate a collection (card, instant EFT, QR).

GET/api/payments/:idRetrieve a single payment.

GET/api/paymentsList payments (paginated, filterable).

POST/api/payments/:id/refundRefund a successful payment.

Payments — Disbursements

Send money out — single payouts, batched CSV payouts, and cancellations before settlement.

POST/api/disbursementsInitiate a single disbursement to a bank account.

POST/api/disbursements/batchesSubmit a CSV of payouts for batch processing.

GET/api/disbursements/:idRetrieve disbursement status + settlement detail.

POST/api/disbursements/:id/cancelCancel a queued disbursement before it settles.

FinVeil Connect — Splits

Onboard sub-accounts and split a single collection across multiple beneficiaries atomically.

POST/api/connect/accountsCreate a connected sub-account (marketplace seller, agent, partner).

POST/api/connect/splitsDefine a split: percentages or fixed amounts per recipient.

GET/api/connect/splits/:idRetrieve a split configuration + execution history.

Transaction Proof

Cryptographic receipts anchored to the Stellar public ledger. Anyone can verify without a FinVeil account.

GET/api/receipts/:idFetch a receipt (authenticated — includes full metadata).

GET/verify/:receiptIdPublic verification page for a receipt. No auth required.

GET/api/receipts/:id/merkle-proofMerkle inclusion proof for ledger verification.

Reconciliation

Match settlements across Paystack, Ozow, PayFast, and your bank. Surface discrepancies automatically.

GET/api/reconciliation/runsList reconciliation runs.

POST/api/reconciliation/runsTrigger a reconciliation run for a date window.

GET/api/reconciliation/runs/:id/discrepanciesList discrepancies detected in a run.

POST/api/reconciliation/exportsExport a reconciled CSV for your finance team.

Conditional Payouts

Hold funds in escrow. Release when a condition (delivery, milestone, manual sign-off) is met.

POST/api/conditional-payoutsCreate a payout held pending a condition.

POST/api/conditional-payouts/:id/releaseRelease a held payout (condition met).

POST/api/conditional-payouts/:id/cancelCancel a held payout (refund to sender).

GET/api/conditional-payouts/:idRetrieve payout status + condition state.

Payment Links

Shareable URLs that accept payment without you writing any frontend code.

POST/api/payment-linksCreate a payment link (one-off or reusable).

GET/api/payment-links/:idRetrieve a payment link.

GET/api/payment-links/:id/paymentsList payments collected via this link.

DELETE/api/payment-links/:idDeactivate a payment link.

Tax

SARS-aligned tax estimation, bracket lookups, and year-over-year comparisons.

POST/api/tax/estimateEstimate PAYE for a given income + deductions.

GET/api/tax/bracketsCurrent-year SARS tax brackets.

POST/api/tax/year-comparisonCompare liabilities across tax years.

Rates

Live SARB benchmark rates (repo, prime, CPI) and real-time FX quotes.

GET/api/rates/repoCurrent SARB repo rate.

GET/api/rates/primeCurrent prime lending rate.

GET/api/rates/cpiMost recent CPI print.

GET/api/fx/quoteReal-time FX quote (ZAR pairs).

Webhooks

Subscribe to events. Every delivery is signed, retried, and fully replayable.

POST/api/webhooks/endpointsRegister a webhook endpoint + subscribed events.

GET/api/webhooks/deliveriesList recent webhook deliveries + status.

POST/api/webhooks/deliveries/:id/replayReplay a previously-sent webhook delivery.

Errors

FinVeil returns errors as RFC 7807 application/problem+json envelopes. Every envelope carries:

code — stable FinVeil error code (e.g. FV-3002).
message — human-readable summary.
traceId — correlate with our logs when you file support.
timestamp — ISO-8601 when the error was produced.
retryable — boolean; whether retrying makes sense.
retryAfterSeconds — hint for exponential backoff (null when not applicable).
details — error-specific context (provider code, entity id, etc.).

FV-3002.httphttp

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json

{
  "code":               "FV-3002",
  "message":            "Payment declined by issuing bank.",
  "traceId":            "trc_a8e2c1f0d9b4",
  "timestamp":          "2026-04-18T09:12:44.091Z",
  "retryable":          false,
  "retryAfterSeconds":  null,
  "details": {
    "provider":        "paystack",
    "providerReason":  "insufficient_funds",
    "paymentId":       "pay_01HRWXC2YQ..."
  }
}