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);
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
