API Reference›Transfers

Transfers

The Transfers API lets you send money to bank accounts across Africa. POPFAB automatically selects the best available provider for your configured environment, with account name verification built in before funds are sent.

Provider support

Transfers are supported by Paystack, Flutterwave, Monnify, Squad, and Interswitch. You must have at least one of these providers configured under Provider Keys before initiating a transfer. If no transfer-capable provider is configured, the API returns a 422 NO_TRANSFER_PROVIDER error.

Endpoints

GET/v1/transfers/banks— List supported banks for a currency

POST/v1/transfers/verify-account— Verify a bank account name before sending

POST/v1/transfers— Initiate a single transfer

POST/v1/transfers/bulk— Initiate multiple transfers in one call

GET/v1/transfers— List transfers (paginated)

GET/v1/transfers/:id— Retrieve a single transfer

List Banks

Returns all banks supported for transfers in a given currency. Use the returned code field as the bank_code in verify-account and transfer requests.

GET

/v1/transfers/banks

Returns the list of active banks for the specified currency.

Query parameters

Parameter	Type	Required	Description
`currency`	`string`	Optional	ISO 4217 currency code. Defaults to NGN.
`provider_id`	`string`	Optional	Force a specific provider for the lookup. Omit to use your first configured transfer-capable provider.

Example requestbash

curl "https://api.popfab.io/v1/transfers/banks?currency=NGN" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

200 OKjson

{
  "banks": [
    { "name": "Access Bank", "code": "044", "country": "Nigeria", "currency": "NGN" },
    { "name": "First Bank of Nigeria", "code": "011", "country": "Nigeria", "currency": "NGN" },
    { "name": "Guaranty Trust Bank", "code": "058", "country": "Nigeria", "currency": "NGN" },
    { "name": "United Bank for Africa", "code": "033", "country": "Nigeria", "currency": "NGN" },
    { "name": "Zenith Bank", "code": "057", "country": "Nigeria", "currency": "NGN" }
  ]
}

Verify Account Name

Resolve the account holder's name before sending funds. Always call this endpoint first — it lets your customer confirm they are sending to the right person.

POST

/v1/transfers/verify-account

Looks up the registered account name for a bank account number + bank code pair.

Request body

Parameter	Type	Required	Description
`account_number`	`string`	Required	10-digit NUBAN bank account number.
`bank_code`	`string`	Required	CBN bank code (e.g. "058" for GTBank, "011" for First Bank).
`provider_id`	`string`	Optional	Force a specific provider for the lookup. Omit to use the first configured transfer-capable provider.

Example requestbash

curl -X POST https://api.popfab.io/v1/transfers/verify-account \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "0123456789",
    "bank_code": "058"
  }'

200 OK — Account verifiedjson

{
  "account_number": "0123456789",
  "bank_code": "058",
  "account_name": "Ada Okafor",
  "bank_name": "Guaranty Trust Bank"
}

Initiate a Transfer

POST

/v1/transfers

Sends money to a bank account. POPFAB creates a transfer record, selects a provider, and initiates the disbursement.

Request headers

Parameter	Type	Required	Description
`Authorization`	`string`	Required	Bearer YOUR_API_KEY
`Content-Type`	`string`	Required	Must be application/json

Request body

Parameter	Type	Required	Description
`reference`	`string`	Required	Your unique reference for this transfer. Alphanumeric, hyphens, and underscores only. Max 255 characters.
`amount`	`integer`	Required	Amount in the smallest currency unit (kobo for NGN). Must be a positive integer.
`currency`	`string`	Required	ISO 4217 currency code: NGN, GHS, KES, ZAR, USD.
`recipient`	`object`	Required	Recipient bank account details.
`recipient.account_number`	`string`	Required	10-digit NUBAN bank account number.
`recipient.bank_code`	`string`	Required	CBN bank code of the recipient's bank.
`recipient.name`	`string`	Optional	Account holder name. Provide this if you have already verified it — it is stored on the transfer record.
`reason`	`string`	Optional	Narration shown to the recipient. Max 100 characters.
`provider_id`	`string`	Optional	Force a specific provider: paystack, flutterwave, monnify, squad, interswitch. Omit to auto-select.
`metadata`	`object`	Optional	Up to 20 key-value pairs of string:string. Returned in all transfer responses.

Example requestbash

curl -X POST https://api.popfab.io/v1/transfers \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "PAYOUT-2025-00042",
    "amount": 500000,
    "currency": "NGN",
    "recipient": {
      "account_number": "0123456789",
      "bank_code": "058",
      "name": "Ada Okafor"
    },
    "reason": "March salary",
    "metadata": {
      "employee_id": "EMP-042"
    }
  }'

200 OK — Transfer objectjson

{
  "id": "ppfb_trf_01HXA3KBZQM4Z3YWN5E6R7VP8S",
  "reference": "PAYOUT-2025-00042",
  "amount": 500000,
  "currency": "NGN",
  "status": "pending",
  "provider": "paystack",
  "provider_transfer_code": "TRF_abc123xyz",
  "recipient": {
    "account_number": "0123456789",
    "bank_code": "058",
    "name": "Ada Okafor"
  },
  "reason": "March salary",
  "metadata": { "employee_id": "EMP-042" },
  "created_at": "2025-03-19T11:00:00.000Z",
  "updated_at": "2025-03-19T11:00:00.000Z"
}

ℹ

Transfers are processed asynchronously. The initial status is pending. Use GET /v1/transfers/:id to poll for the final status, or configure a webhook to be notified when it changes.

Bulk Transfer

Send multiple transfers in a single API call. All items in the batch use the same currency and provider. Useful for payroll, vendor payments, and mass disbursements.

POST

/v1/transfers/bulk

Initiates multiple transfers in one request. Each item is processed independently.

Request body

Parameter	Type	Required	Description
`currency`	`string`	Required	ISO 4217 currency code. Applied to all items in the batch.
`transfers`	`array`	Required	Array of transfer items. Each item follows the same shape as a single transfer body (reference, amount, recipient, reason).
`transfers[].reference`	`string`	Required	Unique reference for this individual transfer.
`transfers[].amount`	`integer`	Required	Amount in smallest currency unit.
`transfers[].recipient.account_number`	`string`	Required	Recipient account number.
`transfers[].recipient.bank_code`	`string`	Required	Recipient bank code.
`transfers[].recipient.name`	`string`	Optional	Recipient account name.
`transfers[].reason`	`string`	Optional	Transfer narration.
`provider_id`	`string`	Optional	Force a specific provider for the whole batch.

Example bulk requestbash

curl -X POST https://api.popfab.io/v1/transfers/bulk \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "transfers": [
      {
        "reference": "PAYOUT-2025-00043",
        "amount": 200000,
        "recipient": { "account_number": "0111222333", "bank_code": "011", "name": "Emeka Nwosu" },
        "reason": "March salary"
      },
      {
        "reference": "PAYOUT-2025-00044",
        "amount": 350000,
        "recipient": { "account_number": "0444555666", "bank_code": "033", "name": "Fatima Bello" },
        "reason": "March salary"
      }
    ]
  }'

200 OK — Bulk transfer responsejson

{
  "batchId": "ppfb_bulk_01HXA4KBZQM4Z3YWN5E6R7VP8S",
  "status": "queued",
  "total": 2,
  "transfers": [
    { "reference": "PAYOUT-2025-00043", "status": "pending", "id": "ppfb_trf_..." },
    { "reference": "PAYOUT-2025-00044", "status": "pending", "id": "ppfb_trf_..." }
  ]
}

List Transfers

GET

/v1/transfers

Returns a cursor-paginated list of transfers, newest first.

Query parameters

Parameter	Type	Required	Description
`status`	`string`	Optional	Filter by status: pending, processing, success, failed, reversed.
`limit`	`integer`	Optional	Results per page. Default 20, max 100.
`cursor`	`string`	Optional	Pagination cursor from a previous response next_cursor field.

List successful transfersbash

curl "https://api.popfab.io/v1/transfers?status=success&limit=50" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Get a Transfer

GET

/v1/transfers/:id

Retrieves the current state of a single transfer. If the transfer is still pending, POPFAB automatically queries the provider for the latest status before responding.

Get transfer by IDbash

curl https://api.popfab.io/v1/transfers/ppfb_trf_01HXA3KBZQM4Z3YWN5E6R7VP8S \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Transfer Statuses

Status	Description
pending	Transfer record created. Awaiting provider initiation.
processing	Submitted to the provider and in the clearing queue.
success	Funds have been delivered to the recipient account.
failed	Transfer could not be completed. See failure_reason for details.
reversed	Funds were returned to your wallet after a failed or disputed transfer.

Provider Capability

Provider	Single Transfer	Bulk Transfer	Account Verify
Paystack	✓	✓	✓
Flutterwave	✓	✓	✓
Monnify	✓	✓	✓
Squad	✓	—	✓
Interswitch	✓	—	—
Payaza	—	—	—

← PaymentsNext: Routing Rules →