Transfers

Create and track business fiat transfers.

Base URL: /v1/fiat/transfers
Auth: Authorization: Bearer <secret_key>

When to use transfers

Use a fiat transfer for a direct NGN payment to one bank account. For a batch or scheduler-backed disbursement workflow, use Payouts instead.

Recommended flow

Fetch the current bank list.
Perform name enquiry and show the resolved account name for confirmation.
Submit the transfer with a source account owned by the authenticated business.
Store the transfer UID, reference, and initial status.
Reconcile non-final transfers through status updates and webhooks.

The transfer amount and fee are checked against the business wallet balance. A successful API submission may still be processing, so do not show a final receipt until the transfer status is successful.

Create transfer

POST /v1/fiat/transfers

Body:

{
  "amount": 5000,
  "source_bank_account_id": "bank_001",
  "currency": "NGN",
  "beneficiary": {
    "bank_code": "090286",
    "account_number": "0110000000"
  },
  "narration": "Payout"
}

Response:

{
  "data": {
    "id": 1,
    "uid": "TS1234567890",
    "reference": "TS1234567890",
    "status": "success",
    "amount": 5000,
    "fee": 55,
    "debit_account_id": "bank_001",
    "debit_account_number": "0110000000",
    "beneficiary": {
      "bank_code": "090286",
      "account_number": "0111111111",
      "account_name": "Jane Doe"
    },
    "balance_before": 10000,
    "balance_after": 4945,
    "channel": "web",
    "created_at": "...",
    "updated_at": "..."
  }
}

List provider transfers

GET /v1/fiat/transfers

Query (optional):

page
limit
fromDate
toDate
type
status

Response:

{
  "data": [
    {
      "reference": "TS1234567890",
      "status": "success",
      "amount": 5000,
      "currency": "NGN",
      "narration": "Payout",
      "session_id": "session_001",
      "debit_account_number": "0110000000",
      "beneficiary": {
        "bank_code": "090286",
        "account_number": "0111111111",
        "account_name": "Jane Doe"
      },
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

List banks

GET /v1/fiat/transfers/banks

Response:

{
  "data": [
    {
      "bank_code": "090286",
      "bank_name": "Example Microfinance Bank"
    }
  ]
}

Name enquiry

POST /v1/fiat/transfers/name-enquiry

Body:

{
  "account_number": "0110000000",
  "bank_code": "090286"
}

Status

POST /v1/fiat/transfers/status

Body:

{
  "uid": "TS1234567890"
}

Returns the same normalized transfer shape as list items.