Skip to main content
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>"
}
'
{
  "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"
  }
}

​
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

​
X-API-Key
string
required
API Key for authentication
YOUR_API_KEY

​
Request Body

​
packageCode
string
required
Package code to purchase (e.g., “US_5GB_30D”)Get available package codes from /api/esim/packages
​
paymentMethod
string
required
Payment method to use:
  • WALLET - Pay with wallet balance
  • CARD - Pay with credit/debit card (Paystack)
  • BANK_TRANSFER - Pay via bank transfer
  • MOBILE_MONEY - Pay with mobile money
  • APPLE_PAY - Pay with Apple Pay
​
packageType
string
required
Type of purchase:
  • BASE - New eSIM purchase
  • TOPUP - Top-up existing eSIM
​
esimId
string
Existing eSIM ID to top up (required when packageType is TOPUP)

​
Response

​
transactionId
string
Unique transaction ID for this purchase
​
status
string
Order status: SUCCESS, PENDING, PROCESSING
​
package
object
Package details including price and data allowance
​
paymentUrl
string
Payment URL for card/online payments (if payment method requires it)
​
bankAccounts
array
Bank account details for bank transfer payments
​
esimDetails
object
eSIM details (only when payment method is WALLET and eSIM is created immediately)

​
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"
  }'

​
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"
  }
}

​
Payment Methods

MethodProcessing TimeNotes
WALLETInstanteSIM created immediately
CARD1-5 minutesRedirects to payment gateway
BANK_TRANSFER10-30 minutesManual verification required
MOBILE_MONEY2-10 minutesCountry-specific
APPLE_PAYInstantiOS devices only

​
Payment Flow

1

Initiate Purchase

Call the /api/esim/buy endpoint with package details
2

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 webhook
5

Retrieve eSIM

eSIM details delivered via webhook or retrieve using /api/esim/:esimId

​
Error Handling

Code: INSUFFICIENT_BALANCESolution: Check wallet balance before purchase or prompt user to fund wallet
const balance = await getWalletBalance();
if (balance < packagePrice) {
  // Redirect to fund wallet page
  redirectToFundWallet();
} else {
  await purchaseEsim(packageCode);
}
Code: PACKAGE_NOT_FOUND or PACKAGE_UNAVAILABLESolution: Refresh package list or show alternative packages
Code: PAYMENT_FAILEDSolution: Retry payment or try different payment method
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"
}
Learn more about webhooks setup.

​
Next Steps

Confirm Payment

Confirm pending payments

Get My eSIMs

View purchased eSIMs

Webhooks

Set up payment notifications

Error Handling

Handle purchase errors