Tutorial: Purchase Airtime or Data Using Bitcoin or USDT (No Wallet Funding Required)
This tutorial shows you how to let your users pay for airtime or data bundles in real-time using Bitcoin or USDT, without needing to fund a wallet first. Bitnob lets you execute airtime or data purchases directly from crypto payment flows, across supported countries and operators.
This is perfect if you're building:
A mobile wallet with direct crypto spending
A cross-border utility app for diaspora users
A telco interface powered by Lightning or stablecoins
Key Concepts
Users don’t need to hold crypto inside Bitnob. Instead:
You call the airtime or data API with the desired telco, amount, and phone number
Bitnob returns a crypto payment request (on-chain or Lightning)
Once the payment is made, Bitnob delivers the airtime/data instantly
This is a just-in-time crypto utility flow , not a wallet interaction.
Prerequisites
A Bitnob API key (sandbox or live)
The user specifies: phone number, amount, operator
You specify: crypto asset, payment method (Lightning or on-chain), country
Step 1: Get Airtime or Data Operators (if needed)
To dynamically list supported telcos and packages, your system should call an endpoint like:
This helps you avoid hardcoding operators like MTN, Airtel, Safaricom, etc.
Step 2: Initiate Airtime or Data Purchase
This step creates the actual airtime/data request and returns a crypto payment instruction. Bitnob will only fulfill the airtime or data once payment is received.
Example Request
Explanation of Fields
| FIELD | DEFINITION |
|---|---|
phoneNumber | Recipient's number (international format) |
amount | In local fiat (e.g. 2000 NGN) |
currency | Target currency of delivery (NGN, GHS, KES, etc.) |
operator | Telco name (e.g. MTN, Airtel, Safaricom) |
paymentAsset | USDT or BTC |
paymentMethod | trc20, erc20, lightning, bitcoin (on-chain) |
reference | Your internal transaction ID |
callbackUrl | Where Bitnob sends confirmation events |
Example Response
You should display the address (or Lightning invoice) and amount to the user. Once the payment is received and confirmed, Bitnob triggers the airtime top-up automatically.
Step 3: Track Payment and Delivery
You’ll receive webhook notifications to your callbackUrl with events like:
airtime.payment.received
airtime.delivered
airtime.failed
airtime.expired
airtime.underpayment
Use these to:
Mark the transaction complete in your UI
Retry if delivery fails
Notify users of status
You may also poll a status endpoint like:
If you haven’t implemented webhooks yet.
Best Practices
Always let the user pick a supported operator from /v1/airtime/operators
Match payment expiry (expiresAt) to a visible countdown timer
Avoid pre-converting crypto or holding balances
Handle underpayment by offering top-up option or cancel
Log the reference, asset, address, and final delivery status
Summary
With just one API call and a crypto payment, you can let your users top up airtime or mobile data across supported countries using Bitcoin or USDT. The user doesn’t need to pre-fund anything — Bitnob converts and settles in real time.
This flow is ideal for remittance use cases, local crypto utility, or building consumer wallets with telco features baked in.
