Skip to main content
POST
/
v1
/
api_partner
/
orders
POST /v1/api_partner/orders

{
  "products": [
    {
      "topup_id": "20250129123456123456789012",
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "topup_id": "20250129123456123456789013",
      "option_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    },
    {
      "topup_id": "20250129123456123456789014",
      "option_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  ]
}

​
Authentication

This endpoint requires HMAC-SHA256 signature authentication. See Authentication guide for details.

​
Headers

​
X-Esim-Story-Access-Key
string
required
Your partner access key. Used for authentication.
​
X-Esim-Story-Signature
string
required
HMAC-SHA256 signature of the request. Generated using your secret key. See Authentication guide for signature generation details.
​
X-Esim-Story-Timestamp
string
required
Unix timestamp in seconds (UTC). Must be within the allowed time window of the current time.

​
Request Body

​
external_order_id
string
required
Your order identifier in your system. Must be unique.
​
products
array
required
Array of products to order. Each product must include: - option_id (string, required): The eSIM product option ID - qty (integer, required): Quantity of this product to order
POST /v1/api_partner/orders

​
Response

​
products
array
Array of products with their assigned topup IDs. Each product includes: - topup_id (string): The topup ID assigned to this product - option_id (string): The option ID that was ordered
{
  "products": [
    {
      "topup_id": "20250129123456123456789012",
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "topup_id": "20250129123456123456789013",
      "option_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    },
    {
      "topup_id": "20250129123456123456789014",
      "option_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  ]
}

​
Error Responses

​
400 Bad Request

Invalid request payload or JSON parsing error: 
{
  "error": "Invalid JSON format"
}
Common causes:
  • Malformed JSON in request body
  • Invalid JSON syntax
  • Missing or empty request body

​
401 Unauthorized

Authentication failed: 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid signature."
  }
}
Common authentication errors:
  • Missing required authentication headers: One or more of X-Esim-Story-Access-Key, X-Esim-Story-Signature, or X-Esim-Story-Timestamp headers are missing 
    {
  "error": {
    "code": "unauthorized",
    "message": "Missing required authentication headers."
  }
}
  • Invalid access key: The provided access key does not exist in the system 
    {
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing access key. Please provide a valid X-Esim-Story-Access-Key header."
  }
}
  • Invalid signature: The HMAC signature does not match the expected signature 
    {
  "error": {
    "code": "unauthorized",
    "message": "Invalid signature."
  }
}
  • Request timestamp is too old or invalid: The timestamp must be within the allowed time window of the current time 
    {
  "error": {
    "code": "unauthorized",
    "message": "Request timestamp is too old or invalid."
  }
}
  • Missing secret key: The partner record is missing a secret key 
    {
  "error": {
    "code": "unauthorized",
    "message": "Missing secret key in partner record."
  }
}

​
422 Unprocessable Entity

Validation errors or business logic errors: Product not found: When an option_id in the products array does not exist in the system: 
{
  "errors": ["Product with option_id not found"]
}
Missing required fields: 
{
  "errors": ["External order id can't be blank"]
}
Duplicate external_order_id: 
{
  "errors": ["External order id has already been taken"]
}
Invalid products array:
  • Empty products array
  • Missing option_id or qty in product objects
  • Invalid qty value (must be a positive integer)
eSIM API errors: When the external eSIM provider API returns an error: 
{
  "errors": ["eSIM Request failed - Status: [code], Message: [message]"]
}
API connection errors: When there’s a network error connecting to the eSIM provider: 
{
  "errors": ["API connection error (Order ID: [order_id])"]
}

​
500 Internal Server Error

Server error during order processing: 
{
  "error": "Internal server error"
}
Common causes:
  • Database connection errors
  • Unexpected server errors
  • External service failures

​
Notes

  • The external_order_id must be unique.
  • Each product in the products array will be ordered qty times.
  • The response includes one topup_id per quantity ordered (e.g., if qty: 2, you’ll receive 2 entries with different topup_id values).
  • Orders are processed asynchronously. The response indicates successful order creation, but eSIM activation may take additional time.
  • You must configure a webhook URL to receive eSIM data. If no webhook URL is configured, you will not receive eSIM activation data.
  • In sandbox environment, orders use test data and do not result in actual eSIM purchases.

​
Example: Ordering Multiple Quantities

If you order a product with qty: 2, you’ll receive 2 separate entries in the response: 
{
  "products": [
    {
      "topup_id": "20250129123456123456789012",
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "topup_id": "20250129123456123456789013",
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

​
Webhooks

After successfully creating an order, eSIM data will be delivered to your configured webhook URL once the eSIM is ready. A webhook URL must be configured in your partner account to receive callbacks. Webhooks are sent via POST requests to your configured webhook URL. Your webhook endpoint should return a 200 OK status code to acknowledge successful receipt. One webhook is sent per order item. For example, if you order a product with qty: 2, you will receive 2 separate webhook requests (one for each quantity ordered).

​
Example Response

{
  "topup_id": "20250129123456123456789012",
  "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "iccid": "89852341234567890123",
  "smdp": "rsp1.cmlink.com",
  "activate_code": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6",
  "download_link": "LPA:1$rsp1.cmlink.com$A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6",
  "qrcode_img_url": "https://func-usimsa-prod-01.azurewebsites.net/api/iccid/qrcode/LPA:1%24rsp1.cmlink.com%24A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6/120",
  "expired_date": "2026-07-28",
  "external_order_id": "ORDER-123456"
}
Last modified on February 4, 2026