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

Payment APIs

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

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

POST /payments/verify-account
Authorization: Bearer sk_live_xxx

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

POST /payment-links
Authorization: Bearer sk_live_xxx

{
  "amount": 5000,
  "currency": "NGN",
  "title": "Subscription"
}

Webhooks

Configure separate webhook URLs for test and live environments.

{
  "event": "payment.success",
  "data": {
    "reference": "uuid",
    "amount": 5000,
    "currency": "NGN"
  }
}

Examples

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" })
});

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"
});

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())