Overview
Purchase eSIM packages using your wallet balance. All API purchases use WALLET payment method and are processed instantly. The system automatically checks your balance and creates the eSIM immediately upon successful payment.Two-Step Process: The purchase API returns a
transactionId and basic package info. You must then query the eSIM endpoint using the transactionId to retrieve complete eSIM details including QR code and activation information.Quick Start
async function purchaseEsim(packageCode) {
// Step 1: Purchase eSIM
const purchaseResponse = 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: packageCode,
paymentMethod: 'WALLET',
packageType: 'BASE'
})
});
const purchaseData = await purchaseResponse.json();
if (purchaseData.status !== 'SUCCESS') {
throw new Error('Purchase failed');
}
// Step 2: Fetch complete eSIM details
const esimResponse = await fetch(
`https://api.vellosim.com/api/esim/${purchaseData.transactionId}`,
{
headers: {
'X-API-Key': `API_KEY}`
}
}
);
const esimData = await esimResponse.json();
return {
transactionId: purchaseData.transactionId,
iccid: esimData.iccid,
qrCodeUrl: esimData.qrCodeUrl,
activationCode: esimData.ac,
packageDetails: esimData.packageDetails
};
}
// Usage
const result = await purchaseEsim('PWZ5FXSJ3');
console.log('eSIM purchased:', result.iccid);
console.log('QR Code:', result.qrCodeUrl);
import requests
def purchase_esim(package_code):
"""Purchase eSIM and fetch complete details"""
headers = {
'X-API-Key': f' {API_KEY}',
'Content-Type': 'application/json'
}
# Step 1: Purchase eSIM
purchase_data = {
'packageCode': package_code,
'paymentMethod': 'WALLET',
'packageType': 'BASE'
}
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('Purchase failed')
transaction_id = purchase_result['transactionId']
# Step 2: Fetch complete 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'],
'qrCodeUrl': esim_data['qrCodeUrl'],
'activationCode': esim_data['ac'],
'packageDetails': esim_data['packageDetails']
}
# Usage
result = purchase_esim('PWZ5FXSJ3')
print(f"eSIM purchased: {result['iccid']}")
print(f"QR Code: {result['qrCodeUrl']}")
<?php
function purchaseEsim($packageCode) {
$apiKey = 'YOUR_API_KEY';
$headers = [
'X-API-Key: ' . $apiKey,
'Content-Type: application/json'
];
// Step 1: Purchase eSIM
$purchaseData = [
'packageCode' => $packageCode,
'paymentMethod' => 'WALLET',
'packageType' => 'BASE'
];
$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('Purchase failed');
}
$transactionId = $purchaseResult['transactionId'];
// Step 2: Fetch complete 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'],
'qrCodeUrl' => $esimData['qrCodeUrl'],
'activationCode' => $esimData['ac'],
'packageDetails' => $esimData['packageDetails']
];
}
// Usage
$result = purchaseEsim('PWZ5FXSJ3');
echo "eSIM purchased: " . $result['iccid'] . "\n";
echo "QR Code: " . $result['qrCodeUrl'];
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type PurchaseRequest struct {
PackageCode string `json:"packageCode"`
PaymentMethod string `json:"paymentMethod"`
PackageType string `json:"packageType"`
}
type PurchaseResponse struct {
TransactionID string `json:"transactionId"`
Status string `json:"status"`
Package struct {
PackageCode string `json:"packageCode"`
Name string `json:"name"`
Price int `json:"price"`
CurrencyCode string `json:"currencyCode"`
} `json:"package"`
}
type EsimDetails struct {
ICCID string `json:"iccid"`
QRCodeURL string `json:"qrCodeUrl"`
AC string `json:"ac"`
TransactionID string `json:"transactionId"`
PackageDetails struct {
Name string `json:"name"`
Code string `json:"code"`
} `json:"packageDetails"`
}
func purchaseEsim(apiKey, packageCode string) (*EsimDetails, error) {
// Step 1: Purchase eSIM
reqBody := PurchaseRequest{
PackageCode: packageCode,
PaymentMethod: "WALLET",
PackageType: "BASE",
}
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 PurchaseResponse
json.Unmarshal(body, &purchaseResult)
if purchaseResult.Status != "SUCCESS" {
return nil, fmt.Errorf("purchase failed")
}
// Step 2: Fetch complete 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 := purchaseEsim("YOUR_API_KEY", "PWZ5FXSJ3")
if err != nil {
fmt.Println("Purchase failed:", err)
return
}
fmt.Printf("eSIM purchased: %s\n", result.ICCID)
fmt.Printf("QR Code: %s\n", result.QRCodeURL)
}
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
packageCode | string | Yes | Package identifier (e.g., “US_5GB_30D”) |
paymentMethod | string | Yes | Must be “WALLET” for API users |
packageType | string | Yes | Must be “BASE” for new eSIM purchase |
Payment Method: API users can only use
WALLET payment. The system automatically checks your balance and deducts the amount instantly.Purchase Response (Step 1)
{
"transactionId": "esim_1762812333247_7046",
"status": "SUCCESS",
"package": {
"packageCode": "PWZ5FXSJ3",
"name": "Qatar 500MB 7Days",
"price": 4800,
"volume": 0,
"duration": 0,
"currencyCode": "NGN"
}
}
The purchase response contains minimal information. Use the
transactionId to fetch complete eSIM details from /api/esim/{transactionId}.Complete eSIM Details (Step 2)
{
"_id": "69125f9f56d7f09edabbaf23",
"packageCode": "PWZ5FXSJ3",
"orderNo": "B25111021560007",
"transactionId": "esim_1762811805580_83",
"esimTranNo": "25111021560007",
"iccid": "8997250230000286674",
"imsi": "260066020045995",
"msisdn": "",
"ac": "LPA:1$rsp-eu.simlessly.com$ABAB05BFAFF44413AA72E3305C80887F",
"qrCodeUrl": "https://p.qrsim.net/674c5892006f4703871581a7bc3b8319.png",
"shortUrl": "https://p.qrsim.net/674c5892006f4703871581a7bc3b8319",
"smdpStatus": "RELEASED",
"eid": "",
"activeType": "2",
"expiredTime": "2026-05-09T21:56:47.000Z",
"totalVolume": 524288000,
"totalDuration": 7,
"durationUnit": "DAY",
"orderUsage": 0,
"data_usage_remain": 524288000,
"validity_usage_remain": 7,
"pin": "3266",
"puk": "58695894",
"apn": "internet",
"esimStatus": "GOT_RESOURCE",
"smsStatus": 2,
"dataType": 1,
"packageDetails": {
"name": "Qatar 500MB 7Days",
"code": "PWZ5FXSJ3",
"volume": 524288000,
"duration": 7,
"location": "QA",
"price": 4800,
"currency": "NGN",
"locationLogo": "https://flagcdn.com/w320/qa.png",
"description": "",
"speed": "3G/4G/5G",
"coverage": [
{
"locationName": "Qatar",
"locationLogo": "https://flagcdn.com/w320/qa.png",
"locationCode": "QA",
"operatorList": [
{
"operatorName": "Vodafone",
"networkType": "4G"
},
{
"operatorName": "ooredoo",
"networkType": "5G"
}
]
}
]
},
"isActive": true,
"createdAt": "2025-11-10T21:56:47.267Z",
"updatedAt": "2025-11-10T21:56:47.726Z",
"user": "69120363ed042b4afb7aca90",
"transactionRef": "69125f9e56d7f09edabbaf1f",
"__v": 0
}
Response Fields
Purchase Response Fields
| Field | Type | Description |
|---|---|---|
transactionId | string | Unique transaction identifier (use this to fetch eSIM details) |
status | string | ”SUCCESS” or “FAILED” |
package.packageCode | string | Package identifier |
package.name | string | Package display name |
package.price | number | Price in smallest currency unit (kobo for NGN) |
package.currencyCode | string | Currency code (e.g., “NGN”) |
eSIM Details Fields
| Field | Type | Description |
|---|---|---|
iccid | string | Integrated Circuit Card ID |
ac | string | Full LPA activation code (for installation) |
qrCodeUrl | string | QR code image URL for easy installation |
shortUrl | string | Short URL to QR code page |
orderNo | string | Order reference number |
esimStatus | string | Current eSIM status |
totalVolume | number | Total data in bytes |
totalDuration | number | Validity period |
durationUnit | string | Time unit (DAY, MONTH, etc.) |
data_usage_remain | number | Remaining data in bytes |
validity_usage_remain | number | Remaining validity days |
expiredTime | string | Expiration date (ISO 8601) |
pin | string | SIM PIN code |
puk | string | SIM PUK code |
apn | string | Access Point Name for data connection |
packageDetails | object | Complete package information with coverage |
Next Steps
Top-Up eSIM
Add more data to existing eSIM
Fetch eSIM Details
Retrieve eSIM information anytime
