Vend data bundles via sub account (v2)

Vend data bundles via sub account

curl --request POST \
  --url https://api.nomba.com/v2/bill/data/{subAccountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '
{
  "productId": "mtn47",
  "phoneNumber": "08055441122",
  "network": "GLO",
  "merchantTxRef": "3bvwhibh38220dsjakTwvb",
  "senderName": "John Doe"
}
'

import requests

url = "https://api.nomba.com/v2/bill/data/{subAccountId}"

payload = {
    "productId": "mtn47",
    "phoneNumber": "08055441122",
    "network": "GLO",
    "merchantTxRef": "3bvwhibh38220dsjakTwvb",
    "senderName": "John Doe"
}
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({
    productId: 'mtn47',
    phoneNumber: '08055441122',
    network: 'GLO',
    merchantTxRef: '3bvwhibh38220dsjakTwvb',
    senderName: 'John Doe'
  })
};

fetch('https://api.nomba.com/v2/bill/data/{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/bill/data/{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([
    'productId' => 'mtn47',
    'phoneNumber' => '08055441122',
    'network' => 'GLO',
    'merchantTxRef' => '3bvwhibh38220dsjakTwvb',
    'senderName' => 'John Doe'
  ]),
  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/bill/data/{subAccountId}"

	payload := strings.NewReader("{\n  \"productId\": \"mtn47\",\n  \"phoneNumber\": \"08055441122\",\n  \"network\": \"GLO\",\n  \"merchantTxRef\": \"3bvwhibh38220dsjakTwvb\",\n  \"senderName\": \"John Doe\"\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/bill/data/{subAccountId}")
  .header("accountId", "<accountid>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"mtn47\",\n  \"phoneNumber\": \"08055441122\",\n  \"network\": \"GLO\",\n  \"merchantTxRef\": \"3bvwhibh38220dsjakTwvb\",\n  \"senderName\": \"John Doe\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomba.com/v2/bill/data/{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  \"productId\": \"mtn47\",\n  \"phoneNumber\": \"08055441122\",\n  \"network\": \"GLO\",\n  \"merchantTxRef\": \"3bvwhibh38220dsjakTwvb\",\n  \"senderName\": \"John Doe\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": "200",
  "description": "SUCCESS",
  "message": "Transaction completed Successfully",
  "status": true,
  "data": {
    "id": "API-DATA-AAA1A-36dc6c70-5cf2-4592-93be-9bccc23df7f5",
    "status": "SUCCESS",
    "type": "data",
    "amount": 100,
    "source": "api",
    "sourceUserId": null,
    "customerBillerId": "08168969046",
    "productId": "62130",
    "meta": {
      "api_rrn": "260927093143",
      "data-plan": "110MB Daily Plan",
      "rrn": "260927093143",
      "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "api_client_id": "2167288-d989-460a-bbde-9842f2b4320f",
      "user_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "merchantTxRef": "REF-29-07-2026-13",
      "allowDuplicate": true,
      "sender_name": "John Doe",
      "idempotentKey": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "pos_withdrawal_id": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "userName": "John Doe",
      "isCorporate": "true",
      "currency": "NGN",
      "hooksEligible": "true",
      "isSubscribedToSavingsService": false,
      "isSubscribedToLoanService": false,
      "txnAlertEligible": false,
      "banking_entity_id": 189585760,
      "banking_entity_user_id": 188595905,
      "banking_entity_type": "CORPORATE",
      "self_transaction": true,
      "transactionCategory": "Bills & Utility",
      "network": "mtn",
      "subscriberNumber": "08123456788",
      "amount_charged": "100.0",
      "paymentVendor": "wallet",
      "wallet_balance": "2955.85",
      "wallet_currency": "NGN",
      "agent_commission": "0.0",
      "gatewayMessage": "Success",
      "billingVendor": "cowrie",
      "billingServiceResponse": "SUCCESS",
      "income": "2.5",
      "paymentFee": 0,
      "tx_revenue": "2.5",
      "phoneNumber": "08123456788"
    },
    "userId": null,
    "timeCreated": "2026-09-27T08:31:43.555+00:00"
  }
}

{
  "code": "201",
  "description": "PROCESSING",
  "message": "Processing",
  "status": true,
  "data": {
    "id": "API-DATA-AAA1A-36dc6c70-5cf2-4592-93be-9bccc23df7f5",
    "status": "PENDING_BILLING",
    "type": "data",
    "amount": 100,
    "source": "api",
    "sourceUserId": null,
    "customerBillerId": "08168969046",
    "productId": "62130",
    "meta": {
      "api_rrn": "260927093143",
      "data-plan": "110MB Daily Plan",
      "rrn": "260927093143",
      "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "api_client_id": "2167288-d989-460a-bbde-9842f2b4320f",
      "user_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "merchantTxRef": "REF-29-07-2026-13",
      "allowDuplicate": true,
      "sender_name": "John Doe",
      "idempotentKey": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "pos_withdrawal_id": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "userName": "John Doe",
      "isCorporate": "true",
      "currency": "NGN",
      "hooksEligible": "true",
      "isSubscribedToSavingsService": false,
      "isSubscribedToLoanService": false,
      "txnAlertEligible": false,
      "banking_entity_id": 189585760,
      "banking_entity_user_id": 188595905,
      "banking_entity_type": "CORPORATE",
      "self_transaction": true,
      "transactionCategory": "Bills & Utility",
      "network": "mtn",
      "subscriberNumber": "08123456788",
      "amount_charged": "100.0",
      "paymentVendor": "wallet",
      "wallet_balance": "2955.85",
      "wallet_currency": "NGN",
      "phoneNumber": "08123456788"
    },
    "userId": null,
    "timeCreated": "2026-09-27T08:31:43.555+00:00"
  }
}

{
  "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"
}

{
  "code": "400",
  "description": "Request failed."
}

POST

bill

data

{subAccountId}

Vend data bundles via sub account

curl --request POST \
  --url https://api.nomba.com/v2/bill/data/{subAccountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '
{
  "productId": "mtn47",
  "phoneNumber": "08055441122",
  "network": "GLO",
  "merchantTxRef": "3bvwhibh38220dsjakTwvb",
  "senderName": "John Doe"
}
'

import requests

url = "https://api.nomba.com/v2/bill/data/{subAccountId}"

payload = {
    "productId": "mtn47",
    "phoneNumber": "08055441122",
    "network": "GLO",
    "merchantTxRef": "3bvwhibh38220dsjakTwvb",
    "senderName": "John Doe"
}
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({
    productId: 'mtn47',
    phoneNumber: '08055441122',
    network: 'GLO',
    merchantTxRef: '3bvwhibh38220dsjakTwvb',
    senderName: 'John Doe'
  })
};

fetch('https://api.nomba.com/v2/bill/data/{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/bill/data/{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([
    'productId' => 'mtn47',
    'phoneNumber' => '08055441122',
    'network' => 'GLO',
    'merchantTxRef' => '3bvwhibh38220dsjakTwvb',
    'senderName' => 'John Doe'
  ]),
  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/bill/data/{subAccountId}"

	payload := strings.NewReader("{\n  \"productId\": \"mtn47\",\n  \"phoneNumber\": \"08055441122\",\n  \"network\": \"GLO\",\n  \"merchantTxRef\": \"3bvwhibh38220dsjakTwvb\",\n  \"senderName\": \"John Doe\"\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/bill/data/{subAccountId}")
  .header("accountId", "<accountid>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"mtn47\",\n  \"phoneNumber\": \"08055441122\",\n  \"network\": \"GLO\",\n  \"merchantTxRef\": \"3bvwhibh38220dsjakTwvb\",\n  \"senderName\": \"John Doe\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomba.com/v2/bill/data/{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  \"productId\": \"mtn47\",\n  \"phoneNumber\": \"08055441122\",\n  \"network\": \"GLO\",\n  \"merchantTxRef\": \"3bvwhibh38220dsjakTwvb\",\n  \"senderName\": \"John Doe\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": "200",
  "description": "SUCCESS",
  "message": "Transaction completed Successfully",
  "status": true,
  "data": {
    "id": "API-DATA-AAA1A-36dc6c70-5cf2-4592-93be-9bccc23df7f5",
    "status": "SUCCESS",
    "type": "data",
    "amount": 100,
    "source": "api",
    "sourceUserId": null,
    "customerBillerId": "08168969046",
    "productId": "62130",
    "meta": {
      "api_rrn": "260927093143",
      "data-plan": "110MB Daily Plan",
      "rrn": "260927093143",
      "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "api_client_id": "2167288-d989-460a-bbde-9842f2b4320f",
      "user_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "merchantTxRef": "REF-29-07-2026-13",
      "allowDuplicate": true,
      "sender_name": "John Doe",
      "idempotentKey": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "pos_withdrawal_id": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "userName": "John Doe",
      "isCorporate": "true",
      "currency": "NGN",
      "hooksEligible": "true",
      "isSubscribedToSavingsService": false,
      "isSubscribedToLoanService": false,
      "txnAlertEligible": false,
      "banking_entity_id": 189585760,
      "banking_entity_user_id": 188595905,
      "banking_entity_type": "CORPORATE",
      "self_transaction": true,
      "transactionCategory": "Bills & Utility",
      "network": "mtn",
      "subscriberNumber": "08123456788",
      "amount_charged": "100.0",
      "paymentVendor": "wallet",
      "wallet_balance": "2955.85",
      "wallet_currency": "NGN",
      "agent_commission": "0.0",
      "gatewayMessage": "Success",
      "billingVendor": "cowrie",
      "billingServiceResponse": "SUCCESS",
      "income": "2.5",
      "paymentFee": 0,
      "tx_revenue": "2.5",
      "phoneNumber": "08123456788"
    },
    "userId": null,
    "timeCreated": "2026-09-27T08:31:43.555+00:00"
  }
}

{
  "code": "201",
  "description": "PROCESSING",
  "message": "Processing",
  "status": true,
  "data": {
    "id": "API-DATA-AAA1A-36dc6c70-5cf2-4592-93be-9bccc23df7f5",
    "status": "PENDING_BILLING",
    "type": "data",
    "amount": 100,
    "source": "api",
    "sourceUserId": null,
    "customerBillerId": "08168969046",
    "productId": "62130",
    "meta": {
      "api_rrn": "260927093143",
      "data-plan": "110MB Daily Plan",
      "rrn": "260927093143",
      "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "api_client_id": "2167288-d989-460a-bbde-9842f2b4320f",
      "user_id": "0167288-d989-460a-bbde-9842f2b4320f",
      "merchantTxRef": "REF-29-07-2026-13",
      "allowDuplicate": true,
      "sender_name": "John Doe",
      "idempotentKey": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "pos_withdrawal_id": "0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-13",
      "userName": "John Doe",
      "isCorporate": "true",
      "currency": "NGN",
      "hooksEligible": "true",
      "isSubscribedToSavingsService": false,
      "isSubscribedToLoanService": false,
      "txnAlertEligible": false,
      "banking_entity_id": 189585760,
      "banking_entity_user_id": 188595905,
      "banking_entity_type": "CORPORATE",
      "self_transaction": true,
      "transactionCategory": "Bills & Utility",
      "network": "mtn",
      "subscriberNumber": "08123456788",
      "amount_charged": "100.0",
      "paymentVendor": "wallet",
      "wallet_balance": "2955.85",
      "wallet_currency": "NGN",
      "phoneNumber": "08123456788"
    },
    "userId": null,
    "timeCreated": "2026-09-27T08:31:43.555+00:00"
  }
}

{
  "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"
}

{
  "code": "400",
  "description": "Request failed."
}

Always requery the transaction using Fetch a single transaction on a sub account to confirm its final status before issuing a refund.

The code field in the response reflects the HTTP status code of the response. For example, 200 means the request completed successfully, and 201 means it was accepted and is still being processed.

Authorizations

Authorization

string

header

required

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

accountId

string<uuid>

required

The parent accountId of the business this sub account belongs to

Example:

"890022ce-bae0-45c1-9b9d-ee7872e6ca27"

Path Parameters

subAccountId

string<uuid>

required

The sub accountId via which data bundle is to be vended

Example:

"890022ce-bae0-45c1-9b9d-ee7872e6ca27"

Body

application/json

The request payload required to vend data bundles

productId

string

required

The unique identifier of the data plan to purchase — returned as productId by the Fetch Data Plans endpoint. Required for all new integrations: it resolves to an exact plan and amount, removing any ambiguity when multiple plans on the same network share the same price.

Example:

"mtn47"

phoneNumber

string

required

Recipient phone number

Required string length: 11 - 13

Example:

"08055441122"

network

enum<string>

required

Recipient network (telco). It can also come as lowercased values e.g. glo, mtn etc.

Available options:

GLO,

MTN,

9MOBILE,

AIRTEL

Minimum string length: 3

Example:

"GLO"

merchantTxRef

string

required

Merchant Transaction Identifier reference (Unique to merchant)

Example:

"3bvwhibh38220dsjakTwvb"

amount

number<double>

deprecated

Deprecated — do not use. amount is a legacy-only field with no guarantee of correctness: multiple plans can share the same price, so it cannot reliably identify the bundle you want. Use productId — the only supported way to select a plan.

senderName

string

A name to describe the sender of the data

Example:

"John Doe"

Response

OK - your request was successful.

code

enum<string>

required

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"

description

string

required

Response description

Example:

"SUCCESS"

data

object

required

Show child attributes

message

string

Response message

Example:

"Transaction completed Successfully"

status

boolean

Whether the request was successful

Example:

true

API Documentation

Authenticate

Accounts

Virtual Accounts

Online Checkout

Charge

Direct Debits

Transfers

Terminals

Transactions

Requery

Global Payout

DRC Collection

Airtime & Data Vending

Cable & Bill Payments

Betting

Vend data bundles via sub account (v2)

Authorizations

Headers

Path Parameters

Body

Response