Overview
Top up an existing eSIM with additional data using top-up packages. This extends the data allowance of an active eSIM without creating a new one.Key Requirements: Top-ups require:
packageType: 'TOPUP'packageCode: TOPUP package code (e.g., “TOPUP_P3ICIKSE8”)esimId: The ID of the eSIM to top up (obtained from previous purchase or fetch)
Two-Step Process: Like purchases, the top-up API returns a
transactionId. Query /api/esim/{transactionId} to get updated eSIM details with the new data balance.Quick Start
async function topUpEsim(esimId, topupPackageCode) {
// Step 1: Purchase top-up
const response = await fetch('https://api.vellosim.com/api/esim/buy', {
method: 'POST',
headers: {
'X-API-Key': `API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageCode: topupPackageCode, // TOPUP package code (e.g., TOPUP_P3ICIKSE8)
paymentMethod: 'WALLET',
packageType: 'TOPUP',
esimId: esimId // ID of the eSIM to top up
})
});
const data = await response.json();
if (data.status !== 'SUCCESS') {
throw new Error('Top-up failed');
}
// Step 2: Fetch updated eSIM details
const esimResponse = await fetch(
`https://api.vellosim.com/api/esim/${data.transactionId}`,
{
headers: {
'X-API-Key': `API_KEY}`
}
}
);
const esimData = await esimResponse.json();
return {
transactionId: data.transactionId,
iccid: esimData.iccid,
dataRemaining: esimData.data_usage_remain,
totalVolume: esimData.totalVolume,
validityRemaining: esimData.validity_usage_remain
};
}
// Usage
const result = await topUpEsim('69125f9f56d7f09edabbaf23', 'TOPUP_P3ICIKSE8');
console.log('Top-up successful! New data:', result.dataRemaining);
import requests
def topup_esim(esim_id, topup_package_code):
"""Top up an existing eSIM with additional data"""
headers = {
'X-API-Key': f' {API_KEY}',
'Content-Type': 'application/json'
}
# Step 1: Purchase top-up
purchase_data = {
'packageCode': topup_package_code, # TOPUP package code
'paymentMethod': 'WALLET',
'packageType': 'TOPUP',
'esimId': esim_id # ID of the eSIM to top up
}
purchase_response = requests.post(
'https://api.vellosim.com/api/esim/buy',
headers=headers,
json=purchase_data
)
purchase_result = purchase_response.json()
if purchase_result['status'] != 'SUCCESS':
raise Exception('Top-up failed')
transaction_id = purchase_result['transactionId']
# Step 2: Fetch updated eSIM details
esim_response = requests.get(
f'https://api.vellosim.com/api/esim/{transaction_id}',
headers=headers
)
esim_data = esim_response.json()
return {
'transactionId': transaction_id,
'iccid': esim_data['iccid'],
'dataRemaining': esim_data['data_usage_remain'],
'totalVolume': esim_data['totalVolume'],
'validityRemaining': esim_data['validity_usage_remain']
}
# Usage
result = topup_esim('69125f9f56d7f09edabbaf23', 'TOPUP_P3ICIKSE8')
print(f"Top-up successful! New data: {result['dataRemaining']}")
<?php
function topUpEsim($esimId, $topupPackageCode) {
$apiKey = 'YOUR_API_KEY';
$headers = [
'X-API-Key: ' . $apiKey,
'Content-Type: application/json'
];
// Step 1: Purchase top-up
$purchaseData = [
'packageCode' => $topupPackageCode, // TOPUP package code
'paymentMethod' => 'WALLET',
'packageType' => 'TOPUP',
'esimId' => $esimId // ID of the eSIM to top up
];
$ch = curl_init('https://api.vellosim.com/api/esim/buy');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($purchaseData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$purchaseResponse = curl_exec($ch);
$purchaseResult = json_decode($purchaseResponse, true);
curl_close($ch);
if ($purchaseResult['status'] !== 'SUCCESS') {
throw new Exception('Top-up failed');
}
$transactionId = $purchaseResult['transactionId'];
// Step 2: Fetch updated eSIM details
$ch = curl_init("https://api.vellosim.com/api/esim/{$transactionId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$esimResponse = curl_exec($ch);
$esimData = json_decode($esimResponse, true);
curl_close($ch);
return [
'transactionId' => $transactionId,
'iccid' => $esimData['iccid'],
'dataRemaining' => $esimData['data_usage_remain'],
'totalVolume' => $esimData['totalVolume'],
'validityRemaining' => $esimData['validity_usage_remain']
];
}
// Usage
$result = topUpEsim('69125f9f56d7f09edabbaf23', 'TOPUP_P3ICIKSE8');
echo "Top-up successful! New data: " . $result['dataRemaining'];
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type TopUpRequest struct {
PackageCode string `json:"packageCode"`
PaymentMethod string `json:"paymentMethod"`
PackageType string `json:"packageType"`
EsimID string `json:"esimId"`
}
PaymentMethod string `json:"paymentMethod"`
PackageType string `json:"packageType"`
}
type TopUpResponse struct {
Status string `json:"status"`
TransactionID string `json:"transactionId"`
}
type EsimDetails struct {
ICCID string `json:"iccid"`
DataUsageRemain int64 `json:"data_usage_remain"`
TotalVolume int64 `json:"totalVolume"`
ValidityUsageRemain int `json:"validity_usage_remain"`
}
func topUpEsim(apiKey, esimID, topupPackageCode string) (*EsimDetails, error) {
// Step 1: Purchase top-up
reqBody := TopUpRequest{
PackageCode: topupPackageCode,
PaymentMethod: "WALLET",
PackageType: "TOPUP",
EsimID: esimID,
}
jsonData, _ := json.Marshal(reqBody)
client := &http.Client{}
req, _ := http.NewRequest("POST", "https://api.vellosim.com/api/esim/buy",
bytes.NewBuffer(jsonData))
req.Header.Set("X-API-Key", apiKey)
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var purchaseResult TopUpResponse
json.Unmarshal(body, &purchaseResult)
if purchaseResult.Status != "SUCCESS" {
return nil, fmt.Errorf("top-up failed")
}
// Step 2: Fetch updated eSIM details
req2, _ := http.NewRequest("GET",
"https://api.vellosim.com/api/esim/"+purchaseResult.TransactionID, nil)
req2.Header.Set("X-API-Key", apiKey)
resp2, err := client.Do(req2)
if err != nil {
return nil, err
}
defer resp2.Body.Close()
body2, _ := io.ReadAll(resp2.Body)
var esimDetails EsimDetails
json.Unmarshal(body2, &esimDetails)
return &esimDetails, nil
}
func main() {
result, err := topUpEsim("YOUR_API_KEY", "69125f9f56d7f09edabbaf23", "TOPUP_P3ICIKSE8")
if err != nil {
fmt.Println("Top-up failed:", err)
return
}
fmt.Printf("Top-up successful! New data: %d bytes\n", result.DataUsageRemain)
}
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
packageCode | string | Yes | TOPUP package identifier (e.g., “TOPUP_P3ICIKSE8”) |
paymentMethod | string | Yes | Must be “WALLET” for API users |
packageType | string | Yes | Must be “TOPUP” for top-up purchases |
esimId | string | Yes | ID of the eSIM to top up (from purchase or fetch response) |
Finding TOPUP Packages: Query
/api/esim/packages?regionCode=US&type=TOPUP&packageCode=CKH533 to get available top-up packages. Top-up package codes are prefixed with TOPUP_.Successful Response
Step 1: Purchase Response{
"transactionId": "esim_1762812333247_7046",
"status": "SUCCESS",
"package": {
"packageCode": "TOPUP_P3ICIKSE8",
"name": "United States 10GB 30Days",
"price": 14640,
"volume": 0,
"duration": 0,
"currencyCode": "NGN"
}
}
{
"iccid": "8997250230000286674",
"transactionId": "esim_1762812333247_7046",
"totalVolume": 11261296640,
"data_usage_remain": 11261296640,
"validity_usage_remain": 37,
"expiredTime": "2026-05-09T21:56:47.000Z",
"packageDetails": {
"name": "United States 10GB 30Days",
"code": "CKH533",
"volume": 10737418240
}
}
The
totalVolume and data_usage_remain are updated to reflect the added data. Values are in bytes.Next Steps
Purchase eSIM
Buy a new eSIM package
API Reference
Complete API documentation
