eSIMDual Reseller API

Use the eSIMDual reseller API in your own website or app

This documentation covers the production and sandbox APIs: authentication, public packages, purchases, eSIM delivery, usage, compatible recharges, unused-eSIM cancellation, refunds, wallet data and signed webhooks.

Download OpenAPI JSON View Raw JSON

Quick start

1Start safely with POST /sandbox/login
2Send Bearer tokens on all protected endpoints
3Use Idempotency-Key on every purchase, recharge and cancellation
4Switch to production only after reseller approval

Base URL https://esimdual.com/api/reseller/v1

Sandbox URL https://esimdual.com/api/reseller/v1/sandbox

Authentication Authorization: Bearer <token>

Idempotency Idempotency-Key: unique-order-key

Sandbox safety

Sandbox orders use a fictitious balance and simulated eSIMs. They never call an upstream supplier and never debit the production wallet. Use the simulate endpoint to test installed, active and consumed states, then verify accepted, rejected and manual-review refund flows.

curl --request POST 'https://esimdual.com/api/reseller/v1/sandbox/login' \
  --header 'Content-Type: application/json' \
  --data '{"email":"partner@example.com","password":"YOUR_PASSWORD","device_name":"sandbox-ci"}'

Sample login request

curl --request POST 'https://esimdual.com/api/reseller/v1/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "partner@example.com",
    "password": "StrongPassword123!",
    "device_name": "production-server",
    "expires_in_days": 90
  }'

Sample order request

curl --request POST 'https://esimdual.com/api/reseller/v1/orders' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Idempotency-Key: ORDER-2026-0001' \
  --header 'Content-Type: application/json' \
  --data '{
    "package_id": 1120,
    "external_order_id": "NOANET-2026-0001",
    "device_imei": "356938035643809"
  }'

Compatible recharge flow

GET /esims/{id}/topup-options

POST /topups
Idempotency-Key: TOPUP-2026-0001
{
  "esim_id": "{id}",
  "package_id": 456
}

Unused eSIM cancellation

POST /esims/{id}/cancel
Idempotency-Key: CANCEL-2026-0001

Automatic refund only when the supplier confirms:
- zero usage
- never installed
- never activated
- no completed recharge exists
- original wallet debit is verified

Webhook events

eSIMDual signs timestamp.raw_payload with HMAC SHA-256. The secret is generated by eSIMDual and displayed only after creation or rotation. Reject timestamps older than five minutes and deduplicate X-eSIMDual-Delivery.

ping order.completed order.processing order.failed topup.completed topup.processing topup.failed esim.cancelled refund.completed refund.failed

X-eSIMDual-Event

X-eSIMDual-Delivery

X-eSIMDual-Timestamp

X-eSIMDual-Signature: v1=…

PHP signature verification

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_ESIMDUAL_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_ESIMDUAL_SIGNATURE'] ?? '';
$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $webhookSecret);

if (!$fresh || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid or stale signature');
}

Store each X-eSIMDual-Delivery value and reject duplicate deliveries. Return an HTTP 2xx response only after the event has been accepted.