Use this guide to send a single bank transfer through the Kuda Business API.
Recommended flow:
Fetch the bank list.
Run name enquiry.
Submit the transfer.
Check uncertain outcomes with Transaction Status Query.
Step 1: Fetch the bank list
Before you transfer money, call BANK_LIST in the same environment where the transfer will happen.
Bank codes can differ between UAT and production, so do not hardcode a production bank code into UAT tests.
{
"serviceType": "BANK_LIST",
"requestRef": "BANK001",
"data": {}
}
Use the returned bankCode in name enquiry and transfer requests.
Step 2: Verify the beneficiary
Run NAME_ENQUIRY before every transfer.
{
"serviceType": "NAME_ENQUIRY",
"requestRef": "NE001",
"data": {
"beneficiaryAccountNumber": "7000000000",
"beneficiaryBankCode": "999129"
}
}
Check the response for:
beneficiary account number
beneficiary name
beneficiary bank code
account status
Only continue if the beneficiary details match the intended recipient.
Step 3: Submit the transfer
Use SINGLE_FUND_TRANSFER after the beneficiary has been verified.
Amounts are sent in kobo. For example, NGN 5,000 is 500000.
{
"serviceType": "SINGLE_FUND_TRANSFER",
"requestRef": "TRF20260603001",
"data": {
"beneficiaryAccount": "7000000000",
"beneficiaryBankCode": "999129",
"beneficiaryName": "Sample Recipient",
"clientAccountNumber": "2000000000",
"amount": "500000",
"narration": "Vendor payment"
}
}
Use your Kuda Business main account number as clientAccountNumber.
Step 4: Check transfer status
Use TRANSACTION_STATUS_QUERY when:
the transfer returns a pending response
the request times out
no response body is received
you need to confirm the final outcome
Use the original transfer requestRef as transactionRequestReference.
{
"serviceType": "TRANSACTION_STATUS_QUERY",
"requestRef": "TSQ20260603001",
"data": {
"isThirdPartyBankTransfer": false,
"transactionRequestReference": "TRF20260603001"
}
}
If a transfer request times out, wait 30 to 60 seconds, then run TSQ with the original requestRef. Do not immediately submit a new transfer with a new reference.
Response handling
Response | Meaning | Recommended action |
| Successful or accepted as successful | Store the response and confirm with TSQ when needed. |
| Pending | Run TSQ before retrying. |
| Timeout | Run TSQ with the original reference. |
| Duplicate request reference | Check whether the original request already succeeded. |
| Insufficient balance | Fund the account before retrying. |
Implementation checklist
Keep Kuda credentials server-side.
Call
BANK_LISTin the active environment.Run
NAME_ENQUIRYbefore transfer.Convert naira to kobo correctly.
Generate a short, unique
requestRef.Store the original request and response.
Use TSQ before retrying uncertain transfers.
Show a confirmation step in your product before executing money movement.
Common mistakes
Skipping name enquiry.
Reusing bank codes across UAT and production.
Losing the original
requestRef.Treating timeout as failure without checking TSQ.
Retrying immediately and creating duplicate transfers.