Skip to main content
POST
/
esim
/
{iccid}
/
topup
Top-up eSIM
curl --request POST \
  --url https://api.fyatu.com/api/v3/esim/{iccid}/topup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "packageId": "merhaba-topup-1gb"
}
'
{
  "success": true,
  "status": 200,
  "message": "<string>",
  "data": {
    "esimId": "<string>",
    "packageId": "<string>",
    "packageName": "<string>",
    "price": 123,
    "currency": "<string>"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Add data or extend validity on an existing eSIM. The top-up is applied immediately without requiring the user to reinstall their eSIM.

​
Path Parameters

ParameterTypeDescription
iccidstringThe eSIM’s ICCID (also accepts esimId for backwards compatibility)

​
Request Body

FieldTypeRequiredDescription
packageIdstringYesTop-up package ID from the topups list

​
Prerequisites

Before topping up:
  1. Get Available Packages: Call GET /esim/{iccid}/topups first
  2. Valid Status: eSIM must be active or inactive
  3. Sufficient Balance: Business wallet must cover the top-up cost
  4. Package Type: Only TOPUP packages work (not regular SIM packages)

​
Response

FieldTypeDescription
iccidstringThe eSIM’s ICCID
esimIdstringThe topped-up eSIM
packageIdstringTop-up package applied
packageNamestringPackage name
pricenumberAmount charged
currencystringCurrency (USD)

​
Example Usage

const iccid = '8910300000000012345';

// First, check wallet balance
const walletResponse = await fetch('https://api.fyatu.com/api/v3/account/wallet', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});
const { data: wallet } = await walletResponse.json();

const topupPackageId = 'merhaba-topup-3gb';
const topupPrice = 8.00;

if (wallet.balance < topupPrice) {
  throw new Error('Insufficient balance');
}

// Perform top-up
const response = await fetch(`https://api.fyatu.com/api/v3/esim/${iccid}/topup`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    packageId: topupPackageId
  })
});

const { data } = await response.json();

console.log(`Top-up successful!`);
console.log(`Package: ${data.packageName}`);
console.log(`Charged: $${data.price}`);

// Optionally refresh to get updated usage
const refreshResponse = await fetch(`https://api.fyatu.com/api/v3/esim/${iccid}/refresh`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "eSIM topped up successfully",
  "data": {
    "iccid": "8910300000000012345",
    "esimId": "ESIM-20260105-ABC12345",
    "packageId": "merhaba-topup-3gb",
    "packageName": "Top-up 3GB",
    "price": 8.00,
    "currency": "USD"
  }
}

​
Error Handling

Error CodeHTTPDescription
ESIM_NOT_FOUND404eSIM doesn’t exist or not owned by you
INVALID_STATUS400eSIM is expired or consumed
PACKAGE_NOT_FOUND404Invalid top-up package ID
INSUFFICIENT_BALANCE402Wallet balance too low
TOPUP_FAILED400Provider error during top-up

​
eSIM Status After Top-up

  • If eSIM was active: Remains active with additional data
  • If eSIM was inactive: Remains inactive (still needs activation)
  • If eSIM was consumed: May become active again with new data
After a successful top-up, call POST /esim/{iccid}/refresh to get the updated data balance.

​
Best Practices

  1. Show Current Usage: Display remaining data before offering top-up
  2. Suggest Appropriate Packages: Recommend packages based on user’s typical usage
  3. Confirm Before Charging: Show price and get user confirmation
  4. Handle Failures Gracefully: If top-up fails, the eSIM’s current data is unchanged

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

​
iccid
string
required

eSIM ICCID (19-20 digits) or esimId (ESIM-XXXXXXXX)

Body

application/json
​
packageId
string
required

Top-up package ID from the topups list

Response

eSIM topped up successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
​
data
object
​
meta
object