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 packageCodestring Yes Package identifier (e.g., “US_5GB_30D”) paymentMethodstring Yes Must be “WALLET” for API users packageTypestring 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 transactionIdstring Unique transaction identifier (use this to fetch eSIM details) statusstring ”SUCCESS” or “FAILED” package.packageCodestring Package identifier package.namestring Package display name package.pricenumber Price in smallest currency unit (kobo for NGN) package.currencyCodestring Currency code (e.g., “NGN”)
eSIM Details Fields Field Type Description iccidstring Integrated Circuit Card ID acstring Full LPA activation code (for installation) qrCodeUrlstring QR code image URL for easy installation shortUrlstring Short URL to QR code page orderNostring Order reference number esimStatusstring Current eSIM status totalVolumenumber Total data in bytes totalDurationnumber Validity period durationUnitstring Time unit (DAY, MONTH, etc.) data_usage_remainnumber Remaining data in bytes validity_usage_remainnumber Remaining validity days expiredTimestring Expiration date (ISO 8601) pinstring SIM PIN code pukstring SIM PUK code apnstring Access Point Name for data connection packageDetailsobject Complete package information with coverage
Next Steps
Top-Up eSIM Add more data to existing eSIM
Fetch eSIM Details Retrieve eSIM information anytime
