Seyyah Reseller API

Integrate eSIM purchasing and management directly into your platform. Offer global data connectivity to your customers through a simple, reliable REST API.

Authentication

All API requests must include your API key as a query parameter. Keep your API key confidential and never expose it in client-side code.

curl "https://your-subdomain.seyyahmobile.com/api/plans?api_key=YOUR_API_KEY"

Base URL

All endpoints are relative to your assigned subdomain:

https://{your-subdomain}.seyyahmobile.com/api

Replace {your-subdomain} with your assigned subdomain slug.

List Available Plans

Retrieve all available eSIM plans grouped by country/region, with your reseller-specific pricing.

Response

{
  "success": true,
  "data": [
    {
      "category_id": 45,
      "category_name": {
        "en": "Turkey",
        "tr": "Türkiye"
      },
      "iso2": "TR",
      "plans": [
        {
          "plan_id": 120,
          "name": "Turkey 5GB - 30 Days",
          "data_gb": 5,
          "validity_days": 30,
          "price": 8.50,
          "supports_topup": true,
          "code": "TR-5GB-30D"
        },
        {
          "plan_id": 121,
          "name": "Turkey 10GB - 30 Days",
          "data_gb": 10,
          "validity_days": 30,
          "price": 14.00,
          "supports_topup": true,
          "code": "TR-10GB-30D"
        }
      ]
    }
  ]
}

Plan Object

Create Order

Create a new eSIM purchase or top-up. The order amount is deducted from your wallet balance. eSIM provisioning occurs asynchronously — you'll receive the result via your webhook URL.

Request Body

Example: New Purchase

curl -X POST "https://your-subdomain.seyyahmobile.com/api/orders?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 120,
    "type": "purchase",
    "customer_email": "[email protected]",
    "customer_name": "John Doe",
    "webhook_url": "https://yoursite.com/webhooks/esim",
    "idempotency_key": "order-2026-02-26-abc123"
  }'

Example: Top-Up

curl -X POST "https://your-subdomain.seyyahmobile.com/api/orders?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 121,
    "type": "topup",
    "customer_email": "[email protected]",
    "webhook_url": "https://yoursite.com/webhooks/esim",
    "idempotency_key": "topup-2026-02-26-xyz789",
    "iccid": "8901234567890123456"
  }'

Success Response

{
  "success": true,
  "data": {
    "id": 5432,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "type": "purchase",
    "plan_name": "Turkey 5GB - 30 Days",
    "data_gb": 5,
    "validity_days": 30,
    "amount": 8.50,
    "currency": "USD",
    "created_at": "2026-02-26T10:30:00+00:00",
    "completed_at": null,
    "failed_at": null,
    "failure_reason": null,
    "status": "processing",
    "esim": null
  },
  "wallet_balance": 491.50
}

Get Order Status

Retrieve the current status and details of an existing order. You can look up orders by ID, UUID, or your idempotency key.

The {order} can be any of:

Completed Order Response

{
  "success": true,
  "data": {
    "id": 5432,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "type": "purchase",
    "plan_name": "Turkey 5GB - 30 Days",
    "data_gb": 5,
    "validity_days": 30,
    "amount": 8.50,
    "currency": "USD",
    "created_at": "2026-02-26T10:30:00+00:00",
    "completed_at": "2026-02-26T10:30:45+00:00",
    "failed_at": null,
    "failure_reason": null,
    "status": "completed",
    "esim": {
      "iccid": "8901234567890123456",
      "lpa": "LPA:1$rsp.example.com$ABCD-EFGH-1234",
      "smdp_address": "rsp.example.com",
      "matching_id": "ABCD-EFGH-1234",
      "qrcode_url": "https://cdn.seyyahmobile.com/qrcodes/reseller_5432.png"
    }
  }
}

eSIM Object

Webhooks

When an order is completed or fails, Seyyah sends a POST request to your webhook_url with the order details.

Webhook Events

Webhook Payload

{
  "event": "order.completed",
  "status": "completed",
  "data": {
    "id": 5432,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "type": "purchase",
    "plan_name": "Turkey 5GB - 30 Days",
    "data_gb": 5,
    "validity_days": 30,
    "amount": 8.50,
    "currency": "USD",
    "created_at": "2026-02-26T10:30:00+00:00",
    "completed_at": "2026-02-26T10:30:45+00:00",
    "status": "completed",
    "esim": {
      "iccid": "8901234567890123456",
      "lpa": "LPA:1$rsp.example.com$ABCD-EFGH-1234",
      "smdp_address": "rsp.example.com",
      "matching_id": "ABCD-EFGH-1234",
      "qrcode_url": "https://cdn.seyyahmobile.com/qrcodes/reseller_5432.png"
    }
  }
}

Retry Policy

Your webhook endpoint must respond with a 2xx status code. Non-2xx responses trigger retries with exponential backoff:

Order Lifecycle

Idempotency

Every order creation request requires a unique idempotency_key. If you accidentally send the same request twice (e.g., due to a network timeout), the API returns the existing order instead of creating a duplicate.

{
  "success": true,
  "message": "Duplicate request, returning existing order.",
  "data": { ... }
}

Error Codes

Error Response Format

{
  "success": false,
  "error": "Insufficient wallet balance."
}

Validation Error Format

{
  "success": false,
  "error": "Validation failed",
  "messages": {
    "plan_id": ["The plan_id field is required."],
    "webhook_url": ["The webhook_url must be a valid URL."]
  }
}

Data Types

Test Mode

If your account is in test mode, only plans enabled for sandbox testing are available. Test mode uses sandbox provisioning: test orders simulate the provisioning flow without creating real eSIMs.