Sandbox & Testing

Test FinVeil end-to-end without a real account. Every sandbox endpoint is isolated from production, accepts any fv_sandbox_sk_* token, and returns deterministic mock data.

1. Register a sandbox account

curl -X POST https://sandbox.finveil.money/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Sandbox Corp",
    "email":       "sandbox@finveil.money",
    "password":    "sandbox-pass-1",
    "popiaConsent": true
  }'

Note: The examples on this page use sandbox.finveil.money, which is a future custom domain. Running locally or in staging? Replace sandbox.finveil.money with your backend URL (e.g., api.finveil.money for the live staging environment).

2. Make a sandbox collection

Charge a card in the sandbox. Use test card 4084 0840 8408 4081, CVC 408, and any future expiry. Set provider: "auto" to let FinVeil route to the cheapest healthy rail.

collect.shbash

curl -X POST https://sandbox.finveil.money/api/payments/collect \
  -H "Authorization: Bearer fv_sandbox_sk_demo" \
  -H "Content-Type: application/json" \
  -d '{
    "amount":   125000,
    "currency": "ZAR",
    "email":    "customer@example.com",
    "provider": "auto",
    "reference": "ORDER-4821"
  }'

# Any bearer token prefixed fv_sandbox_sk_ is accepted.
# Use test card 4084 0840 8408 4081 / CVC 408 / any future expiry.

3. Make a sandbox disbursement

Send funds to a South African bank account. In sandbox, settlement completes instantly and a disbursement.settled webhook fires a few seconds later.

disburse.shbash

curl -X POST https://sandbox.finveil.money/api/disbursements \
  -H "Authorization: Bearer fv_sandbox_sk_demo" \
  -H "Content-Type: application/json" \
  -d '{
    "amount":        200000,
    "currency":      "ZAR",
    "bankAccount": {
      "accountNumber": "1234567890",
      "branchCode":    "632005",
      "accountHolder": "Sandbox Payee"
    },
    "reference":     "PAYOUT-991"
  }'

4. Batch disbursements via CSV

Upload a CSV to pay a batch of recipients in one call. Each row becomes an independent disbursement — failures don't block successful rows.

batch.shbash

curl -X POST https://sandbox.finveil.money/api/disbursements/batches \
  -H "Authorization: Bearer fv_sandbox_sk_demo" \
  -F "file=@sample-payouts.csv"

Save this as sample-payouts.csv:

sample-payouts.csvbash

reference,account_holder,account_number,branch_code,amount,currency
PAYOUT-001,Acme Supplier,1234567890,632005,150000,ZAR
PAYOUT-002,Jane Operator,9876543210,250655,85000,ZAR
PAYOUT-003,Studio Beta,5556667778,051001,210000,ZAR

5. API Explorer

Run real public API calls from your browser — no login required. Select an endpoint, hit Run, and inspect the live response.

Returns service health status and uptime info.

curlbash

curl -X GET /api/health

6. Sandbox test cards

VISA4084 0840 8408 4081CVC 408

Always succeeds (FinVeil sandbox)

MASTER5060 6666 6666 6666 667CVC 123

3DS challenge (sandbox)

VISA4084 0800 0000 0000CVC 000

Always declines (sandbox)