Create an order

​

Authentication

​

Headers

​

Request Body

POST /v1/api_partner/orders

{
  "external_order_id": "ORDER-123456",
  "products": [
    {
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "qty": 1
    },
    {
      "option_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "qty": 2
    }
  ]
}

​

Response

{
  "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

{
  "error": "Invalid JSON format"
}

• Malformed JSON in request body
• Invalid JSON syntax
• Missing or empty request body

​

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid signature."
  }
}

• 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

{
  "errors": ["Product with option_id not found"]
}

{
  "errors": ["External order id can't be blank"]
}

{
  "errors": ["External order id has already been taken"]
}

• Empty products array
• Missing option_id or qty in product objects
• Invalid qty value (must be a positive integer)

{
  "errors": ["eSIM Request failed - Status: [code], Message: [message]"]
}

{
  "errors": ["API connection error (Order ID: [order_id])"]
}

​

500 Internal Server Error

{
  "error": "Internal server error"
}

• 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

{
  "products": [
    {
      "topup_id": "20250129123456123456789012",
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "topup_id": "20250129123456123456789013",
      "option_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

​

Webhooks

​

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"
}