Skip to main content
POST
Purchase eSIM
Part of VAS. Discover destinations and packages with List billers first, then call this endpoint.
1

Pick a destination

GET /api/v1/merchant/vas/billers?category=esim → choose a locationCode (e.g. NG).
2

Pick a package

GET /api/v1/merchant/vas/billers?category=esim&locationCode=NG → copy packages[].id (UUID).
3

Purchase

POST /api/v1/merchant/vas/esim with that UUID as packageId, customer fields, deviceType, and an Idempotency-Key.
packageCode values like P0Q24KI1C are not valid packageIds and will fail. Always use the UUID id from the billers response.
Pricing: the package price from List billers is in USD. Your NGN wallet is debited the equivalent at the current rate — details.amount in the response is the NGN amount charged.
Sample below uses the cheapest Nigeria package from the live catalog (Nigeria 100MB 7Days, price 0.7755 USD).

Authorizations

X-Api-Key
string
header
required

API key id (sp_test_… / sp_live_…)

Headers

X-Timestamp
string
required

Unix time in seconds

X-Signature
string
required

HMAC-SHA256 signature

Idempotency-Key
string<uuid>
required

UUID. Required on money-moving writes.

Body

application/json
packageId
string<uuid>
required

UUID from List billers → data.esim.packages[].id (e.g. after category=esim&locationCode=NG). Not packageCode.

customerName
string
required
customerPhone
string
required
customerEmail
string
required
deviceType
enum<string>
required

Device that will install the eSIM profile

Available options:
SMARTPHONE,
TABLET,
LAPTOP,
WATCH

Response

OK

The response is of type object.