eSIM Management

The FYATU eSIM API allows you to programmatically issue and manage eSIMs for your users. Whether you’re building a travel app, IoT platform, or mobile connectivity service, our API provides access to thousands of data packages across 190+ countries.

How It Works

Browse Destinations

Query available destinations (countries or regions) to show your users where eSIMs are available.

Select a Package

Each destination has multiple packages with different data amounts, validity periods, and price points.

Purchase eSIM

Purchase the eSIM using your business wallet balance. The eSIM is instantly provisioned.

Activate on Device

Provide the QR code or manual activation code to your user. They scan it to install the eSIM.

Monitor & Top-up

Track usage in real-time and top-up data when needed without changing the eSIM.

Destinations

Destinations represent geographic coverage areas. There are three types:

Type	Description	Examples
Local	Single country coverage	France, Japan, United States
Regional	Multi-country coverage	Europe (39 countries), Asia Pacific
Global	Worldwide coverage	Global Data (100+ countries)

Destination Object

{
  "slug": "france",
  "countryCode": "FR",
  "name": "France",
  "type": "local",
  "imageUrl": "https://cdn.fyatu.com/flags/fr.svg",
  "lowestPrice": 4.50
}

Use the type filter when listing destinations to let users choose between local country plans or multi-country regional/global plans.

Packages

Each destination offers multiple eSIM packages. Packages vary by:

Data Amount: From 1GB to unlimited data
Validity Period: From 7 to 365 days
Price: Based on data, validity, and destination
Features: Data-only vs. voice/SMS included

Package Tiers

Packages are categorized into three tiers:

Tier	Description	Use Cases
Standard	Data-only packages	Travelers needing mobile data, IoT devices
Premium	Includes voice calls and/or SMS	Business travelers, users needing a phone number
Unlimited	Unlimited data (fair usage policies apply)	Heavy data users, content streaming

Package Object

{
  "packageId": "merhaba-7days-1gb",
  "name": "Merhaba 7 Days 1GB",
  "tier": "standard",
  "data": {
    "amount": 1024,
    "display": "1 GB",
    "isUnlimited": false
  },
  "validity": {
    "days": 7,
    "display": "7 days"
  },
  "price": {
    "amount": 4.50,
    "currency": "USD"
  },
  "features": {
    "hasVoice": false,
    "hasSms": false,
    "voiceMinutes": null,
    "smsCount": null
  },
  "operator": {
    "name": "Turkcell",
    "imageUrl": "https://cdn.fyatu.com/operators/turkcell.png"
  }
}

eSIM Lifecycle

An eSIM progresses through several statuses during its lifecycle:

Status	Description	Actions Available
`inactive`	Purchased but not yet activated	View details, get QR code
`active`	Currently in use	Monitor usage, top-up
`expired`	Validity period ended	None (read-only)
`consumed`	Data fully used	Top-up may reactivate

Purchasing eSIMs

Wallet Balance

eSIM purchases are deducted from your business wallet. Ensure sufficient balance before purchasing:

// Check wallet balance first
const wallet = await fyatu.account.getWallet();
const available = wallet.balance - wallet.holdBalance;

if (available < packagePrice * quantity) {
  throw new Error('Insufficient balance');
}

// Then purchase
const result = await fyatu.esim.purchase({
  packageId: 'merhaba-7days-1gb',
  quantity: 1
});

Batch Purchases

Purchase up to 10 eSIMs in a single request:

{
  "packageId": "merhaba-7days-1gb",
  "quantity": 5,
  "ownerId": "customer-12345"
}

The ownerId is optional and allows you to associate eSIMs with your own customer identifiers.

Activation

After purchase, each eSIM includes activation details:

Field	Description	Usage
`qrCodeUrl`	URL to QR code image	Display for user to scan
`manualCode`	Text activation code	For manual entry
`appleInstallUrl`	iOS direct install link	One-tap install on iPhone
`lpa`	LPA address	Technical: SM-DP+ address
`matchingId`	Matching ID	Technical: Activation code

QR Code Installation

The most common activation method:

User opens device Settings > Cellular/Mobile Data
User selects “Add eSIM” or “Add Cellular Plan”
User scans the QR code you provide
eSIM profile downloads and installs

Each QR code can only be used once. If a user needs to reinstall, they’ll need the manual activation code.

eSIM Identifiers

Each eSIM has two identifiers you can use:

Identifier	Format	Description
`iccid`	19-20 digits	The ICCID (Integrated Circuit Card Identifier) - unique to the SIM
`esimId`	ESIM-XXXXXXXX	FYATU’s internal eSIM identifier

We recommend using the ICCID for all API calls. It’s the industry-standard identifier and works with external tools. The esimId is also accepted for backwards compatibility.

Top-ups

Extend data or validity on an active eSIM without issuing a new one:

Get Available Top-ups

Call GET /esim/{iccid}/topups to see compatible top-up packages

Purchase Top-up

Call POST /esim/{iccid}/topup with the selected package ID

Automatic Application

The additional data/validity is applied immediately to the eSIM

Top-up packages are different from regular SIM packages. Only packages with packageType: "TOPUP" can be used for top-ups.

Usage Monitoring

Real-time Data

Get current usage stats for any eSIM:

{
  "usage": {
    "data": {
      "totalMb": 1024,
      "usedMb": 412,
      "remainingMb": 612,
      "percentUsed": 40.2
    },
    "voice": {
      "totalMinutes": 100,
      "usedMinutes": 15,
      "remainingMinutes": 85
    },
    "sms": {
      "total": 50,
      "used": 3,
      "remaining": 47
    }
  }
}

Refresh Usage

Usage data may be cached. To get the latest from the provider:

POST /v3/esim/{esimId}/refresh

Best Practices

Cache Destination/Package Data

Destinations and packages don’t change frequently. Cache them for 1-6 hours to reduce API calls and improve response times.

Handle Low Balance Scenarios

Check wallet balance before purchase attempts. Set up balance alerts in the dashboard to avoid failed purchases.

Store eSIM Details

Save the full eSIM response (especially activation codes) in your database. Users may need to reinstall or reference their eSIM later.

Implement Usage Alerts

Poll usage periodically for active eSIMs. Notify users when they reach 80% data consumption so they can top-up.

Use Webhooks for Status Changes

Configure webhooks to receive notifications when eSIM status changes (activated, expired, depleted) rather than polling.

Error Handling

Common eSIM-specific errors:

Error Code	Description	Resolution
`INSUFFICIENT_BALANCE`	Wallet balance too low	Top-up business wallet
`PACKAGE_NOT_FOUND`	Invalid or unavailable package	Refresh package list
`ESIM_NOT_FOUND`	eSIM doesn’t exist or not owned by you	Verify eSIM ID
`INVALID_STATUS`	eSIM can’t be topped up in current status	Check eSIM is active
`REGION_NOT_FOUND`	Can’t determine eSIM’s region for topup	Contact support

Pricing

eSIM pricing is set per package and displayed in USD:

Your Cost: The price field in package details
Retail Price: Set your own markup when reselling to end users
No Hidden Fees: The displayed price is the total charge

Ready to Start?

Explore the eSIM API reference to start integrating

Getting Started

Core Concepts

eSIM Management

eSIM Management

How It Works

Destinations

Destination Object

Packages

Package Tiers

Package Object

eSIM Lifecycle

Purchasing eSIMs

Wallet Balance

Batch Purchases

Activation

QR Code Installation

eSIM Identifiers

Top-ups

Usage Monitoring

Real-time Data

Refresh Usage

Best Practices

Error Handling

Pricing

Ready to Start?

Getting Started

Core Concepts

​eSIM Management

​How It Works

​Destinations

​Destination Object

​Packages

​Package Tiers

​Package Object

​eSIM Lifecycle

​Purchasing eSIMs

​Wallet Balance

​Batch Purchases

​Activation

​QR Code Installation

​eSIM Identifiers

​Top-ups

​Usage Monitoring

​Real-time Data

​Refresh Usage

​Best Practices

​Error Handling

​Pricing

Ready to Start?

eSIM Management

How It Works

Destinations

Destination Object

Packages

Package Tiers

Package Object

eSIM Lifecycle

Purchasing eSIMs

Wallet Balance

Batch Purchases

Activation

QR Code Installation

eSIM Identifiers

Top-ups

Usage Monitoring

Real-time Data

Refresh Usage

Best Practices

Error Handling

Pricing