curl --request POST \
--url https://api.nomba.com/v1/accounts/virtual \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'accountId: <accountid>' \
--data '
{
"accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
"accountName": "Daniel Scorsese",
"bvn": "12345678",
"nin": "12345678901",
"expiryDate": "2026-01-30 12:15:00",
"expectedAmount": "200.00"
}
'import requests
url = "https://api.nomba.com/v1/accounts/virtual"
payload = {
"accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
"accountName": "Daniel Scorsese",
"bvn": "12345678",
"nin": "12345678901",
"expiryDate": "2026-01-30 12:15:00",
"expectedAmount": "200.00"
}
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({
accountRef: '1oWbJQQHLyQqqf1SwxjSpudeA21',
accountName: 'Daniel Scorsese',
bvn: '12345678',
nin: '12345678901',
expiryDate: '2026-01-30 12:15:00',
expectedAmount: '200.00'
})
};
fetch('https://api.nomba.com/v1/accounts/virtual', 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/v1/accounts/virtual",
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([
'accountRef' => '1oWbJQQHLyQqqf1SwxjSpudeA21',
'accountName' => 'Daniel Scorsese',
'bvn' => '12345678',
'nin' => '12345678901',
'expiryDate' => '2026-01-30 12:15:00',
'expectedAmount' => '200.00'
]),
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/v1/accounts/virtual"
payload := strings.NewReader("{\n \"accountRef\": \"1oWbJQQHLyQqqf1SwxjSpudeA21\",\n \"accountName\": \"Daniel Scorsese\",\n \"bvn\": \"12345678\",\n \"nin\": \"12345678901\",\n \"expiryDate\": \"2026-01-30 12:15:00\",\n \"expectedAmount\": \"200.00\"\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/v1/accounts/virtual")
.header("accountId", "<accountid>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"accountRef\": \"1oWbJQQHLyQqqf1SwxjSpudeA21\",\n \"accountName\": \"Daniel Scorsese\",\n \"bvn\": \"12345678\",\n \"nin\": \"12345678901\",\n \"expiryDate\": \"2026-01-30 12:15:00\",\n \"expectedAmount\": \"200.00\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nomba.com/v1/accounts/virtual")
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 \"accountRef\": \"1oWbJQQHLyQqqf1SwxjSpudeA21\",\n \"accountName\": \"Daniel Scorsese\",\n \"bvn\": \"12345678\",\n \"nin\": \"12345678901\",\n \"expiryDate\": \"2026-01-30 12:15:00\",\n \"expectedAmount\": \"200.00\"\n}"
response = http.request(request)
puts response.read_body{
"code": "00",
"description": "Success",
"data": {
"createdAt": "2023-09-04T07:09:06.900Z",
"accountHolderId": "01a10aeb-d989-460a-bbde-9842f2b4320f",
"accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
"bvn": "12234412345",
"accountName": "Daniel Scorsese",
"currency": "NGN",
"identifierType": "BVN",
"bankName": "Nombank MFB",
"bankAccountNumber": "9391076543",
"bankAccountName": "Nomba/Ifeoluwa Adeboye",
"callbackUrl": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7",
"expired": true
}
}{
"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"
}Create virtual account
You can use this endpoint to create a virtual account to receive payments.
curl --request POST \
--url https://api.nomba.com/v1/accounts/virtual \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'accountId: <accountid>' \
--data '
{
"accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
"accountName": "Daniel Scorsese",
"bvn": "12345678",
"nin": "12345678901",
"expiryDate": "2026-01-30 12:15:00",
"expectedAmount": "200.00"
}
'import requests
url = "https://api.nomba.com/v1/accounts/virtual"
payload = {
"accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
"accountName": "Daniel Scorsese",
"bvn": "12345678",
"nin": "12345678901",
"expiryDate": "2026-01-30 12:15:00",
"expectedAmount": "200.00"
}
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({
accountRef: '1oWbJQQHLyQqqf1SwxjSpudeA21',
accountName: 'Daniel Scorsese',
bvn: '12345678',
nin: '12345678901',
expiryDate: '2026-01-30 12:15:00',
expectedAmount: '200.00'
})
};
fetch('https://api.nomba.com/v1/accounts/virtual', 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/v1/accounts/virtual",
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([
'accountRef' => '1oWbJQQHLyQqqf1SwxjSpudeA21',
'accountName' => 'Daniel Scorsese',
'bvn' => '12345678',
'nin' => '12345678901',
'expiryDate' => '2026-01-30 12:15:00',
'expectedAmount' => '200.00'
]),
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/v1/accounts/virtual"
payload := strings.NewReader("{\n \"accountRef\": \"1oWbJQQHLyQqqf1SwxjSpudeA21\",\n \"accountName\": \"Daniel Scorsese\",\n \"bvn\": \"12345678\",\n \"nin\": \"12345678901\",\n \"expiryDate\": \"2026-01-30 12:15:00\",\n \"expectedAmount\": \"200.00\"\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/v1/accounts/virtual")
.header("accountId", "<accountid>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"accountRef\": \"1oWbJQQHLyQqqf1SwxjSpudeA21\",\n \"accountName\": \"Daniel Scorsese\",\n \"bvn\": \"12345678\",\n \"nin\": \"12345678901\",\n \"expiryDate\": \"2026-01-30 12:15:00\",\n \"expectedAmount\": \"200.00\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nomba.com/v1/accounts/virtual")
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 \"accountRef\": \"1oWbJQQHLyQqqf1SwxjSpudeA21\",\n \"accountName\": \"Daniel Scorsese\",\n \"bvn\": \"12345678\",\n \"nin\": \"12345678901\",\n \"expiryDate\": \"2026-01-30 12:15:00\",\n \"expectedAmount\": \"200.00\"\n}"
response = http.request(request)
puts response.read_body{
"code": "00",
"description": "Success",
"data": {
"createdAt": "2023-09-04T07:09:06.900Z",
"accountHolderId": "01a10aeb-d989-460a-bbde-9842f2b4320f",
"accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
"bvn": "12234412345",
"accountName": "Daniel Scorsese",
"currency": "NGN",
"identifierType": "BVN",
"bankName": "Nombank MFB",
"bankAccountNumber": "9391076543",
"bankAccountName": "Nomba/Ifeoluwa Adeboye",
"callbackUrl": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7",
"expired": true
}
}{
"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"
}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. In each of the methods, You will get an ACCESS_TOKEN. You need to use an "Authorization" HTTP header to provide your ACCESS_TOKEN. For example: Authorization: {ACCESS_TOKEN}.
Headers
The parent accountId of the business.
"890022ce-bae0-45c1-9b9d-ee7872e6ca27"
Body
The request payload required to create an account
Account reference
16 - 64"1oWbJQQHLyQqqf1SwxjSpudeA21"
Account holder's name
8 - 64"Daniel Scorsese"
Account holder's BVN. Optional.
"12345678"
Account holder's National Identification Number (NIN). Optional.
Must be exactly 11 digits. Can be sent on its own or alongside bvn. If neither is sent, the BVN on the parent business account is used.
11^\d{11}$"12345678901"
Account expiry date. Optional. ⚠️Be careful with this.
"2026-01-30 12:15:00"
Amount the account can receive. Optional.
"200.00"