Skip to main content
POST
/
esim
/
purchase
Purchase eSIM
curl --request POST \
  --url https://api.fyatu.com/api/v3/esim/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "packageId": "merhaba-7days-5gb",
  "quantity": 1,
  "ownerId": "customer-12345"
}
'
{
  "success": true,
  "status": 201,
  "message": "<string>",
  "data": {
    "orderId": "<string>",
    "reference": "<string>",
    "package": {
      "id": "<string>",
      "name": "<string>",
      "destination": "<string>"
    },
    "quantity": 123,
    "esims": [
      {
        "esimId": "<string>",
        "iccid": "<string>",
        "status": "ready",
        "activation": {
          "qrCodeUrl": "<string>",
          "manualCode": "<string>",
          "appleInstallUrl": "<string>"
        }
      }
    ],
    "price": 123,
    "currency": "<string>",
    "status": "<string>",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Purchase one or more eSIMs from a selected package. The cost is deducted from your business wallet balance.
For a complete guide on eSIM purchasing and lifecycle management, see eSIM Concepts.

​
Request Body

FieldTypeRequiredDescription
packageIdstringYesPackage ID from the packages list
quantityintegerNoNumber of eSIMs to purchase (1-10, default: 1)
ownerIdstringNoYour customer identifier for tracking

​
Prerequisites

Before purchasing:
  1. Check Balance: Ensure your wallet has sufficient funds
  2. Valid Package: Verify the package exists and is available
  3. Package Type: Only SIM packages can be purchased (not TOPUP)

​
Response

On successful purchase, you receive:
FieldDescription
packagePackage details (id, name, destination)
quantityNumber of eSIMs purchased
esimsArray of purchased eSIM details
totalPriceTotal amount charged
currencyCurrency (USD)

​
eSIM Object

Each eSIM in the array includes:
FieldDescription
esimIdUnique eSIM identifier (use for all operations)
iccideSIM ICCID (SIM card number)
orderIdProvider order reference
statusInitial status: inactive

​
Example Request

const response = await fetch('https://api.fyatu.com/api/v3/esim/purchase', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    packageId: 'merhaba-7days-5gb',
    quantity: 2,
    ownerId: 'customer-12345'
  })
});

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

// Store eSIM details
data.esims.forEach(esim => {
  console.log(`eSIM ${esim.esimId} purchased`);
  console.log(`ICCID: ${esim.iccid}`);

  // Save to your database for later retrieval
  saveEsimToDatabase({
    esimId: esim.esimId,
    iccid: esim.iccid,
    customerId: 'customer-12345',
    orderId: esim.orderId
  });
});

​
Example Response

{
  "success": true,
  "status": 201,
  "message": "eSIM purchased successfully",
  "data": {
    "package": {
      "packageId": "merhaba-7days-5gb",
      "name": "Merhaba 7 Days 5GB",
      "destination": "Turkey",
      "destinationType": "local"
    },
    "quantity": 2,
    "esims": [
      {
        "esimId": "ESIM-20260105-ABC12345",
        "iccid": "8910300000000012345",
        "orderId": "airalo-order-67890",
        "status": "inactive"
      },
      {
        "esimId": "ESIM-20260105-DEF67890",
        "iccid": "8910300000000012346",
        "orderId": "airalo-order-67891",
        "status": "inactive"
      }
    ],
    "totalPrice": 16.00,
    "currency": "USD"
  }
}

​
Error Handling

Error CodeHTTPDescription
INSUFFICIENT_BALANCE402Wallet balance too low
PACKAGE_NOT_FOUND404Invalid or unavailable package
VALIDATION_ERROR400Invalid quantity or missing packageId
PURCHASE_FAILED400Provider error during purchase

​
After Purchase

Once purchased, you’ll need to:
  1. Retrieve Activation Details: Call GET /esim/{esimId} to get QR code and manual codes
  2. Provide to User: Display QR code or send activation instructions
  3. Monitor Status: Track when the eSIM becomes active

Next: Get eSIM Details

Retrieve activation codes and full eSIM details

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Body

application/json
​
packageId
string
required

Package ID from the packages list

Example:

"merhaba-7days-5gb"

​
quantity
integer
default:1

Number of eSIMs to purchase

Required range: 1 <= x <= 10
​
ownerId
string

Your customer identifier for tracking (optional)

Example:

"customer-12345"

Response

eSIM purchased successfully

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
​
data
object
​
meta
object