Skip to main content
POST
Purchase eSIM

Endpoint

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

Request Body

string
required
Package code to purchase (e.g., “US_5GB_30D”)Get available package codes from /api/esim/packages
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
string
required
Type of purchase:
  • BASE - New eSIM purchase
  • TOPUP - 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, PROCESSING
object
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
eSIM details (only when payment method is WALLET and eSIM is created immediately)

Example Request

Example Response

Payment Methods

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

Webhooks

Set up a webhook to receive real-time notifications about purchase status:
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