Partner Reseller API

POST /api/v1/partner/auth/token
Content-Type: application/json

{
  "api_key": "esim_live_1a2b3c4d5e6f7g8h..."
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

• Tokens are valid for 1 hour. There is no refresh token — when a token expires, call this endpoint again with your API key to get a new one (standard OAuth2 Client Credentials style flow).
• 401 if the key is invalid, malformed, or has been revoked.
• Rate limited to 10 requests/minute per IP.

Lists all active destination countries. Optional query param search filters by name or ISO2 code.

[
  {
    "id": 1,
    "iso2": "US",
    "iso3": "USA",
    "name_en": "United States",
    "name_bn": null,
    "flag_url": "https://...",
    "region": null,
    "is_popular": true,
    "is_active": true
  }
]

Rate limit: 120/minute.

Lists active eSIM data products for a country. iso2 is case-insensitive.

[
  {
    "id": "a1b2c3d4-...",
    "country_id": 1,
    "title_en": "1GB / 7 Days",
    "title_bn": null,
    "data_amount_gb": 1.0,
    "validity_days": 7,
    "retail_price": 4.50,
    "currency": "EUR",
    "is_unlimited": false,
    "is_active": true,
    "coverage_networks": null
  }
]

404 if the country ISO2 doesn't exist. Rate limit: 120/minute.

Your merchant profile, effective commission rate, and current wallet balance.

{
  "business_name": "Acme Travel Co",
  "commission_rate_pct": 5.00,
  "wallet_balance": 142.5000,
  "wallet_currency": "EUR",
  "commission_balance": 3.2500,
  "webhook_configured": true
}

wallet_balance is the prepaid balance orders are paid from — check it before charging your own customer. commission_balance is commission earned on completed orders, held separately.

Reflects any active volume-based commission tier, falling back to your flat rate. Rate limit: 120/minute.

Places an order and provisions an eSIM asynchronously. Your merchant wallet is debited the product's retail_price immediately; the order returns in PROCESSING status right away — poll GET /orders/{id} or wait for the webhook (§3) to find out whether it completed.

{
  "product_id": "a1b2c3d4-...",
  "customer_reference": "your-internal-order-id-123"
}

The response is the full order object (see GET /orders/{order_id} below) plus idempotent_replay.

Always send customer_reference — it makes retries safe

• The same customer_reference with the same product_id returns the original order ("idempotent_replay": true) and never charges your wallet again.
• The same customer_reference with a different product_id returns 409.
• Without one, every call is a new purchase — a retried timeout can buy two eSIMs. Use one unique value per eSIM you sell, e.g. your own order ID.

What happens after PROCESSING (usually 10–30 seconds):

• Success — order becomes COMPLETED, the eSIM fields and install links are filled in, and commission is credited to your account.
• Failure — order becomes FAILED, no eSIM is issued, and the full amount is refunded to your wallet automatically. No commission is paid on a failed order.
• If our server restarts mid-order, a recovery job still settles it within minutes — a PROCESSING order always ends as COMPLETED or FAILED.

400 insufficient wallet balance (nothing charged) · 404 product not found/inactive · 409 customer_reference reused for another product · rate limit 30/minute.

The current state of one of your orders. Poll every 3–5 seconds while PROCESSING. The webhook sends this same object.

{
  "order_id": "e5f6a7b8-...",
  "order_no": "PTR-20260913-A1B2C3",
  "customer_reference": "your-order-id-123",
  "status": "COMPLETED",
  "amount": "4.5000",
  "currency": "EUR",
  "product": {
    "id": "a1b2c3d4-...",
    "title": "Singapore 1GB 7 Days",
    "country_iso2": "SG",
    "data_amount_gb": 1.0,
    "is_unlimited": false,
    "validity_days": 7
  },
  "iccid": "8965012345678901234",
  "lpa_string": "LPA:1$smdp.example.com$ABC123",
  "qr_code_data": "LPA:1$smdp.example.com$ABC123",
  "smdp_address": "smdp.example.com",
  "matching_id": "ABC123",
  "install_links": {
    "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24...",
    "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA%3A1%24..."
  },
  "is_mock_fallback": false,
  "created_at": "2026-09-13T10:00:00+00:00",
  "updated_at": "2026-09-13T10:00:14+00:00"
}

• Encode qr_code_data into the QR code your customer scans; show smdp_address and matching_id for manual entry.
• install_links.ios works on iOS 17.4+; Android support is still uneven — always show the QR code too.
• For unlimited plans is_unlimited is true and data_amount_gb is 0.
• Fields are only ever added, never removed or renamed — ignore ones you don't recognise. is_mock_fallback is legacy and always false.

404 if the order doesn't exist or isn't yours. Rate limit: 120/minute.

Orders you placed through this API, newest first — for reconciliation. Query params: customer_reference, status (PROCESSING, COMPLETED, FAILED), limit (1–100, default 50), offset.

{
  "orders": [ { "order_id": "e5f6a7b8-...", "status": "COMPLETED", "...": "..." } ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Rate limit: 120/minute.

Sets, rotates, or clears your webhook endpoint. Self-service — no admin involvement needed.

{ "webhook_url": "https://yourapp.example.com/webhooks/esim" }

{
  "webhook_url": "https://yourapp.example.com/webhooks/esim",
  "webhook_secret": "whsec_...",
  "warning": "Store this secret securely - it will not be shown again in full."
}

A new webhook_secret is generated every time you set or change the URL — save it immediately, it verifies webhook signatures (§3) and is never shown again.

Send {"webhook_url": null} to clear your webhook entirely (you'll only be able to poll after that):

{ "webhook_url": null, "webhook_secret": null }

Rate limit: 10/minute.