Skip to main content
POST
Top-Up eSIM

Endpoint

Description

Top up an existing eSIM with additional data. This uses the same purchase endpoint but with packageType: 'TOPUP' and the esimId of the eSIM you want to refill.

Top-Up Flow

The complete top-up process follows these steps:
1

Get your eSIMs

Call GET /api/esim/my-esims to find the eSIM you want to top up. Note down its id and packageCode.
2

Fetch top-up packages

Call GET /api/esim/packages?type=TOPUP&regionCode={regionCode}&packageCode={packageCode} to see available top-up options.
3

Get exchange rate (optional)

Call GET /api/settings/exchange-rate to show the NGN equivalent price to your users.
4

Purchase the top-up

Call POST /api/esim/buy with packageType: 'TOPUP', the top-up packageCode, and the esimId.
5

Verify the top-up

Call GET /api/esim/{id} to confirm the updated data balance on the eSIM.

Authentication

string
required
API Key for authentication

Request Body

string
required
The top-up package code from the Get Top-Up Packages endpoint.
string
required
Payment method:
  • WALLET - Pay with wallet balance (instant)
  • CARD - Pay with credit/debit card
  • BANK_TRANSFER - Pay via bank transfer
string
required
Must be TOPUP for top-up purchases.
string
required
The ID of the existing eSIM to top up. Get this from GET /api/esim/my-esims.

Response

string
Unique transaction ID for this top-up
string
Order status: SUCCESS (wallet payment) or PENDING (card/bank transfer)
object
Top-up package details
object
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

Top-up requirements:
  • The eSIM must be active — you cannot top up expired or cancelled eSIMs
  • The top-up packageCode must be compatible with the original eSIM package
  • You must have sufficient wallet balance (for WALLET payment method)
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