Developer Docs

Everything you need to integrate Finswitz into your stack.

API Authentication

Use test keys for development and live keys for production.

Authorization: Bearer sk_test_xxx
Authorization: Bearer sk_live_xxx

Supported Currencies

Finswitz supports major African currencies and USD.

NGN, GHS, KES, UGX, ZAR, TZS, XOF, XAF, EGP, MAD, RWF, ETB, USD

Live Mode KYC

Live keys require KYC plus document uploads: full name, address, country, phone number, ID type/number, proof of address, incorporation doc, ID document, and a selfie.

After KYC approval, a settlement bank account is required before live mode usage.

Login OTP & 2FA

Logins may require an email OTP or authenticator code based on recent login history. 2FA can be enabled from the dashboard security section.

Settlement Accounts (Live)

Live payment links require a settlement account.

POST /developers/settlement
Authorization: Bearer <dashboard_jwt>

{
  "bankCode": "058",
  "accountNumber": "01234567890",
  "accountName": "Finswitz Labs",
  "currency": "NGN"
}

Payment APIs

Finswitz automatically routes and fails over between providers if one fails. Priority is configured with PROVIDER_PRIORITY on the backend.

Fraud & Risk Controls

Transfers and payment links are screened for duplicates, velocity bursts, and risk scores. Blocked calls return 403 with fraud details.

Response (blocked)
{
  "error": "Transfer blocked by fraud checks.",
  "details": {
    "allowed": false,
    "action": "block",
    "riskScore": 80,
    "reasons": ["duplicate_detected", "velocity_high_1m"]
  }
}

Bank Transfer

POST /payments/transfer
Authorization: Bearer sk_live_xxx
Idempotency-Key: unique-key

{
  "amount": 5000,
  "currency": "NGN",
  "bank_code": "058",
  "account_number": "0123456789"
}

Mock Card Charge (Test Only)

POST /payments/mock/charge
Authorization: Bearer sk_test_xxx

{
  "reference": "uuid",
  "card": {
    "number": "4242424242424242",
    "exp_month": "12",
    "exp_year": "30",
    "cvv": "123"
  }
}
Test card outcomes:
  • 4242424242424242 → success
  • 4000000000000002 → declined
  • 4000000000009995 → insufficient funds

Verify Account

POST /payments/verify-account
Authorization: Bearer sk_live_xxx

{
  "bank_code": "058",
  "account_number": "0123456789"
}

Payment Links

POST /payments/payment-links
Authorization: Bearer sk_live_xxx

{
  "amount": 5000,
  "currency": "NGN",
  "title": "Order #1234",
  "email": "buyer@shop.com",
  "callback_url": "https://merchant.com/checkout/complete"
}

Live mode requires an active settlement account. In test mode, checkoutUrl points to https://checkout.finswitz.com/test/<reference>?token=... for simulation.

1. Create a payment link and redirect the customer to `checkoutUrl`.
2. Handle the `callback_url` after payment.
3. Verify status with webhook events or GET /payments/{reference}.

Webhook Playground (Sandbox)

POST /developers/webhooks/simulate
Authorization: Bearer <dashboard token>

{
  "event": "payment.success",
  "reference": "uuid",
  "data": {
    "customerEmail": "buyer@shop.com"
  }
}

Use this endpoint to trigger test webhook events against your test webhook URL.

Mobile Money (Test)

POST /payments/mobile-money
Authorization: Bearer sk_test_xxx

{
  "amount": 1500,
  "currency": "GHS",
  "phone": "+233501112222",
  "country": "GH"
}

Live mode supports MTN MoMo, M-Pesa, Airtel Money, Vodafone Cash, and aggregator-backed routing where configured.

Pan-African Mobile Money Routing

Finswitz resolves the best path for mobile money based on country, network, provider health, latency, and recent failures. That helps developers support East and West African collection flows without manually wiring every telco rail.

M-Pesa (Live)

POST /payments/mobile-money
Authorization: Bearer sk_live_xxx

{
  "amount": 1200,
  "currency": "KES",
  "phone": "+254700123456",
  "provider": "mpesa",
  "country": "KE"
}

Vodafone Cash (Live)

POST /payments/mobile-money
Authorization: Bearer sk_live_xxx

{
  "amount": 900,
  "currency": "GHS",
  "phone": "+233201234567",
  "provider": "vodafone_cash",
  "country": "GH"
}

Wallets + FX

GET /developers/wallets
Authorization: Bearer <dashboard token>
POST /developers/wallets/fund
Authorization: Bearer <dashboard token>

{
  "amount": 150000,
  "currency": "NGN"
}
POST /developers/wallets/convert
Authorization: Bearer <dashboard token>

{
  "from": "USD",
  "to": "NGN",
  "amount": 10
}

Card Issuance

Issue Lite, prepaid debit, prepaid credit, and contactless virtual cards through Finswitz. Cards are funded from the developer USD wallet, and Finswitz adds its own platform fee on top of the vendor fee for each issued card.

GET /cards/pricing
Authorization: Bearer sk_live_xxx
POST /cards/issue
Authorization: Bearer sk_live_xxx
Idempotency-Key: card-issue-001

{
  "issueType": "LITE",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100,
  "cardType": "MASTERCARD",
  "swipeCount": 3,
  "expirationDate": "03/2027",
  "terminationDate": "03/2027"
}
GET /cards
GET /cards/{id}/transactions

Live card issuance requires account activation, approved KYC, and enough USD wallet balance to cover the funded amount plus fees. Partner-issued cards are expected to be branded under the Finswitz program.

Webhooks

Configure separate webhook URLs for test and live environments.

{
  "event": "payment.success",
  "data": {
    "reference": "uuid",
    "provider": "paystack",
    "status": "SUCCESS",
    "amount": 5000,
    "currency": "NGN",
    "type": "PAYMENT_LINK",
    "metadata": {
      "orderId": "ORD-123",
      "customerEmail": "buyer@shop.com"
    }
  }
}

Finswitz Collections

Finswitz Collections is our no-code payment collection product for schools, churches, communities, associations, and event organizers. Merchants can create a hosted payment page in minutes, share the link, track payments from the dashboard, and download receipts without writing code.

Dashboard flow
1. Create a collection
2. Set fixed or custom amount
3. Add branding and optional payer fields
4. Publish the collection
5. Share the hosted link
6. Track payments and download receipts

Live collections:
- require settlement setup
- do not require KYC

Live API keys:
- require KYC approval
- require KYC documents
- require settlement
POST /public/collections/:slug/pay
{
  "fullName": "Grace Johnson",
  "email": "grace@example.com",
  "amount": 10000,
  "phone": "+2348012345678",
  "memberId": "CHOIR-204"
}

Response
{
  "reference": "uuid",
  "checkoutUrl": "https://...",
  "amount": 10100,
  "currency": "NGN",
  "pricing": {
    "baseAmount": 10000,
    "payerFlatFeeMajor": 100,
    "settlementNetAmount": 9700
  }
}

Compliance as a Service (KYB)

Finswitz offers KYB verification and document review as part of merchant onboarding. This can be consumed as a managed service and billed per verification.

Examples

JavaScript

fetch("https://api.finswitz.com/payments/transfer", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer sk_live_xxx"
  },
  body: JSON.stringify({ amount: 5000, currency: "NGN", bank_code: "058", account_number: "0123456789" })
});

Node.js

import axios from "axios";

const client = axios.create({
  baseURL: "https://api.finswitz.com",
  headers: { Authorization: "Bearer sk_live_xxx" }
});

await client.post("/payments/transfer", {
  amount: 5000,
  currency: "NGN",
  bank_code: "058",
  account_number: "0123456789"
});

Python

import requests

res = requests.post(
  "https://api.finswitz.com/payments/transfer",
  headers={"Authorization": "Bearer sk_live_xxx"},
  json={"amount": 5000, "currency": "NGN", "bank_code": "058", "account_number": "0123456789"}
)
print(res.json())

Postman Collection

Import docs/Finswitz.postman_collection.json from the repo to test settlement, payment links, and transfers quickly.