Skip to main content
POST
/
api
/
esim
/
buy
Top-Up eSIM
curl --request POST \
  --url https://api.vellosim.com/api/esim/buy \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "packageCode": "<string>",
  "paymentMethod": "<string>",
  "packageType": "<string>",
  "esimId": "<string>"
}
'
{
  "transactionId": "esim_1697888400_12345",
  "status": "SUCCESS",
  "message": "Top-up applied successfully",
  "package": {
    "packageCode": "CKH384_TOPUP_3GB",
    "name": "USA Top-Up 3GB - 30 Days",
    "price": 6.90,
    "currencyCode": "USD",
    "volume": 3221225472,
    "duration": 30
  },
  "esimDetails": {
    "iccid": "8901234567890123456",
    "totalVolume": 8589934592,
    "dataRemaining": 6442450944
  }
}

Endpoint

POST /api/esim/buy

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

X-API-Key
string
required
API Key for authentication
YOUR_API_KEY

Request Body

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

Response

transactionId
string
Unique transaction ID for this top-up
status
string
Order status: SUCCESS (wallet payment) or PENDING (card/bank transfer)
package
object
Top-up package details
esimDetails
object
Updated eSIM details (only when status is SUCCESS)

Example Request

curl -X POST https://api.vellosim.com/api/esim/buy \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "packageCode": "CKH384_TOPUP_3GB",
    "paymentMethod": "WALLET",
    "packageType": "TOPUP",
    "esimId": "69125f9f56d7f09edabbaf23"
  }'

Example Response

{
  "transactionId": "esim_1697888400_12345",
  "status": "SUCCESS",
  "message": "Top-up applied successfully",
  "package": {
    "packageCode": "CKH384_TOPUP_3GB",
    "name": "USA Top-Up 3GB - 30 Days",
    "price": 6.90,
    "currencyCode": "USD",
    "volume": 3221225472,
    "duration": 30
  },
  "esimDetails": {
    "iccid": "8901234567890123456",
    "totalVolume": 8589934592,
    "dataRemaining": 6442450944
  }
}

Complete Top-Up Example

Here’s a full end-to-end example showing the entire top-up flow:
async function completeTopUpFlow(esimId, regionCode, originalPackageCode) {
  const headers = {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  };

  // Step 1: Get available top-up packages
  const topupParams = new URLSearchParams({
    type: 'TOPUP',
    regionCode,
    packageCode: originalPackageCode
  });

  const topupsRes = await fetch(
    `https://api.vellosim.com/api/esim/packages?${topupParams}`,
    { headers }
  );
  const topups = await topupsRes.json();

  if (topups.length === 0) {
    console.log('No top-up options available for this eSIM');
    return null;
  }

  console.log(`${topups.length} top-up options available:`);
  topups.forEach((pkg, i) => {
    const gb = (pkg.volume / 1073741824).toFixed(1);
    console.log(`  ${i + 1}. ${pkg.name}: ${gb}GB — $${pkg.price}`);
  });

  // Step 2: Get exchange rate for NGN display
  const rateRes = await fetch(
    'https://api.vellosim.com/api/settings/exchange-rate',
    { headers }
  );
  const { data: rateData } = await rateRes.json();

  // Step 3: Select a top-up and show price
  const selected = topups[0]; // Pick first option
  const ngnPrice = Math.round(selected.price * rateData.rate * 100) / 100;
  console.log(`\nSelected: ${selected.name} — $${selected.price} (≈ ₦${ngnPrice.toLocaleString()})`);

  // Step 4: Purchase the top-up
  const purchaseRes = await fetch('https://api.vellosim.com/api/esim/buy', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      packageCode: selected.packageCode,
      paymentMethod: 'WALLET',
      packageType: 'TOPUP',
      esimId
    })
  });

  const result = await purchaseRes.json();

  if (result.status === 'SUCCESS') {
    console.log(`✅ Top-up applied! Transaction: ${result.transactionId}`);
  } else {
    console.log(`❌ Top-up failed: ${result.message}`);
  }

  return result;
}

// Usage
await completeTopUpFlow(
  '69125f9f56d7f09edabbaf23',  // esimId
  'US',                          // regionCode
  'CKH384'                       // original packageCode
);

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