Map Billing wallet for Utility

Before performing any utility transaction, you must map a billing wallet to the user. The mapped wallet is used to fund utility purchases made through LedgerBlock.

This is a required setup step for all utility transactions.

Once the wallet is successfully mapped, the user can proceed with utility operations such as mobile top-up, mobile data, cable TV, electricity, water, and other supported utility services.

Endpoint

POST {{base_url}}/api/v1/utility/wallet/bind

Headers

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

Request Body

The request requires the user reference and the wallet to be mapped for utility purchases.

{
  "user_ref": "{{vault:Merchant-user-ref}}",
  "wallet_id": "{{vault:eusd-wallet}}"
}

Request Fields

Field	Type	Required	Description
`user_ref`	string	Yes	The reference of the user whose wallet will be used for utility transactions.
`wallet_id`	string	Yes	The wallet ID to be mapped for utility purchases.

Example Request

curl --request POST \
  --url '{{base_url}}/api/v1/utility/wallet/bind' \
  --header 'x-merchant-ref: YOUR_MERCHANT_REF' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_ref": "{{vault:Merchant-user-ref}}",
    "wallet_id": "{{vault:eusd-wallet}}"
  }'

Successful Response

{
  "status": "success",
  "message": "Wallet bound for utility purchases",
  "data": {
    "user_ref": "UREF52EAF03D45714E47A65BF451969A22FB00CHN",
    "wallet_id": "LBWEUSD:MOB677851297ADB454BB35E1EEE16214E9B00EJU",
    "currency": "EUSD:MOB"
  }
}

Response Fields

Field	Type	Description
`status`	string	Indicates whether the request was successful.
`message`	string	Description of the operation result.
`data.user_ref`	string	The user reference associated with the wallet.
`data.wallet_id`	string	The wallet that has been mapped for utility purchases.
`data.currency`	string	Currency of the mapped wallet.

Utility Transaction Flow

Wallet mapping should be completed before initiating any utility transaction.

Create/Identify User
        ↓
Map Billing Wallet
        ↓
Retrieve Product Categories
        ↓
Select Utility Product
        ↓
Initiate Utility Transaction
        ↓
Receive Transaction Result/Webhook

Important: A billing wallet must be successfully mapped to the user before the user can perform utility transactions.

Updated 26 days ago

Did this page help you?