Test mode

FinVeil works like Paystack: one account per business, in TEST mode by default. There is no separate sandbox website. Test mode runs on the production API, https://api.finveil.money, and TEST payments go through Paystack's test environment. No card is charged and no bank account is paid.

What the free Sandbox plan covers: API keys, payment links, Connect split payments and payment status. Paid-plan routes, including direct collections, disbursements and the /v1/** API, return 403 FV-1003. Paystack is the provider verified end to end in test mode.

1. Register and get a test key

api-key.shbash

# Mint a TEST key with your ADMIN access token (from /api/auth/register or /api/auth/login)
curl -X POST https://api.finveil.money/api/api-keys \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Backend (test)", "environment": "TEST" }'

# → 201 { "prefix": "fvk_test_ab12cd3", "rawKey": "fvk_test_<SECRET>", ... }  (rawKey is shown once)

2. Create a test payment link

Amounts are in cents. Send the buyer to paymentUrl, where Paystack shows its Test badge.

payment-link.shbash

curl -X POST https://api.finveil.money/api/payment-links \
  -H "X-API-Key: fvk_test_<SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821" \
  -d '{
    "amountCents":    125000,
    "currency":       "ZAR",
    "description":    "Order 4821",
    "provider":       "PAYSTACK",
    "expiresInHours": 2
  }'

# → 201 { "id": "<LINK_ID>", "paymentUrl": "https://checkout.paystack.com/<ACCESS_CODE>", "status": "ACTIVE", ... }

3. Confirm the payment

FinVeil doesn't yet send webhooks for payment links, so poll the status instead. Each poll also checks with Paystack.

status.shbash

# Find the collection's reference in your history (match on checkoutUrl) ...
curl "https://api.finveil.money/api/payments/history?size=20" \
  -H "X-API-Key: fvk_test_<SECRET>"

# ... then poll every 15–30 seconds until SUCCEEDED or FAILED
curl https://api.finveil.money/api/payments/by-reference/<REFERENCE>/status \
  -H "X-API-Key: fvk_test_<SECRET>"

4. Paystack test card

VISA4084 0840 8408 4081CVV 408

Any future expiry. If Paystack asks for an outcome, choose Success.

For other test cards and failure scenarios, see Paystack's test payments documentation.

5. Public API explorer

Call a few public, read-only endpoints from your browser without signing in. Pick an endpoint, click Run and inspect the live response.

Returns backend status, build commit, and per-provider configuration and mode (UNKNOWN means configured but not called since the last restart).

curlbash

curl -X GET /api/health