Top-Up eSIM
Purchase
Top-Up eSIM
Add more data to an existing eSIM
POST
Top-Up eSIM
Endpoint
Description
Top up an existing eSIM with additional data. This uses the same purchase endpoint but withpackageType: 'TOPUP' and the esimId of the eSIM you want to refill.
Top-Up Flow
The complete top-up process follows these steps:Get your eSIMs
Call
GET /api/esim/my-esims to find the eSIM you want to top up. Note down its id and packageCode.Fetch top-up packages
Call
GET /api/esim/packages?type=TOPUP®ionCode={regionCode}&packageCode={packageCode} to see available top-up options.Get exchange rate (optional)
Call
GET /api/settings/exchange-rate to show the NGN equivalent price to your users.Purchase the top-up
Call
POST /api/esim/buy with packageType: 'TOPUP', the top-up packageCode, and the esimId.Authentication
API Key for authentication
Request Body
The top-up package code from the Get Top-Up Packages endpoint.
Payment method:
WALLET- Pay with wallet balance (instant)CARD- Pay with credit/debit cardBANK_TRANSFER- Pay via bank transfer
Must be
TOPUP for top-up purchases.The ID of the existing eSIM to top up. Get this from
GET /api/esim/my-esims.Response
Unique transaction ID for this top-up
Order status:
SUCCESS (wallet payment) or PENDING (card/bank transfer)Top-up package details
Updated eSIM details (only when
status is SUCCESS)Example Request
Example Response
Complete Top-Up Example
Here’s a full end-to-end example showing the entire top-up flow:Important Notes
Not all packages support top-ups. If
GET /api/esim/packages?type=TOPUP returns an empty array, the eSIM does not support data refills. The user would need to purchase a new eSIM instead.Next Steps
Get Top-Up Packages
Browse available top-up options
My eSIMs
Get your existing eSIMs
Check Balance
Check wallet balance before top-up
Top-Up Guide
Full integration guide
