Perform bank account transfer from the sub account
curl --request POST \
--url https://api.nomba.com/v2/transfers/bank/{subAccountId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'accountId: <accountid>' \
--data '
{
"amount": 3500,
"accountNumber": "0554772814",
"accountName": "M.A Animashaun",
"bankCode": "058",
"merchantTxRef": "UNQ_123abGGhh5546",
"senderName": "Nightly Post",
"narration": "Testing Payment"
}
'import requests
url = "https://api.nomba.com/v2/transfers/bank/{subAccountId}"
payload = {
"amount": 3500,
"accountNumber": "0554772814",
"accountName": "M.A Animashaun",
"bankCode": "058",
"merchantTxRef": "UNQ_123abGGhh5546",
"senderName": "Nightly Post",
"narration": "Testing Payment"
}
headers = {
"accountId": "<accountid>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
accountId: '<accountid>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 3500,
accountNumber: '0554772814',
accountName: 'M.A Animashaun',
bankCode: '058',
merchantTxRef: 'UNQ_123abGGhh5546',
senderName: 'Nightly Post',
narration: 'Testing Payment'
})
};
fetch('https://api.nomba.com/v2/transfers/bank/{subAccountId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nomba.com/v2/transfers/bank/{subAccountId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 3500,
'accountNumber' => '0554772814',
'accountName' => 'M.A Animashaun',
'bankCode' => '058',
'merchantTxRef' => 'UNQ_123abGGhh5546',
'senderName' => 'Nightly Post',
'narration' => 'Testing Payment'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"accountId: <accountid>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nomba.com/v2/transfers/bank/{subAccountId}"
payload := strings.NewReader("{\n \"amount\": 3500,\n \"accountNumber\": \"0554772814\",\n \"accountName\": \"M.A Animashaun\",\n \"bankCode\": \"058\",\n \"merchantTxRef\": \"UNQ_123abGGhh5546\",\n \"senderName\": \"Nightly Post\",\n \"narration\": \"Testing Payment\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("accountId", "<accountid>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nomba.com/v2/transfers/bank/{subAccountId}")
.header("accountId", "<accountid>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 3500,\n \"accountNumber\": \"0554772814\",\n \"accountName\": \"M.A Animashaun\",\n \"bankCode\": \"058\",\n \"merchantTxRef\": \"UNQ_123abGGhh5546\",\n \"senderName\": \"Nightly Post\",\n \"narration\": \"Testing Payment\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nomba.com/v2/transfers/bank/{subAccountId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["accountId"] = '<accountid>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 3500,\n \"accountNumber\": \"0554772814\",\n \"accountName\": \"M.A Animashaun\",\n \"bankCode\": \"058\",\n \"merchantTxRef\": \"UNQ_123abGGhh5546\",\n \"senderName\": \"Nightly Post\",\n \"narration\": \"Testing Payment\"\n}"
response = http.request(request)
puts response.read_body{
"code": "200",
"description": "Success",
"data": {
"amount": "1.0",
"meta": {
"api_rrn": "2309081xxxxxx",
"narration": "Testing",
"recipientName": "John doe",
"sender_name": "Nightly Post",
"merchantTxRef": "3JVW2xJCjj443oannREBuTaXDdji",
"api_client_id": "6a7bed88-7c93-4a1c-a445-f88edbca6489",
"currency": "NGN",
"hooksEligible": "true",
"banking_entity_id": "842f2b4320f",
"banking_entity_user_id": "01a10aeb-d989-460a-bbde-9842f2b4320f",
"banking_entity_type": "9842f2b4320f",
"self_transaction": "true",
"transactionCategory": "128735648",
"accountNumber": "0127667384",
"bankName": "GTbank",
"bankCode": "058",
"sessionId": "",
"user_referral_code": "HABI76745",
"amount_charged": "21.0",
"paymentVendor": "Wallet",
"wallet_balance": "5.38",
"wallet_currency": "NGN",
"paymentVendorReference": "01a10aeb-d989-460a-bbde-9840f",
"agent_commission": "0.0",
"useV2Fulfilment": "true"
},
"fee": 50,
"timeCreated": "2026-03-08T14:17:13.634Z",
"id": "API-TRANSFER-C24AD-a6443bf0-011c-4bc2-b739-4a2e33e2a27b",
"type": "transfer",
"status": "SUCCESS",
"source": "api",
"sourceUserId": "11ec45a1-1fe5-44f5-8baf-cxxxxxxxxxx",
"customerBillerId": "010784xxxx",
"productId": "058"
}
}{
"code": "201",
"description": "PROCESSING",
"message": "Unable to process response, please rely on web hook",
"status": false,
"data": {
"status": "PENDING_BILLING"
}
}{
"code": "400",
"description": "Request failed."
}{
"code": "401",
"description": "Unauthorized"
}{
"code": "403",
"description": "Forbidden"
}{
"code": "404",
"description": "Record not found"
}{
"code": "429",
"description": "Too many requests"
}{
"code": "500",
"description": "Server error"
}Transfers
Perform bank account transfer from the sub account
Initiate a bank transfer from a specific sub-account. Useful when managing multiple balances under your main account. Sub-account transfers must be enabled by Nomba before use. Sub-accounts can only be created from the Nomba dashboard.
POST
/
v2
/
transfers
/
bank
/
{subAccountId}
Perform bank account transfer from the sub account
curl --request POST \
--url https://api.nomba.com/v2/transfers/bank/{subAccountId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'accountId: <accountid>' \
--data '
{
"amount": 3500,
"accountNumber": "0554772814",
"accountName": "M.A Animashaun",
"bankCode": "058",
"merchantTxRef": "UNQ_123abGGhh5546",
"senderName": "Nightly Post",
"narration": "Testing Payment"
}
'import requests
url = "https://api.nomba.com/v2/transfers/bank/{subAccountId}"
payload = {
"amount": 3500,
"accountNumber": "0554772814",
"accountName": "M.A Animashaun",
"bankCode": "058",
"merchantTxRef": "UNQ_123abGGhh5546",
"senderName": "Nightly Post",
"narration": "Testing Payment"
}
headers = {
"accountId": "<accountid>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
accountId: '<accountid>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 3500,
accountNumber: '0554772814',
accountName: 'M.A Animashaun',
bankCode: '058',
merchantTxRef: 'UNQ_123abGGhh5546',
senderName: 'Nightly Post',
narration: 'Testing Payment'
})
};
fetch('https://api.nomba.com/v2/transfers/bank/{subAccountId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nomba.com/v2/transfers/bank/{subAccountId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 3500,
'accountNumber' => '0554772814',
'accountName' => 'M.A Animashaun',
'bankCode' => '058',
'merchantTxRef' => 'UNQ_123abGGhh5546',
'senderName' => 'Nightly Post',
'narration' => 'Testing Payment'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"accountId: <accountid>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nomba.com/v2/transfers/bank/{subAccountId}"
payload := strings.NewReader("{\n \"amount\": 3500,\n \"accountNumber\": \"0554772814\",\n \"accountName\": \"M.A Animashaun\",\n \"bankCode\": \"058\",\n \"merchantTxRef\": \"UNQ_123abGGhh5546\",\n \"senderName\": \"Nightly Post\",\n \"narration\": \"Testing Payment\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("accountId", "<accountid>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nomba.com/v2/transfers/bank/{subAccountId}")
.header("accountId", "<accountid>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 3500,\n \"accountNumber\": \"0554772814\",\n \"accountName\": \"M.A Animashaun\",\n \"bankCode\": \"058\",\n \"merchantTxRef\": \"UNQ_123abGGhh5546\",\n \"senderName\": \"Nightly Post\",\n \"narration\": \"Testing Payment\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nomba.com/v2/transfers/bank/{subAccountId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["accountId"] = '<accountid>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 3500,\n \"accountNumber\": \"0554772814\",\n \"accountName\": \"M.A Animashaun\",\n \"bankCode\": \"058\",\n \"merchantTxRef\": \"UNQ_123abGGhh5546\",\n \"senderName\": \"Nightly Post\",\n \"narration\": \"Testing Payment\"\n}"
response = http.request(request)
puts response.read_body{
"code": "200",
"description": "Success",
"data": {
"amount": "1.0",
"meta": {
"api_rrn": "2309081xxxxxx",
"narration": "Testing",
"recipientName": "John doe",
"sender_name": "Nightly Post",
"merchantTxRef": "3JVW2xJCjj443oannREBuTaXDdji",
"api_client_id": "6a7bed88-7c93-4a1c-a445-f88edbca6489",
"currency": "NGN",
"hooksEligible": "true",
"banking_entity_id": "842f2b4320f",
"banking_entity_user_id": "01a10aeb-d989-460a-bbde-9842f2b4320f",
"banking_entity_type": "9842f2b4320f",
"self_transaction": "true",
"transactionCategory": "128735648",
"accountNumber": "0127667384",
"bankName": "GTbank",
"bankCode": "058",
"sessionId": "",
"user_referral_code": "HABI76745",
"amount_charged": "21.0",
"paymentVendor": "Wallet",
"wallet_balance": "5.38",
"wallet_currency": "NGN",
"paymentVendorReference": "01a10aeb-d989-460a-bbde-9840f",
"agent_commission": "0.0",
"useV2Fulfilment": "true"
},
"fee": 50,
"timeCreated": "2026-03-08T14:17:13.634Z",
"id": "API-TRANSFER-C24AD-a6443bf0-011c-4bc2-b739-4a2e33e2a27b",
"type": "transfer",
"status": "SUCCESS",
"source": "api",
"sourceUserId": "11ec45a1-1fe5-44f5-8baf-cxxxxxxxxxx",
"customerBillerId": "010784xxxx",
"productId": "058"
}
}{
"code": "201",
"description": "PROCESSING",
"message": "Unable to process response, please rely on web hook",
"status": false,
"data": {
"status": "PENDING_BILLING"
}
}{
"code": "400",
"description": "Request failed."
}{
"code": "401",
"description": "Unauthorized"
}{
"code": "403",
"description": "Forbidden"
}{
"code": "404",
"description": "Record not found"
}{
"code": "429",
"description": "Too many requests"
}{
"code": "500",
"description": "Server error"
}Always requery the transaction using Fetch a single transaction on a sub account to confirm its final status before issuing a refund. Only refund if
data.status is REFUND.For a complete guide on response codes and transaction statuses, see Response Codes.
Authorizations
Nomba authenticates API calls with OAuth2 HTTP bearer tokens. There are two methods of authentication; Client-Credentials method and PKCE (Proof Key for Code Exchange) method. Both methods return an access token. Send it in the Authorization header: Authorization: Bearer <access_token>.
Headers
The parent accountId of the business.
Example:
"890022ce-bae0-45c1-9b9d-ee7872e6ca27"
Path Parameters
The sub accountId to transfer from.
Body
application/json
The request payload required to perform bank account transfer.
A structure representing an object required to post a bank account transfer.
The amount to be transferred.
Example:
3500
The destination bank account number.
Required string length:
10Example:
"0554772814"
The name on the account.
Example:
"M.A Animashaun"
The code of the recipient bank.
Example:
"058"
Unique reference used to track a transaction from an external process.
This is an idempotency key and must be unique per transaction.
Example:
"UNQ_123abGGhh5546"
Sender name
Example:
"Nightly Post"
The payment narration
Example:
"Testing Payment"
Response
OK - your request was successful.
Response code. This reflects the HTTP status code of the response, e.g. 200 when the request completed successfully and 201 when it was accepted and is still being processed.
Available options:
200, 201, 400, 401, 403, 429, 500 Example:
"200"
Response description
Example:
"Success"
Transfer data
Show child attributes
Show child attributes