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 5 minutes of the current time.

​
Request Body

​
external_order_id
string
required
Your unique order identifier. This should be unique within your system.
​
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"
}

​
401 Unauthorized

Authentication failed: 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid signature."
  }
}
Common authentication errors:
  • Missing required authentication headers
  • Invalid access key
  • Invalid signature
  • Request timestamp is too old or invalid (must be within 5 minutes)

​
500 Internal Server Error

Server error during order processing: 
{
  "error": "Internal server error"
}

​
Notes

  • The external_order_id should be unique within your system
  • 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. You must configure a webhook URL in your partner settings to receive callbacks.

​
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"
}
Your webhook endpoint should return a 200 OK status code to acknowledge successful receipt.
Last modified on January 29, 2026