Purchase Data

Use this endpoint to purchase a mobile data bundle for a recipient.

Before making a data purchase, the user's billing wallet must be mapped for utility transactions using the Map Billing Wallet for Utility endpoint.

Endpoint

POST {{base_url}}/api/v1/utility/transactions/data

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer authentication token.
`x-merchant-ref`	string	Yes	Your unique merchant reference.
`Content-Type`	string	Yes	Must be `application/json`.

Authorization

Include your access token in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body

{
  "user_ref": "UREF52EAF03D45714E47A65BF451969A22FB00CHN",
  "operator_id": "1",
  "product_id": "12",
  "wallet_id": "LBWEUSD:MOB677851297ADB454BB35E1EEE16214E9B00EJU",
  "recipient": "2348064642044",
  "amount": 50,
  "currency": "NGN",
  "reference": "",
  "extra_parameters": {}
}

Request Fields

Field	Type	Required	Description
`user_ref`	string	Yes	Reference of the user making the utility purchase.
`operator_id`	string	Yes	Unique identifier of the mobile network operator.
`product_id`	string	Yes	Identifier of the data product to purchase.
`wallet_id`	string	Yes	ID of the billing wallet mapped to the user for utility transactions.
`recipient`	string	Yes	Phone number that will receive the data bundle. Use the appropriate international format.
`amount`	number	Yes	Amount to be charged for the data purchase.
`currency`	string	Yes	Currency of the transaction.
`reference`	string	No	Merchant-generated reference for the transaction.
`extra_parameters`	object	No	Additional parameters required for the selected product.

Example Request

curl --request POST \
  --url '{{base_url}}/api/v1/utility/transactions/data' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-merchant-ref: YOUR_MERCHANT_REF' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_ref": "UREF52EAF03D45714E47A65BF451969A22FB00CHN",
    "operator_id": "1",
    "product_id": "12",
    "wallet_id": "LBWEUSD:MOB677851297ADB454BB35E1EEE16214E9B00EJU",
    "recipient": "2348064642044",
    "amount": 50,
    "currency": "NGN",
    "reference": "",
    "extra_parameters": {}
  }'

Transaction Parameters

The operator_id and product_id determine the specific network and data bundle being purchased.

You can retrieve available utility categories and use the relevant utility product endpoints to identify supported products before initiating the transaction.

The wallet_id must correspond to the wallet previously mapped to the user's utility billing configuration.

Reference

The reference field can be used to provide your own transaction identifier.

For example:

{
  "reference": "DATA-ORDER-00125"
}

Using a unique reference for each transaction makes it easier to reconcile transactions in your system.

Extra Parameters

extra_parameters is an object reserved for any additional information required by a particular data product.

When no additional parameters are required, send an empty object:

"extra_parameters": {}

Transaction Flow

User
  ↓
Billing Wallet Mapped
  ↓
Identify Operator
  ↓
Identify Data Product
  ↓
Buy Data
  ↓
LedgerBlock Processes Transaction
  ↓
Transaction Result / Webhook

Important: The billing wallet must be successfully mapped to the user before initiating a data purchase.