> ## Documentation Index
> Fetch the complete documentation index at: https://developer.nomba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vend data bundles via sub account (v2)
> You can use this endpoint to vend data via a sub account
Always requery the transaction using [Fetch a single transaction on a sub account](/nomba-api-reference/requery/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.
## OpenAPI
````yaml post /v2/bill/data/{subAccountId}
openapi: 3.0.1
info:
description: ''
title: Vendor API
version: 1.0.0
servers:
- description: Production
url: https://api.nomba.com
- description: Sandbox
url: https://sandbox.nomba.com
security: []
tags:
- name: Authenticate
- name: Accounts
- name: Virtual Accounts
- name: Online Checkout
- name: Charge
- name: Transfers
- name: Direct Debits
- name: Terminals
- name: Transactions
- name: Airtime and Data Vending
- name: Electricity Vending
- name: CableTV Subscription
- name: Betting Vending
paths:
/v2/bill/data/{subAccountId}:
post:
tags:
- Airtime and Data Vending
summary: Vend data bundles via sub account
description: You can use this endpoint to vend data via a sub account
operationId: Vend data bundles via specific or sub account v2
parameters:
- description: The parent accountId of the business this sub account belongs to
in: header
name: accountId
schema:
type: string
format: uuid
example: 890022ce-bae0-45c1-9b9d-ee7872e6ca27
required: true
- description: The sub accountId via which data bundle is to be vended
in: path
name: subAccountId
schema:
type: string
format: uuid
example: 890022ce-bae0-45c1-9b9d-ee7872e6ca27
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataVendingRequest'
example:
productId: mtn47
phoneNumber: '08055441122'
network: GLO
merchantTxRef: 3bvwhibh38220dsjakTwvb
senderName: John Doe
description: The request payload required to vend data bundles
required: true
responses:
'200':
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: >-
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.
example: '200'
enum:
- '200'
- '201'
- '400'
- '401'
- '403'
- '429'
- '500'
description:
type: string
example: SUCCESS
description: Response description
message:
type: string
description: Response message
example: Transaction completed Successfully
status:
type: boolean
description: Whether the request was successful
example: true
data:
$ref: '#/components/schemas/DataVendingV2Response'
required:
- code
- description
- data
example:
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'
description: OK - your request was successful.
headers:
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
schema:
type: string
example: '40'
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
schema:
type: string
example: '39'
X-Rate-Limit-Window:
description: The specified rate limit window
schema:
type: string
example: 1s
'201':
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: >-
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.
example: '201'
enum:
- '200'
- '201'
- '400'
- '401'
- '403'
- '429'
- '500'
description:
type: string
description: Response description
example: PROCESSING
message:
type: string
description: Response message
example: Processing
status:
type: boolean
description: Whether the request was successful
example: true
data:
$ref: '#/components/schemas/DataVendingV2Response'
required:
- code
- description
- data
example:
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'
description: >-
Created - your request was accepted and is being processed.
`data.status` is `PENDING_BILLING`; listen for webhook notifications
or requery the transaction for the final status.
headers:
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
schema:
type: string
example: '40'
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
schema:
type: string
example: '39'
X-Rate-Limit-Window:
description: The specified rate limit window
schema:
type: string
example: 1s
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
description: The request body sent by merchant did not pass the validation checks
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
description: >-
The access_token provided to access the resource is missing or
invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationError'
description: The client does not have the permissions to access this resource
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RecordNotFoundError'
description: The record that the client is trying to access does not exist.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
description: >-
The client has maxed out the number of calls within a time period on
this resource.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
description: Downstream system error.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
description: Resource not available
security:
- BearerAuth: []
components:
schemas:
DataVendingRequest:
type: object
properties:
productId:
type: string
description: >-
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
amount:
type: number
format: double
description: >-
**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.
deprecated: true
phoneNumber:
type: string
description: Recipient phone number
minLength: 11
maxLength: 13
example: '08055441122'
network:
type: string
description: >-
Recipient network (telco). It can also come as lowercased values
e.g. glo, mtn etc.
minLength: 3
enum:
- GLO
- MTN
- 9MOBILE
- AIRTEL
example: GLO
merchantTxRef:
type: string
description: Merchant Transaction Identifier reference (Unique to merchant)
example: 3bvwhibh38220dsjakTwvb
senderName:
type: string
description: A name to describe the sender of the data
example: John Doe
required:
- productId
- phoneNumber
- network
- merchantTxRef
DataVendingV2Response:
type: object
properties:
id:
type: string
description: Unique identifier of the data transaction
example: API-DATA-AAA1A-36dc6c70-5cf2-4592-93be-9bccc23df7f5
status:
type: string
description: >-
Status of the transaction. `SUCCESS` (HTTP 200) means the purchase
completed; `PENDING_BILLING` (HTTP 201) means it is still being
processed
example: SUCCESS
type:
type: string
description: Transaction type
example: data
amount:
type: number
format: double
description: Amount paid for the data bundle
example: 100
source:
type: string
description: Channel through which the transaction was initiated
example: api
sourceUserId:
type: string
description: Identifier of the source user, if any
nullable: true
customerBillerId:
type: string
description: Phone number credited with the data bundle
example: '08168969046'
productId:
type: string
description: Identifier of the data plan purchased
example: '62130'
meta:
type: object
description: >-
Additional transaction metadata, including the data plan purchased
(`data-plan`) and network
additionalProperties: true
example:
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:
type: string
description: Identifier of the user, if any
nullable: true
timeCreated:
type: string
description: Time the transaction was created
format: date-time
example: '2026-09-27T08:31:43.555+00:00'
required:
- id
- status
- type
- amount
- timeCreated
RequestError:
type: object
description: Request Error response.
properties:
code:
type: string
description: API error code.
example: '400'
description:
type: string
description: Additional details about the error.
example: Request failed.
AuthenticationError:
type: object
description: Authentication Error response.
properties:
code:
type: string
description: API error code.
example: '401'
description:
type: string
description: Additional details about the error.
example: Unauthorized
AuthorizationError:
type: object
description: Permissions error response.
properties:
code:
type: string
description: API error code.
example: '403'
description:
type: string
description: Additional details about the error.
example: Forbidden
RecordNotFoundError:
type: object
description: Record-Not-Found error response.
properties:
code:
type: string
description: API error code.
example: '404'
description:
type: string
description: Additional details about the error.
example: Record not found
RateLimitError:
type: object
description: Rate-limit error response.
properties:
code:
type: string
description: API error code.
example: '429'
description:
type: string
description: Additional details about the error.
example: Too many requests
ServerError:
type: object
description: Server error response.
properties:
code:
type: string
description: API error code.
example: '500'
description:
type: string
description: Additional details about the error.
example: Server error
securitySchemes:
BearerAuth:
description: >-
Nomba authenticates API calls with [OAuth2 HTTP bearer
tokens](http://tools.ietf.org/html/rfc6750). There are two methods of
authentication; [Client-Credentials
method](https://www.rfc-editor.org/rfc/rfc6749) and [PKCE (Proof Key for
Code Exchange)](https://www.rfc-editor.org/rfc/rfc7636) 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}`.
scheme: bearer
type: http
bearerFormat: JWT
````