This document is provided by Microdrive Tech Co., Ltd and is only used for the technical connection of the partner.
\nPlease setup request header : Content-Type:Request Content-Type depends on the endpoint. Follow the Body type shown for each endpoint. When multipart/form-data is used, let the HTTP client generate the boundary automatically.
\nThe interface uses UTF-8 encoding
\nSystem time zone: UTC/GMT+08:00
\nEnvironment URLs:
\nTest Environment :https://test.microesim.com
Production Environment :https://business.microesim.com
MICROESIM-ACCOUNT：Account identifier provided by MicroEsim.
\nMICROESIM-NONCE：A unique random string of 6–20 characters. Generate a new value for every request. A nonce reused within five minutes will be rejected. .
\nMICROESIM-TIMESTAMP：Current 13-digit Unix timestamp in milliseconds. It must be within five minutes of the server time.
\nMICROESIM-SIGN: Lowercase hexadecimal HMAC-SHA256 signature generated from MICROESIM-ACCOUNT + MICROESIM-NONCE + MICROESIM-TIMESTAMP, with no separators.
\nGenerate a unique random nonce of 6–20 characters.
\nGet the current Unix timestamp in milliseconds.
\nDerive a 32-byte key using PBKDF2-HMAC-SHA256 with the provided secret, hex-decoded salt and 1024 iterations.
\nConvert the derived key to a lowercase hexadecimal string.
\nConcatenate MICROESIM-ACCOUNT, MICROESIM-NONCE and MICROESIM-TIMESTAMP without separators.
\nGenerate the HMAC-SHA256 signature using the UTF-8 bytes of the derived hexadecimal key, and output the signature as lowercase
hexadecimal.
Send the four authentication headers with the request.
\nOnly MICROESIM-ACCOUNT, MICROESIM-NONCE and MICROESIM-TIMESTAMP are included in the signature. The URL, query parameters and request body
are not included.
Production requests may also be restricted by the IP allowlist configured for the account.
\nimport crypto from \"crypto\";\nimport fetch from \"node-fetch\";\nfunction toHex(buffer) {\n return buffer.toString(\"hex\");\n}\nfunction pbkdf2ToHex(secret, saltHex, iterations, keyLen) {\n const salt = Buffer.from(saltHex, \"hex\");\n const derivedKey = crypto.pbkdf2Sync(secret, salt, iterations, keyLen, \"sha256\");\n return toHex(derivedKey);\n}\nfunction hmacWithHexKey(data, hexKey) {\n return crypto\n .createHmac(\"sha256\", Buffer.from(hexKey, \"utf-8\"))\n .update(data)\n .digest(\"hex\");\n}\nasync function sendRequest() {\n const account = \"your_account_here\";\n const secret = \"your_secret_here\";\n const saltHex = \"your_salt_hex_here\";\n const nonce = Math.random().toString(36).substring(2, 18);\n const timestamp = Date.now().toString();\n const hexKey = pbkdf2ToHex(secret, saltHex, 1024, 32);\n const data = account + nonce + timestamp;\n const signature = hmacWithHexKey(data, hexKey);\n const url = \"https://business.microesim.com/allesim/v1/esimDataplanList\";\n const headers = {\n \"Content-Type\": \"application/json\",\n \"MICROESIM-ACCOUNT\": account,\n \"MICROESIM-NONCE\": nonce,\n \"MICROESIM-TIMESTAMP\": timestamp,\n \"MICROESIM-SIGN\": signature,\n };\n try {\n const response = await fetch(url, { method: \"GET\", headers });\n const result = await response.json();\n console.log(\"Response status:\", response.status);\n console.log(\"Response data:\", result);\n } catch (error) {\n console.error(\"Request failed:\", error);\n }\n}\nsendRequest();\n\nimport requests\nimport secrets\nimport time\nimport hmac\nimport hashlib\nimport binascii\nACCOUNT = \"your_account_here\"\nSECRET = \"your_secret_here\"\nSALT_HEX = \"your_salt_hex_here\"\nSALT = binascii.unhexlify(SALT_HEX)\nITERATIONS = 1024\nKEY_LENGTH = 32 \nnonce = secrets.token_hex(10)\ntimestamp = str(int(time.time() * 1000))\nhash_password = hashlib.pbkdf2_hmac(\n 'sha256',\n SECRET.encode('utf-8'),\n SALT,\n ITERATIONS,\n dklen=KEY_LENGTH\n)\ndata_to_sign = ACCOUNT + nonce + timestamp\nhash_password_hex = hash_password.hex()\nsignature = hmac.new(\n hash_password_hex.encode('utf-8'),\n data_to_sign.encode('utf-8'),\n hashlib.sha256\n).hexdigest()\nheaders = {\n \"Content-Type\": \"application/json\",\n \"MICROESIM-ACCOUNT\": ACCOUNT,\n \"MICROESIM-NONCE\": nonce,\n \"MICROESIM-TIMESTAMP\": timestamp,\n \"MICROESIM-SIGN\": signature\n}\nurl = \"https://business.microesim.com/allesim/v1/esimDataplanList\"\nresponse = requests.get(url, headers=headers, timeout=10)\nprint(\"Signature:\", signature)\nprint(\"Response status:\", response.status_code)\nprint(\"Response text:\", response.text)\n\nimport javax.crypto.Mac;\nimport javax.crypto.SecretKeyFactory;\nimport javax.crypto.spec.PBEKeySpec;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.io.BufferedReader;\nimport java.io.InputStreamReader;\nimport java.net.HttpURLConnection;\nimport java.net.URL;\nimport java.nio.charset.StandardCharsets;\nimport java.security.spec.KeySpec;\nimport java.util.Random;\npublic class MicroEsimApiClient {\n public static String pbkdf2Hex(String secret, byte[] salt, int iterations, int keyLength) throws Exception {\n KeySpec spec = new PBEKeySpec(secret.toCharArray(), salt, iterations, keyLength * 8);\n SecretKeyFactory factory = SecretKeyFactory.getInstance(\"PBKDF2WithHmacSHA256\");\n byte[] key = factory.generateSecret(spec).getEncoded();\n return bytesToHex(key);\n }\n public static String hmacSha256Hex(String data, String hexKey) throws Exception {\n byte[] keyBytes = hexKey.getBytes(StandardCharsets.UTF_8);\n SecretKeySpec secretKey = new SecretKeySpec(keyBytes, \"HmacSHA256\");\n Mac mac = Mac.getInstance(\"HmacSHA256\");\n mac.init(secretKey);\n byte[] hmac = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));\n return bytesToHex(hmac);\n }\n public static String bytesToHex(byte[] bytes) {\n StringBuilder sb = new StringBuilder();\n for (byte b : bytes) {\n sb.append(String.format(\"\u0002x\", b)); \n }\n return sb.toString();\n }\n public static String generateNonce(int length) {\n String chars = \"abcdefghijklmnopqrstuvwxyz0123456789\";\n StringBuilder nonce = new StringBuilder();\n Random random = new Random();\n for (int i = 0; i < length; i++) {\n nonce.append(chars.charAt(random.nextInt(chars.length())));\n }\n return nonce.toString();\n }\n private static byte[] hexStringToByteArray(String s) {\n int len = s.length();\n byte[] data = new byte[len / 2];\n for (int i = 0; i < len; i += 2) {\n data[i / 2] = (byte) ((Character.digit(s.charAt(i), 16) << 4)\n + Character.digit(s.charAt(i + 1), 16));\n }\n return data;\n }\n public static void main(String[] args) throws Exception {\n // 请替换成你自己的参数👇\n String account = \"your_account_here\";\n String secret = \"your_secret_here\";\n String saltHex = \"your_salt_hex_here\";\n byte[] salt = hexStringToByteArray(saltHex);\n int iterations = 1024;\n int keyLength = 32;\n String nonce = generateNonce(16);\n String timestamp = String.valueOf(System.currentTimeMillis());\n String hexKey = pbkdf2Hex(secret, salt, iterations, keyLength);\n String dataToSign = account + nonce + timestamp;\n String signature = hmacSha256Hex(dataToSign, hexKey);\n String urlStr = \"https://business.microesim.com/allesim/v1/esimDataplanList\";\n URL url = new URL(urlStr);\n HttpURLConnection conn = (HttpURLConnection) url.openConnection();\n conn.setRequestMethod(\"GET\");\n conn.setRequestProperty(\"Content-Type\", \"application/json\");\n conn.setRequestProperty(\"MICROESIM-ACCOUNT\", account);\n conn.setRequestProperty(\"MICROESIM-NONCE\", nonce);\n conn.setRequestProperty(\"MICROESIM-TIMESTAMP\", timestamp);\n conn.setRequestProperty(\"MICROESIM-SIGN\", signature);\n int responseCode = conn.getResponseCode();\n System.out.println(\"Response Code: \" + responseCode);\n BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8));\n String inputLine;\n StringBuilder response = new StringBuilder();\n while ((inputLine = in.readLine()) != null) {\n response.append(inputLine);\n }\n in.close();\n System.out.println(\"Response Body: \" + response.toString());\n }\n}\n\n$account = \"your_account_here\";\n$secret = \"your_secret_here\";\n$saltHex = \"your_salt_hex_here\";\n$nonce = bin2hex(random_bytes(8));\n$timestamp = (string)round(microtime(true) * 1000);\n$key_bin = hash_pbkdf2(\"sha256\", $secret, hex2bin($saltHex), 1024, 32, true);\n$key_hex = bin2hex($key_bin);\n$dataToSign = $account . $nonce . $timestamp;\n$signature = hash_hmac(\"sha256\", $dataToSign, $key_hex);\n$url = \"https://business.microesim.com/allesim/v1/esimDataplanList\";\n$headers = [\n \"Content-Type: application/json\",\n \"MICROESIM-ACCOUNT: $account\",\n \"MICROESIM-NONCE: $nonce\",\n \"MICROESIM-TIMESTAMP: $timestamp\",\n \"MICROESIM-SIGN: $signature\"\n];\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL, $url);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, $headers);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$response = curl_exec($ch);\nif (curl_errno($ch)) {\n echo \"Curl error: \" . curl_error($ch);\n} else {\n echo \"Response:\\n$response\\n\";\n}\ncurl_close($ch);\n\n// Postman Request Script\nconst CryptoJS = require('crypto-js');\nconst account = 'account';\nconst nonce = CryptoJS.lib.WordArray.random(10).toString(CryptoJS.enc.Hex);\nconst timestamp = new Date().getTime().toString();\nconst secret = 'secret';\nconst salt = CryptoJS.enc.Hex.parse('salt');\nconst iterations = 1024;\nconst keyLength = 256 / 32; \nlet hashPassword = CryptoJS.PBKDF2(secret, salt, {keySize: keyLength,iterations: iterations,hasher: CryptoJS.algo.SHA256}).toString(CryptoJS.enc.Hex);\nconst dataToHash = account + nonce + timestamp;\nconst signature = CryptoJS.HmacSHA256(dataToHash,hashPassword).toString(CryptoJS.enc.Hex);\nconsole.log(\"Generated Signature (Client): \" + signature); \npm.environment.set(\"MICROESIM-ACCOUNT\", account);\npm.environment.set(\"MICROESIM-SIGN\", signature);\npm.environment.set(\"MICROESIM-TIMESTAMP\", timestamp);\npm.environment.set(\"MICROESIM-NONCE\", nonce); \n\nAll /allesim/v1/\\\\* endpoints return the same envelope:
{ \"code\": 400, \"error_code\": \"ORDER_INSUFFICIENT_BALANCE\", \"msg\": \"...\", \"result\": null }\n\nSuccess is always code = 1, and error_code is not present.
Failure returns error_code. Branch on error_code — never parse msg, its wording may change.
msg is written by MicroEsim and never contains supplier names or upstream error codes.
result may be null or omitted on failure; do not rely on it being present.
Partial provisioning. Multi-unit orders are provisioned and billed one unit at a time. If stock
runs out part-way, the delivered units are kept and charged and you still get ORDER_OUT_OF_STOCK.
Call topupDetail and compare success_number against your requested number before re-ordering.
Never auto-retry ORDER_PROVISION_FAILED or ORDER_OUT_OF_STOCK without calling topupDetail
first — the order may already be partially provisioned.
Unknown codes. Treat any error_code you do not recognise as a non-retryable failure of its
HTTP status class, so new codes added later will not break your integration.
GET /allesim/v1/esimDataplanList — Returns the complete eSIM data plan list.
GET /allesim/v1/esimDataplanListPage — Returns a paginated eSIM data plan list.
POST /allesim/v1/esimSubscribe — Creates a new eSIM order.
POST /allesim/v1/topupDetail — Queries order and eSIM delivery progress.
POST /allesim/v1/deviceDetail — Queries the status, activation time, expiration time and usage of one eSIM.
POST /allesim/v1/eventDetail — Queries eSIM profile events.
POST /allesim/v1/accountBalance — Returns the account balance.
POST /allesim/v1/accountTransactionList — Returns paginated account transaction records.
GET /allesim/v1/dailyNotice — Returns daily notices.
eSIM Delivery Notification — Sent by MicroEsim to the effective client callback URL when an eSIM delivery record is ready. This is not a MicroEsim API endpoint.
\nGET /allesim/v1/esimDataplanList
or GET /allesim/v1/esimDataplanListPage (Recommended for large data)
POST /allesim/v1/esimSubscribe
Use channel_dataplan_id from Step 1
Response returns topup_id
POST /allesim/v1/topupDetail
Query order status by topup_id
Client actively polls the order detail
\nConfigure an account-level callback URL, or provide notify_url in the esimSubscribe request as an order-level override.
\nMicroEsim sends one eSIM delivery record to the effective callback URL when the delivery information is ready.
\nThe callback URL is a client-provided endpoint. /topupDetail-async is not a MicroEsim API endpoint.
\nBase URL: https://test.microesim.com
\nEach esimSubscribe returns a unique topup_id; the number you pass is reflected in topupDetail (number + device_ids array).
The same topup_id can be queried repeatedly and always returns the same result.
Usage figures are sample/placeholder values — no real eSIM is provisioned in test.
\nThe channel_dataplan_id, topup_id, device_id and dates shown in the examples are sample values for testing. Authentication values must be generated for each request using the credentials assigned to your account.
\nThe order-stage errors ORDER_INSUFFICIENT_BALANCE, ORDER_OUT_OF_STOCK and
ORDER_PROVISION_FAILED are not reproducible in the test environment, which returns
simulated order results. Handle them by error_code as described in Section 5.
HMAC-SHA256 signature generated for this request.
\n"}],"url":"https://business.microesim.com/allesim/v1/esimDataplanList","description":"eSIM Data Plan List - All interface
\n","urlObject":{"path":["allesim","v1","esimDataplanList"],"host":["https://business.microesim.com"],"query":[],"variable":[]}},"response":[{"id":"f759ba70-bafa-41be-a06a-a29f5e66b2fe","name":"/allesim/v1/esimDataplanList","originalRequest":{"method":"GET","header":[{"key":"MICROESIM-ACCOUNT","value":""},{"key":"MICROESIM-NONCE","value":""},{"key":"MICROESIM-TIMESTAMP","value":""},{"key":"MICROESIM-SIGN","value":"","description":"HMAC-SHA256 signature generated for this request."},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://business.microesim.com/allesim/v1/esimDataplanList"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1,\n \"msg\": \"Success\",\n \"result\": [\n {\n \"channel_dataplan_id\": \"b1a926e1-d770-4e03-804e-c527b9397eb9\",\n \"channel_dataplan_name\": \"Global 66-Total1GB-7-A0-test\",\n \"price\": \"524.00\",\n \"currency\": \"HKD\",\n \"status\": \"1\",\n \"day\": 30,\n \"data\": \"unlimited\",\n \"apn\": \"vmobile.jp\",\n \"active_type\":\"ACTIVEDBYDEVICE\",\n \"code\": \"JP\",\n \"networks\": \"JP:Docomo(IIJ)[4G;LTE]|\",\n \"ip\": \"PL\",\n \"rule_desc\": \"unlimited 512kbps\",\n \"validity_period\": \"60\",\n \"special_desc\": \"\", \n \"date_reset\": \"24Hrs\", \n \"usage_reset\": \"24Hrs\" \n },\n {\n \"channel_dataplan_id\": \"202408136e79772A718449EEE9290CAC3\",\n \"channel_dataplan_name\": \"JapanIIJ-unlimited-15-test\",\n \"price\": \"279.62\",\n \"currency\": \"HKD\",\n \"status\": \"1\",\n \"day\": 15,\n \"data\": \"unlimited\",\n \"apn\": \"vmobile.jp\",\n \"active_type\":\"ACTIVEDBYDEVICE\",\n \"code\": \"JP\",\n \"networks\": \"JP:Docomo(IIJ)[4G;LTE]|\",\n \"ip\": \"PL\",\n \"rule_desc\": \"unlimited 512kbps\",\n \"validity_period\": \"60\",\n \"special_desc\": \"\", \n \"date_reset\": \"24Hrs\", \n \"usage_reset\": \"24Hrs\" \n \n },\n {\n \"channel_dataplan_id\": \"2024081342489905C36Eee9eA513390E9\",\n \"channel_dataplan_name\": \"JapanIIJ-unlimited-10-test\",\n \"price\": \"209.00\",\n \"currency\": \"HKD\",\n \"status\": \"1\",\n \"day\": 10,\n \"data\": \"unlimited\",\n \"apn\": \"vmobile.jp\",\n \"active_type\":\"ACTIVEDBYDEVICE\",\n \"code\": \"JP\",\n \"networks\": \"JP:Docomo(IIJ)[4G;LTE]|\",\n \"ip\": \"HK\",\n \"rule_desc\": \"unlimited 128kb\",\n \"validity_period\": \"60\",\n \"special_desc\": \"\", \n \"date_reset\": \"24Hrs\", \n \"usage_reset\": \"24Hrs\" \n }\n ]\n}"}],"_postman_id":"27a2a67a-9d34-443c-84ce-383fd2bcc663"},{"name":"/allesim/v1/esimDataplanListPage","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["\r\n"]}}],"id":"998947b1-c8ee-48a4-9e6c-a4e79c988d23","protocolProfileBehavior":{"disabledSystemHeaders":{}},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}","description":"HMAC-SHA256 signature generated for this request.
\n"}],"url":"https://business.microesim.com/allesim/v1/esimDataplanListPage?pageNo=1&pageSize=500","description":"⚠️ For accounts with a large number of data plans (> 10,000), requesting all data in a single call may cause network timeouts or oversized responses.
If any request issues occur, please use the paginated interface: eSIM Data Plan List By Page.
Maximum value: 500
\n","type":"text/plain"},"key":"pageSize","value":"500"}],"variable":[]}},"response":[{"id":"f418e5a2-d586-4dae-a7d6-d33bf5512483","name":"/allesim/v1/esimDataplanListPage","originalRequest":{"method":"GET","header":[{"key":"MICROESIM-ACCOUNT","value":""},{"key":"MICROESIM-NONCE","value":""},{"key":"MICROESIM-TIMESTAMP","value":""},{"key":"MICROESIM-SIGN","value":"","description":"HMAC-SHA256 signature generated for this request."}],"url":"https://business.microesim.com/allesim/v1/esimDataplanListPage"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1,\n \"msg\": \"Success\",\n \"result\": {\n \"pageNo\": 1,\n \"pageSize\": 500,\n \"total\": 5,\n \"totalPages\": 1,\n \"list\": [\n {\n \"channel_dataplan_id\": \"b1a926e1-d770-4e03-804e-c527b9397eb9\",\n \"channel_dataplan_name\": \"Global 66-Total1GB-7-A0-test\",\n \"price\": \"524.00\",\n \"currency\": \"HKD\",\n \"status\": \"1\",\n \"day\": 30,\n \"data\": \"unlimited\",\n \"apn\": \"vmobile.jp\",\n \"active_type\":\"ACTIVEDBYDEVICE\",\n \"code\": \"JP\",\n \"networks\": \"JP:Docomo(IIJ)[4G;LTE]|\",\n \"ip\": \"PL\",\n \"rule_desc\": \"unlimited 512kbps\",\n \"validity_period\": \"60\",\n \"special_desc\": \"\", \n \"date_reset\": \"24Hrs\", \n \"usage_reset\": \"24Hrs\" \n },\n {\n \"channel_dataplan_id\": \"202408136e79772A718449EEE9290CAC3\",\n \"channel_dataplan_name\": \"JapanIIJ-unlimited-15-test\",\n \"price\": \"279.62\",\n \"currency\": \"HKD\",\n \"status\": \"1\",\n \"day\": 15,\n \"data\": \"unlimited\",\n \"apn\": \"vmobile.jp\",\n \"active_type\":\"ACTIVEDBYDEVICE\",\n \"code\": \"JP\",\n \"networks\": \"JP:Docomo(IIJ)[4G;LTE]|\",\n \"ip\": \"PL\",\n \"rule_desc\": \"unlimited 512kbps\",\n \"validity_period\": \"60\",\n \"special_desc\": \"ekyc required esim\", \n \"date_reset\": \"24Hrs\", \n \"usage_reset\": \"24Hrs\" \n },\n {\n \"channel_dataplan_id\": \"2024081342489905C36Eee9eA513390E9\",\n \"channel_dataplan_name\": \"JapanIIJ-unlimited-10-test\",\n \"price\": \"209.00\",\n \"currency\": \"HKD\",\n \"status\": \"1\",\n \"day\": 10,\n \"data\": \"unlimited\",\n \"apn\": \"vmobile.jp\",\n \"active_type\":\"ACTIVEDBYDEVICE\",\n \"code\": \"JP\",\n \"networks\": \"JP:Docomo(IIJ)[4G;LTE]|\",\n \"ip\": \"HK\",\n \"rule_desc\": \"unlimited 128kb\",\n \"validity_period\": \"60\",\n \"special_desc\": \"ekyc required esim\", \n \"date_reset\": \"24Hrs\", \n \"usage_reset\": \"24Hrs\" \n }\n ]\n }\n}"}],"_postman_id":"998947b1-c8ee-48a4-9e6c-a4e79c988d23"},{"name":"/allesim/v1/esimSubscribe","id":"8b99ff5a-f21f-410c-bb59-0a8bc6f3ab0f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}","description":"HMAC-SHA256 signature generated for this request.
\n"}],"body":{"mode":"formdata","formdata":[{"key":"number","value":"1","type":"text","description":"Quantity(Recommended：1，Value> 1 may trigger delays.Mandatory)
\n"},{"key":"channel_dataplan_id","value":"b1a926e1-d770-4e03-804e-c527b9397eb9","type":"text","description":"channel_dataplan_id(Mandatory)
\n"},{"key":"activation_date","value":"","type":"text","description":"Required only when active_type=ACTIVEDBYORDER. Format: yyyy-MM-dd. Must be a future date within 180 days. Leave blank for other activation types.
\n"},{"key":"custom_order_no","value":"","type":"text","description":"Custom order number(Optional)
\n"},{"key":"custom_email","value":"","type":"text","description":"Send an email after complete the eSIM(Optional)
\n"},{"key":"remark","value":"","type":"text","description":"Optional
\n"},{"key":"notify_url","value":"","type":"text","description":"Optional. Per-order eSIM delivery callback URL. Overrides the account-level callback URL. Maximum 255 characters; must start with http:// or https://.
\n"}]},"url":"https://business.microesim.com/allesim/v1/esimSubscribe","description":"Create a new eSIM order.
\nBefore ordering, call /allesim/v1/esimDataplanList or /allesim/v1/esimDataplanListPage and check the active_type of the selected data plan.
\nIf active_type is ACTIVEDBYORDER, activation_date is required.
\nFor other active_type values, activation follows the data plan's activation policy. Leave activation_date empty.
\nactivation_date format: yyyy-MM-dd.
\nactivation_date must be a future date within 180 days.
\nThe response returns topup_id. Use /allesim/v1/topupDetail to query the order and eSIM delivery progress.
\nThe topup_id shown in examples is for illustration only. A unique topup_id is generated for each successful order.
\nnotify_url is optional. When provided, it overrides the account-level callback URL for this order. If omitted, the account-level callback URL is used; if neither is configured, no delivery webhook is sent. The value must be no more than 255 characters and start with http:// or https://. Request parameters, including notify_url, are not included in the HMAC signature.
\n","urlObject":{"path":["allesim","v1","esimSubscribe"],"host":["https://business.microesim.com"],"query":[],"variable":[]}},"response":[{"id":"d5351c58-bf1c-470c-bd63-d97a1dacd214","name":"/allesim/v1/esimSubscribe","originalRequest":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":""},{"key":"MICROESIM-NONCE","value":""},{"key":"MICROESIM-TIMESTAMP","value":""},{"key":"MICROESIM-SIGN","value":"","description":"HMAC-SHA256 signature generated for this request."}],"body":{"mode":"formdata","formdata":[{"key":"number","value":"2","type":"text"},{"key":"channel_dataplan_id","value":"b1a926e1-d770-4e03-804e-c527b9397eb9","type":"text"}]},"url":"https://business.microesim.com/allesim/v1/esimSubscribe"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1,\n \"msg\": \"Success\",\n \"result\": {\n \"topup_id\": \"202308161431187762753800\"\n }\n}"}],"_postman_id":"8b99ff5a-f21f-410c-bb59-0a8bc6f3ab0f"},{"name":"/allesim/v1/topupDetail","id":"695a4ed0-d637-43a2-aa55-01d8092f01a4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}"}],"body":{"mode":"formdata","formdata":[{"key":"topup_id","value":"202308161431187762753800","type":"text","description":"Required. The topup_id returned by POST /allesim/v1/esimSubscribe.
\n"}]},"url":"https://business.microesim.com/allesim/v1/topupDetail","description":"Query the eSIM delivery progress of an order using topup_id.
\nOrder delivery status:
\nprocessing: Delivery information is not ready for all eSIMs, or success_number is less than number.
\ncompleted: success_number has reached number.
\nWhen the status is processing, delivery fields and arrays may be absent or incomplete. Retry the query later. A processing status does not mean that the order has failed.
\nThis endpoint may be used for polling even when a delivery webhook is configured. The webhook is sent by MicroEsim to the effective callback URL; it is not an API endpoint named /topupDetail-async.
\nFor Local data plans, delivery or usage information may take 1–2 minutes to become available.
\nFields at the same array index, such as device_ids, lpa_str, qrcode, ios_esim_install_link and android_esim_install_link, belong to the same eSIM. During processing, these arrays may be incomplete.
\n","urlObject":{"path":["allesim","v1","topupDetail"],"host":["https://business.microesim.com"],"query":[],"variable":[]}},"response":[{"id":"777240f2-8205-4841-bd3e-2e707ebc6bcf","name":"200 OK：status=completed","originalRequest":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":""},{"key":"MICROESIM-NONCE","value":""},{"key":"MICROESIM-TIMESTAMP","value":""},{"key":"MICROESIM-SIGN","value":""}],"body":{"mode":"formdata","formdata":[{"key":"topup_id","value":"202408161431187762753800","type":"text","description":"Topup ID"}]},"url":"https://business.microesim.com/allesim/v1/topupDetail"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1,\n \"msg\": \"Success\",\n \"result\": {\n \"topup_id\": \"202308161431187762753800\",\n \"status\": \"completed\" ,\n \"number\": 2,\n \"channel_dataplan_id\": \"b1a926e1-d770-4e03-804e-c527b9397eb9\",\n \"channel_dataplan_name\": \"Global 66-Total1GB-7-A0\",\n \"success_number\": 2,\n \"create_time\": \"Fri Aug 16 14:00:08 CST 2024\",\n \"type\": \"esim\",\n \"device_ids\": [\n \"9000024081603874\",\n \"9000024081684603\"\n ],\n \"lpa_str\": [\n \"LPA:1$rsp-eu.simlessly.com$580FFE02FFEE57965B6EECA132DA088D\",\n \"LPA:1$rsp-eu.simlessly.com$56C139A2ED0CA148F9AF57364F6DDDEF\"\n ],\n \"qrcode\": [\n \"https://microesim.top/files/9999-9000024081603874\",\n \"https://microesim.top/files/9999-9000024081684603\"\n ],\n \"ios_esim_install_link\": [\n \"https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$580FFE02FFEE57965B6EECA132DA088D\",\n \"https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$56C139A2ED0CA148F9AF57364F6DDDEF\"\n ],\n \"android_esim_install_link\": [\n \"https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$580FFE02FFEE57965B6EECA132DA028D\",\n \"https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$56C139A2ED0CA148F9AF57364F6CCCEF\"\n ],\n \"msisdn\": [\n \"482222233223\",\n \"482222233333\"\n ],\n \"cf_code\": [\n \"000777\",\n \"000888\"\n ]\n }\n}"},{"id":"18b558b5-0c66-4812-9b3c-4122e564d980","name":"200 - Order Processing","originalRequest":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}"}],"body":{"mode":"formdata","formdata":[{"key":"topup_id","value":"202308161431187762753800","type":"text","description":"Required. The topup_id returned by POST /allesim/v1/esimSubscribe."}]},"url":"https://business.microesim.com/allesim/v1/topupDetail"},"code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":" { \r\n \"code\": 1, \r\n \"msg\": \"Processing\", \r\n \"result\": { \r\n \"topup_id\": \"202308161431187762753800\", \r\n \"status\": \"processing\" \r\n } \r\n } \r\n "}],"_postman_id":"695a4ed0-d637-43a2-aa55-01d8092f01a4"},{"name":"/allesim/v1/deviceDetail","event":[{"listen":"prerequest","script":{"exec":[""],"type":"text/javascript","packages":{},"id":"d05d1e01-2f56-4252-b609-11f9399114ba"}},{"listen":"test","script":{"exec":[""],"type":"text/javascript","packages":{},"id":"f88913d8-119a-468f-a58e-ec32a7bad81c"}}],"id":"6e17cc64-93eb-4bd5-9c6e-78607bf84338","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}","type":"text"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}","type":"text"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}","type":"text"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"topup_id","value":"202308161431187762753800","description":"Topup ID (Order No)
\n","type":"text"},{"key":"device_id","value":"9000024081684603","description":"Device ID (ICCID No)
\n","type":"text"}]},"url":"https://business.microesim.com/allesim/v1/deviceDetail","description":"Enquiry Data Plan Details interface.
\nNote: topup_id and device_id in the example are sample values. Use the actual topup_id from esimSubscribe and the device_id from topupDetail.
Device ID (ICCID No)
\n","type":"text"}]},"url":"https://business.microesim.com/allesim/v1/eventDetail","description":"notify_type:\"DOWNLOADED\", \"INSTALLED\", \"DELETE\", \"ENABLE\", \"DISABLE\"
\nNote: device_id in the example is a sample value. Use the actual device_id returned by topupDetail.
Returns the account balance.
\n","urlObject":{"path":["allesim","v1","accountBalance"],"host":["https://business.microesim.com"],"query":[],"variable":[]}},"response":[{"id":"455a1dc2-8a16-4ac8-93ed-9d4d58bfafe9","name":"/allesim/v1/accountBalance","originalRequest":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":""},{"key":"MICROESIM-NONCE","value":""},{"key":"MICROESIM-TIMESTAMP","value":""},{"key":"MICROESIM-SIGN","value":""}],"url":"https://business.microesim.com/allesim/v1/accountBalance"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1,\n \"msg\": \"Success\",\n \"result\": {\n \"balance\": 14860.23,\n \"currency\": \"HKD\",\n \"account\": \"MicroeSIM\"\n }\n}"}],"_postman_id":"a12fc3f5-11c0-4c85-a691-136f34684609"},{"name":"/allesim/v1/accountTransactionList","id":"dea9f8a0-1ee3-4598-b803-7ef169f6b36d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"start_time","value":"2026-08-01 00:00:00","description":"Required. Start time in Asia/Shanghai (yyyy-MM-dd HH:mm:ss); inclusive.
\n"},{"key":"end_time","value":"2026-08-20 00:00:00","description":"Required. End time in Asia/Shanghai (yyyy-MM-dd HH:mm:ss); exclusive. Maximum range: 30 days.
\n"},{"key":"transaction_type","value":"","description":"Optional. Allowed values: consume, recharge, order_refund, adjustment.
\n","disabled":true},{"key":"topup_id","value":"","description":"Optional. Exact Top-up ID filter.
\n","disabled":true},{"key":"device_id","value":"","description":"Optional. Exact eSIM device ID filter.
\n","disabled":true},{"key":"page_size","value":"","description":"Optional. Records per page. Default: 100; maximum: 500.
\n","disabled":true},{"key":"cursor","value":"","description":"Optional. Use the next_cursor returned by the previous response to retrieve the next page
\n","disabled":true}]},"url":"https://business.microesim.com/allesim/v1/accountTransactionList","description":"Returns paginated account transaction records for the authenticated B2B account.
\nThe maximum query range is 30 days. Results are ordered by creation time in descending order.
\n","urlObject":{"path":["allesim","v1","accountTransactionList"],"host":["https://business.microesim.com"],"query":[],"variable":[]}},"response":[{"id":"8dcc570b-8bda-4120-b2cc-b4acebf342d2","name":"/allesim/v1/accountTransactionList","originalRequest":{"method":"POST","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"start_time","value":"2026-08-01 00:00:00"},{"key":"end_time","value":"2026-08-20 00:00:00"}]},"url":"https://business.microesim.com/allesim/v1/accountTransactionList"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":" { \n \"code\": 1, \n \"msg\": \"Success\", \n \"result\": { \n \"transactions\": [\n { \n \"transaction_id\": \"example-transaction-id\", \n \"transaction_type\": \"consume\", \n \"amount\": \"-12.50\", \n \"direction\": \"debit\", \n \"currency\": \"HKD\",\n \"balance_after\": \"987.50\", \n \"topup_id\": \"example-topup-id\", \n \"device_id\": \"example-device-id\", \n \"description\": \"Order consumption\", \n \"created_at\": \"2026-08-19T15:30:00+08:00\" \n }, \n { \n \"transaction_id\": \"example-recharge-id\", \n \"transaction_type\": \"recharge\", \n \"amount\": \"1000.00\", \n \"direction\": \"credit\",\n \"currency\": \"HKD\", \n \"balance_after\": \"1000.00\", \n \"topup_id\": null, \n \"device_id\": null, \n \"description\": \"Account recharge\", \n \"created_at\": \"2026-08-18T10:20:00+08:00\" \n } \n ], \n \"next_cursor\": \"opaque-cursor-returned-by-server\", \n \"has_more\": true\n } \n } "}],"_postman_id":"dea9f8a0-1ee3-4598-b803-7ef169f6b36d"},{"name":"/allesim/v1/dailyNotice","id":"54437191-f79f-4561-9add-02febce47723","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"MICROESIM-ACCOUNT","value":"{{MICROESIM-ACCOUNT}}"},{"key":"MICROESIM-NONCE","value":"{{MICROESIM-NONCE}}"},{"key":"MICROESIM-TIMESTAMP","value":"{{MICROESIM-TIMESTAMP}}"},{"key":"MICROESIM-SIGN","value":"{{MICROESIM-SIGN}}"}],"url":"https://business.microesim.com/allesim/v1/dailyNotice?date=2026-08-05&lang=zh","description":"Returns daily Notice page.
\ndate (required) — format yyyy-MM-dd. Returns notices whose update_date falls on this date.
\nlang (optional) — one of: en, zh, ja, id. If omitted or not one of these four values, defaults to en.
\n","urlObject":{"path":["allesim","v1","dailyNotice"],"host":["https://business.microesim.com"],"query":[{"key":"date","value":"2026-08-05"},{"key":"lang","value":"zh"}],"variable":[]}},"response":[{"id":"0cf38841-df47-4f68-9805-3e10464e3dcb","name":"/allesim/v1/dailyNotice","originalRequest":{"method":"GET","header":[{"key":"MICROESIM-ACCOUNT","value":""},{"key":"MICROESIM-NONCE","value":""},{"key":"MICROESIM-TIMESTAMP","value":""},{"key":"MICROESIM-SIGN","value":""}],"url":"https://business.microesim.com/allesim/v1/dailyNotice"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1,\n \"msg\": \"Success\",\n \"result\": [\n {\n \"notice_type\": \"Service Notice\",\n \"content\": \"Due to policy reasons, roaming services in Kuwait are currently suspended.
All plans including Kuwait are temporarily unavailable for use in the region.
We apologize for any inconvenience caused. If you need any assistance, please feel free to contact our customer support.
\",\n \"update_date\": \"2026-03-24 11:46:36\"\n }\n ]\n}"}],"_postman_id":"54437191-f79f-4561-9add-02febce47723"},{"name":"Webhook Callback: eSIM Delivery Notification","id":"f3ded04a-d706-449d-a469-cec6a6a0a9f8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":" { \r\n \"code\": 1, \r\n \"msg\": \"Success\", \r\n \"data\": { \r\n \"topup_id\": \"202308161431187762753800\", \r\n \"number\": 1, \r\n \"create_time\": \"2023-04-27 15:39:47\", \r\n \"device_id\": \"9000024081603874\", \r\n \"lpa_str\": \"LPA:1$rsp-eu.simlessly.com$580FFE02FFEE57965B6EECA132DA088D\", \r\n \"qrcode\": \"https://microesim.top/files/9999-9000024081603874\", \r\n \"ios_esim_install_link\": \r\n \"https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-eu.simlessly.com$580FFE02FFEE57965B6EECA132DA088D\", \r\n \"msisdn\": \"482222233223\", \r\n \"cf_code\": \"000888\" \r\n } \r\n } ","options":{"raw":{"language":"json"}}},"url":"{{NOTIFY_URL}}","description":"MicroEsim sends this webhook to the effective callback URL when the delivery information for one eSIM is ready.
\nThis is an outbound webhook sent by MicroEsim to the client-provided endpoint. It is not a MicroEsim API endpoint and should not be called by the client.
\nFor orders created through POST /allesim/v1/esimSubscribe, a valid per-order notify_url takes priority. If it is omitted, the account-level callback URL is used as a fallback.
The request body contains the delivery and installation information for one eSIM. It is not an activation, expiration, usage, or plan-status notification.
\nThe receiving endpoint should return HTTP 2xx as soon as possible and handle duplicate notifications idempotently using topup_id + device_id. Failed delivery may be retried; retry timing and total attempts are not guaranteed.