E-sim Reseller API

Base URL: https://web.sprintpay.online/api

Sell global E-sim data and phone plans on your website. Call SprintPay from your backend — your merchant wallet is debited in NGN and orders are fulfilled automatically.

1. Overview

You integrate only with SprintPay. Do not expose upstream credentials on your site.

2. Authentication

Every request requires both credentials:

POST /api/merchant/vas/esim/orders HTTP/1.1
Host: web.sprintpay.online
Content-Type: application/json
X-Api-Key: your_webkey_here
Authorization: Bearer your_webhook_secret_here

3. Integration flow

1. List packages       → GET  /api/merchant/vas/esim/packages
2. Quote price         → POST /api/merchant/vas/esim/quote
3. Create order        → POST /api/merchant/vas/esim/orders
4. Poll order status   → GET  /api/merchant/vas/esim/orders/{externalOrderId}
5. Deliver QR / code   → when status = completed
6. Check usage         → GET  /api/merchant/vas/esim/esims/{iccid}/usage
7. Top up (optional)   → GET topup-options, then POST topup

Orders are asynchronous. After POST /orders, status is usually processing until the eSIM is provisioned. Poll until completed or failed.

4. Endpoints

Base path: /api/merchant/vas/esim

Catalogue

GET /packages

List available E-sim packages with vendor prices.

{
  "status": true,
  "data": {
    "packages": [
      {
        "packageCode": "JP_7D_1GB",
        "name": "Japan 7 Days 1GB",
        "locationCode": "JP",
        "planType": "data",
        "volumeGB": 1,
        "validityDays": 7,
        "retailUsdCents": 500,
        "retailUsdFormatted": "$5.00",
        "chargeNgn": 7500,
        "marginPercent": 15,
        "supportTopUp": true
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 120, "pages": 3 }
  }
}

GET /packages/{packageCode}

Single package details (same price fields as list).

POST /quote

Preview price and wallet balance before purchase.

{
  "key": "your_webkey",
  "packageCode": "JP_7D_1GB"
}

Orders

POST /orders

Create an eSIM order. Wallet is debited immediately; provisioning may take a few seconds.

{
  "key": "your_webkey",
  "packageCode": "JP_7D_1GB",
  "externalOrderId": "YOUR-UNIQUE-REF-123",
  "email": "customer@example.com"
}

Success (201)

{
  "status": true,
  "message": "E-sim order created. QR details will be available when provisioning completes.",
  "data": {
    "externalOrderId": "YOUR-UNIQUE-REF-123",
    "orderId": "upstream-order-id",
    "status": "processing",
    "packageCode": "JP_7D_1GB",
    "chargeNgn": 7500,
    "retailUsdFormatted": "$5.00"
  }
}

GET /orders

List your orders. Query: status, page, limit.

GET /orders/{orderRef}

Get one order by externalOrderId or upstream orderId.

{
  "status": true,
  "data": {
    "externalOrderId": "YOUR-UNIQUE-REF-123",
    "status": "completed",
    "iccid": "8901234567890123456",
    "qrCodeUrl": "https://...",
    "activationCode": "LPA:1$...",
    "supportTopUp": true,
    "canTopUp": true
  }
}

eSIM management

GET /esims/{iccid}

Live eSIM details (must belong to your webkey). Includes supportTopUp and canTopUp when the original package supports top-ups.

GET /esims/{iccid}/usage

Data usage statistics.

GET /esims/{iccid}/topup-options

List valid top-up packages for an existing eSIM. Always call this before topping up.

{
  "status": true,
  "data": {
    "iccid": "8901234567890123456",
    "canTopUp": true,
    "topupPackages": [
      {
        "packageCode": "CKH205",
        "name": "Bulgaria 1GB 7Days",
        "volumeGB": 1,
        "duration": 7,
        "price": 203,
        "priceFormatted": "$2.03",
        "retailUsdCents": 233,
        "retailUsdFormatted": "$2.33",
        "chargeNgn": 3495
      }
    ]
  }
}

POST /esims/{iccid}/topup

Add a top-up to an existing eSIM. Use a packageCode from topup-options only.

{
  "key": "your_webkey",
  "packageCode": "TOPUP_CODE_FROM_OPTIONS",
  "externalOrderId": "YOUR-TOPUP-REF-456"
}

Phone plans: topping up extends validity and keeps the same phone number.

5. Top-up eligibility

Recommended flow: check supportTopUp when listing packages → after purchase, call GET /topup-options to confirm canTopUp and get valid packageCode values → POST /topup.

6. Pricing

You may mark up further when selling to your own customers.

7. Order statuses

8. Phone plans

• Filter catalogue with ?type=phone.
• Real phone number is assigned after the end user activates the eSIM on device.
• Do not show placeholder msisdn until status is active.

9. Error responses

{
  "status": false,
  "message": "Insufficient wallet balance.",
  "balance": 1200,
  "required": 7500
}

10. Code examples

List packages (Japan)

curl -s "https://web.sprintpay.online/api/merchant/vas/esim/packages?country=JP&limit=10" \
  -H "X-Api-Key: YOUR_WEBKEY" \
  -H "Authorization: Bearer YOUR_WEBHOOK_SECRET"

Create order

curl -s -X POST "https://web.sprintpay.online/api/merchant/vas/esim/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_WEBKEY" \
  -H "Authorization: Bearer YOUR_WEBHOOK_SECRET" \
  -d '{
    "packageCode": "JP_7D_1GB",
    "externalOrderId": "SHOP-ORDER-99001",
    "email": "buyer@example.com"
  }'

Check order

curl -s "https://web.sprintpay.online/api/merchant/vas/esim/orders/SHOP-ORDER-99001" \
  -H "X-Api-Key: YOUR_WEBKEY" \
  -H "Authorization: Bearer YOUR_WEBHOOK_SECRET"

Check top-up options

curl -s "https://web.sprintpay.online/api/merchant/vas/esim/esims/8901234567890123456/topup-options" \
  -H "X-Api-Key: YOUR_WEBKEY" \
  -H "Authorization: Bearer YOUR_WEBHOOK_SECRET"

Top up an eSIM

curl -s -X POST "https://web.sprintpay.online/api/merchant/vas/esim/esims/8901234567890123456/topup" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_WEBKEY" \
  -H "Authorization: Bearer YOUR_WEBHOOK_SECRET" \
  -d '{
    "packageCode": "CKH205",
    "externalOrderId": "SHOP-TOPUP-99002"
  }'

11. Related docs

• VTU / bills API — airtime, data, cable, electricity
• Collection API — payment collection