Purchase eSIM
curl --request POST \
--url https://api.vellosim.com/api/esim/buy \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"packageCode": "<string>",
"paymentMethod": "<string>",
"packageType": "<string>",
"esimId": "<string>"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
packageCode: '<string>',
paymentMethod: '<string>',
packageType: '<string>',
esimId: '<string>'
})
};
fetch('https://api.vellosim.com/api/esim/buy', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.vellosim.com/api/esim/buy"
payload = {
"packageCode": "<string>",
"paymentMethod": "<string>",
"packageType": "<string>",
"esimId": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vellosim.com/api/esim/buy",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'packageCode' => '<string>',
'paymentMethod' => '<string>',
'packageType' => '<string>',
'esimId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vellosim.com/api/esim/buy"
payload := strings.NewReader("{\n \"packageCode\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"packageType\": \"<string>\",\n \"esimId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"transactionId": "esim_1699564800_12345",
"status": "SUCCESS",
"package": {
"packageCode": "US_5GB_30D",
"packageName": "USA 5GB - 30 Days",
"price": 8000,
"currency": "NGN"
},
"esimDetails": {
"esimId": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
"iccid": "8944500123456789012",
"qrCodeUrl": "https://vellosim.com/qr/abc123",
"activationCode": "LPA:1$smdp.address$matchingId",
"smdpAddress": "smdp.gsma.com",
"matchingId": "ABC-123-DEF-456"
}
}
{
"transactionId": "esim_1699564800_12346",
"status": "PENDING",
"package": {
"packageCode": "EU_10GB_15D",
"packageName": "Europe 10GB - 15 Days",
"price": 12000,
"currency": "NGN"
},
"paymentUrl": "https://checkout.paystack.com/xyz789",
"paystackReference": "xyz789abc"
}
{
"transactionId": "esim_1699564800_12347",
"status": "PENDING",
"package": {
"packageCode": "ASIA_20GB_30D",
"packageName": "Asia 20GB - 30 Days",
"price": 20000,
"currency": "NGN"
},
"bankAccounts": [
{
"bankName": "First Bank of Nigeria",
"accountNumber": "1234567890",
"accountName": "Vellosim Technologies",
"expiryDate": "2024-11-15T10:30:00Z"
}
],
"trackingReference": "VLS-BANK-12347"
}
{
"success": false,
"message": "Insufficient wallet balance",
"error": {
"code": "INSUFFICIENT_BALANCE",
"details": "Your wallet balance is NGN 5,000 but package costs NGN 8,000. Please fund your wallet."
}
}
{
"success": false,
"message": "Package not found",
"error": {
"code": "PACKAGE_NOT_FOUND",
"details": "The specified package code does not exist"
}
}
Purchase
Purchase eSIM
Purchase an eSIM package with wallet or card payment
POST
/
api
/
esim
/
buy
Purchase eSIM
curl --request POST \
--url https://api.vellosim.com/api/esim/buy \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"packageCode": "<string>",
"paymentMethod": "<string>",
"packageType": "<string>",
"esimId": "<string>"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
packageCode: '<string>',
paymentMethod: '<string>',
packageType: '<string>',
esimId: '<string>'
})
};
fetch('https://api.vellosim.com/api/esim/buy', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.vellosim.com/api/esim/buy"
payload = {
"packageCode": "<string>",
"paymentMethod": "<string>",
"packageType": "<string>",
"esimId": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vellosim.com/api/esim/buy",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'packageCode' => '<string>',
'paymentMethod' => '<string>',
'packageType' => '<string>',
'esimId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vellosim.com/api/esim/buy"
payload := strings.NewReader("{\n \"packageCode\": \"<string>\",\n \"paymentMethod\": \"<string>\",\n \"packageType\": \"<string>\",\n \"esimId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"transactionId": "esim_1699564800_12345",
"status": "SUCCESS",
"package": {
"packageCode": "US_5GB_30D",
"packageName": "USA 5GB - 30 Days",
"price": 8000,
"currency": "NGN"
},
"esimDetails": {
"esimId": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
"iccid": "8944500123456789012",
"qrCodeUrl": "https://vellosim.com/qr/abc123",
"activationCode": "LPA:1$smdp.address$matchingId",
"smdpAddress": "smdp.gsma.com",
"matchingId": "ABC-123-DEF-456"
}
}
{
"transactionId": "esim_1699564800_12346",
"status": "PENDING",
"package": {
"packageCode": "EU_10GB_15D",
"packageName": "Europe 10GB - 15 Days",
"price": 12000,
"currency": "NGN"
},
"paymentUrl": "https://checkout.paystack.com/xyz789",
"paystackReference": "xyz789abc"
}
{
"transactionId": "esim_1699564800_12347",
"status": "PENDING",
"package": {
"packageCode": "ASIA_20GB_30D",
"packageName": "Asia 20GB - 30 Days",
"price": 20000,
"currency": "NGN"
},
"bankAccounts": [
{
"bankName": "First Bank of Nigeria",
"accountNumber": "1234567890",
"accountName": "Vellosim Technologies",
"expiryDate": "2024-11-15T10:30:00Z"
}
],
"trackingReference": "VLS-BANK-12347"
}
{
"success": false,
"message": "Insufficient wallet balance",
"error": {
"code": "INSUFFICIENT_BALANCE",
"details": "Your wallet balance is NGN 5,000 but package costs NGN 8,000. Please fund your wallet."
}
}
{
"success": false,
"message": "Package not found",
"error": {
"code": "PACKAGE_NOT_FOUND",
"details": "The specified package code does not exist"
}
}
Endpoint
POST /api/esim/buy
Description
Purchase an eSIM package using your wallet balance or card payment. This endpoint creates an order and returns payment information if needed.Authentication
string
required
API Key for authentication
YOUR_API_KEY
Request Body
string
required
Package code to purchase (e.g., “US_5GB_30D”)Get available package codes from
/api/esim/packagesstring
required
Payment method to use:
WALLET- Pay with wallet balanceCARD- Pay with credit/debit card (Paystack)BANK_TRANSFER- Pay via bank transferMOBILE_MONEY- Pay with mobile moneyAPPLE_PAY- Pay with Apple Pay
string
required
Type of purchase:
BASE- New eSIM purchaseTOPUP- Top-up existing eSIM
string
Existing eSIM ID to top up (required when packageType is
TOPUP)Response
string
Unique transaction ID for this purchase
string
Order status:
SUCCESS, PENDING, PROCESSINGobject
Package details including price and data allowance
string
Payment URL for card/online payments (if payment method requires it)
array
Bank account details for bank transfer payments
object
Example Request
# Purchase with wallet
curl -X POST https://api.vellosim.com/api/esim/buy \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"packageCode": "US_5GB_30D",
"paymentMethod": "WALLET",
"packageType": "BASE"
}'
# Purchase with card
curl -X POST https://api.vellosim.com/api/esim/buy \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"packageCode": "EU_10GB_15D",
"paymentMethod": "CARD",
"packageType": "BASE"
}'
# Top-up existing eSIM
curl -X POST https://api.vellosim.com/api/esim/buy \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"packageCode": "US_5GB_30D",
"paymentMethod": "WALLET",
"packageType": "TOPUP",
"esimId": "esim_64f8a1b2c3d4e5f6a7b8c9d0"
}'
// Purchase with wallet
async function purchaseEsim(packageCode) {
const response = await fetch('https://api.vellosim.com/api/esim/buy', {
method: 'POST',
headers: {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageCode: packageCode,
paymentMethod: 'WALLET',
packageType: 'BASE'
})
});
const data = await response.json();
if (data.status === 'SUCCESS') {
console.log('eSIM purchased successfully!');
console.log('ICCID:', data.esimDetails.iccid);
console.log('QR Code:', data.esimDetails.qrCodeUrl);
}
return data;
}
// Purchase with card
async function purchaseWithCard(packageCode) {
const response = await fetch('https://api.vellosim.com/api/esim/buy', {
method: 'POST',
headers: {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageCode: packageCode,
paymentMethod: 'CARD',
packageType: 'BASE'
})
});
const data = await response.json();
if (data.status === 'PENDING' && data.paymentUrl) {
// Redirect user to payment page
window.location.href = data.paymentUrl;
}
return data;
}
// Top-up existing eSIM
async function topUpEsim(esimId, packageCode) {
const response = await fetch('https://api.vellosim.com/api/esim/buy', {
method: 'POST',
headers: {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageCode: packageCode,
paymentMethod: 'WALLET',
packageType: 'TOPUP',
esimId: esimId
})
});
return await response.json();
}
import requests
def purchase_esim(package_code, payment_method='WALLET'):
"""Purchase an eSIM package"""
headers = {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
}
payload = {
'packageCode': package_code,
'paymentMethod': payment_method,
'packageType': 'BASE'
}
response = requests.post(
'https://api.vellosim.com/api/esim/buy',
headers=headers,
json=payload
)
data = response.json()
if data['status'] == 'SUCCESS':
print(f"eSIM purchased successfully!")
print(f"Transaction ID: {data['transactionId']}")
if 'esimDetails' in data:
print(f"ICCID: {data['esimDetails']['iccid']}")
print(f"QR Code: {data['esimDetails']['qrCodeUrl']}")
elif data['status'] == 'PENDING':
print(f"Payment pending. Payment URL: {data.get('paymentUrl')}")
return data
# Usage
result = purchase_esim('US_5GB_30D', 'WALLET')
# Top-up example
def topup_esim(esim_id, package_code):
"""Top-up an existing eSIM"""
headers = {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
}
payload = {
'packageCode': package_code,
'paymentMethod': 'WALLET',
'packageType': 'TOPUP',
'esimId': esim_id
}
response = requests.post(
'https://api.vellosim.com/api/esim/buy',
headers=headers,
json=payload
)
return response.json()
<?php
function purchaseEsim($packageCode, $paymentMethod = 'WALLET') {
$apiKey = 'YOUR_API_KEY';
$data = [
'packageCode' => $packageCode,
'paymentMethod' => $paymentMethod,
'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($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Key: ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);
if ($result['status'] === 'SUCCESS') {
echo "eSIM purchased successfully!\n";
echo "Transaction ID: " . $result['transactionId'] . "\n";
if (isset($result['esimDetails'])) {
echo "ICCID: " . $result['esimDetails']['iccid'] . "\n";
echo "QR Code: " . $result['esimDetails']['qrCodeUrl'] . "\n";
}
} elseif ($result['status'] === 'PENDING') {
echo "Payment pending. Redirect to: " . $result['paymentUrl'] . "\n";
}
return $result;
}
// Usage
$result = purchaseEsim('US_5GB_30D', 'WALLET');
?>
Example Response
{
"transactionId": "esim_1699564800_12345",
"status": "SUCCESS",
"package": {
"packageCode": "US_5GB_30D",
"packageName": "USA 5GB - 30 Days",
"price": 8000,
"currency": "NGN"
},
"esimDetails": {
"esimId": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
"iccid": "8944500123456789012",
"qrCodeUrl": "https://vellosim.com/qr/abc123",
"activationCode": "LPA:1$smdp.address$matchingId",
"smdpAddress": "smdp.gsma.com",
"matchingId": "ABC-123-DEF-456"
}
}
{
"transactionId": "esim_1699564800_12346",
"status": "PENDING",
"package": {
"packageCode": "EU_10GB_15D",
"packageName": "Europe 10GB - 15 Days",
"price": 12000,
"currency": "NGN"
},
"paymentUrl": "https://checkout.paystack.com/xyz789",
"paystackReference": "xyz789abc"
}
{
"transactionId": "esim_1699564800_12347",
"status": "PENDING",
"package": {
"packageCode": "ASIA_20GB_30D",
"packageName": "Asia 20GB - 30 Days",
"price": 20000,
"currency": "NGN"
},
"bankAccounts": [
{
"bankName": "First Bank of Nigeria",
"accountNumber": "1234567890",
"accountName": "Vellosim Technologies",
"expiryDate": "2024-11-15T10:30:00Z"
}
],
"trackingReference": "VLS-BANK-12347"
}
{
"success": false,
"message": "Insufficient wallet balance",
"error": {
"code": "INSUFFICIENT_BALANCE",
"details": "Your wallet balance is NGN 5,000 but package costs NGN 8,000. Please fund your wallet."
}
}
{
"success": false,
"message": "Package not found",
"error": {
"code": "PACKAGE_NOT_FOUND",
"details": "The specified package code does not exist"
}
}
Payment Methods
| Method | Processing Time | Notes |
|---|---|---|
| WALLET | Instant | eSIM created immediately |
| CARD | 1-5 minutes | Redirects to payment gateway |
| BANK_TRANSFER | 10-30 minutes | Manual verification required |
| MOBILE_MONEY | 2-10 minutes | Country-specific |
| APPLE_PAY | Instant | iOS devices only |
Payment Flow
1
Initiate Purchase
Call the
/api/esim/buy endpoint with package details2
Handle Response
- SUCCESS: eSIM created (wallet payment)
- PENDING: Payment required (card/bank transfer)
3
Complete Payment
For pending payments:
- Card: Redirect to
paymentUrl - Bank Transfer: Show bank account details
4
Confirm Payment
Call
/api/esim/confirm-payment or wait for webhook5
Retrieve eSIM
eSIM details delivered via webhook or retrieve using
/api/esim/:esimIdError Handling
Insufficient Balance
Insufficient Balance
Code:
INSUFFICIENT_BALANCESolution: Check wallet balance before purchase or prompt user to fund walletconst balance = await getWalletBalance();
if (balance < packagePrice) {
// Redirect to fund wallet page
redirectToFundWallet();
} else {
await purchaseEsim(packageCode);
}
Package Not Available
Package Not Available
Code:
PACKAGE_NOT_FOUND or PACKAGE_UNAVAILABLESolution: Refresh package list or show alternative packagesPayment Failed
Payment Failed
Code:
PAYMENT_FAILEDSolution: Retry payment or try different payment methodTop-Up Validation
Top-Up Validation
Code:
INVALID_TOPUPSolution: Verify eSIM ID and package compatibility// Check if eSIM supports top-up
const esim = await getEsimById(esimId);
if (!esim.topUpAvailable) {
console.error('This eSIM does not support top-up');
}
Webhooks
Set up a webhook to receive real-time notifications about purchase status:{
"event": "esim.purchased",
"data": {
"transactionId": "esim_1699564800_12345",
"status": "SUCCESS",
"esimId": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
"iccid": "8944500123456789012",
"qrCodeUrl": "https://vellosim.com/qr/abc123"
},
"timestamp": "2024-11-10T10:30:00Z"
}
Next Steps
Confirm Payment
Confirm pending payments
Get My eSIMs
View purchased eSIMs
Webhooks
Set up payment notifications
Error Handling
Handle purchase errors
⌘I
