iroamly logoHome

eSIM Exchange Business Integration API Specification v1.2

Basic Explanation

To ensure the security of server transmission information, the following security mechanisms are adopted:

  1. All interfaces use HTTPS secure links.
  2. Officially assigned customer authentication AuthKey, used for authorization and encryption, with a maximum length of 32.
  3. Officially assigned encryption key AuthSecret, used for encryption, with a maximum length of 50.
  4. Ensures the security of requests through SHA-256.

Interface Standards

Base Path:https://api.iroamly.shop/
Request Protocol:HTTPS
Request Method:GET / POST
Data Transfer Format: application/json

Request Header Parameters:

AuthKey: Customer authentication key, type String

Certification: Encrypted string, type String (Result of SHA-256 encryption of accumulated AuthKey+AuthSecret)

Get Regional Plan List

Request URL:https://api.iroamly.shop/common/getPlanItem
Request Method:GET

Request Parameters:

ParameterDescriptionType
regionAccepts ISO2 codes, country names (case-insensitive), or standardized formats (e.g., united-states).String

Response Format:

Success: HTTP 200 with a JSON array of plans.
Failure: HTTP 404 (if region is invalid) or an empty array [].

Response Field Descriptions:

FieldTypeDescription
planPlan name (includes region, type, data allowance, and duration).String
productCodeUnique plan ID for purchasing or queries.String
dataData allowance (e.g., 10GB、Unlimited、500MB).String
typePlan type (e.g., Total、Daily、Unlimited).String
package_typePackage type (e.g., Data Only).String
durationValidity period in days (e.g., 10).String
speedNetwork speed (e.g., 4G / 5G).String
operatorSupported operators (e.g., T-Mobile/AT&T).String
regionOfficial region name (e.g., United States).String
region_indexStandardized region identifier (lowercase with hyphens, e.g., united-states).String
creditPlan price (currency unit not specified; default likely USD).Float
remarkAdditional notes (e.g., speed throttling rules).String
created_atPlan creation timestamp (ISO 8601 format).String
Request Example
"https://api.iroamly.shop/common/getPlanItem?region=US"
Example Return
{
  "code": 0,
  "data": {
    list:[
     {
       "plan": "United States-eSIM-10GB-10 Days-Total",
       "productCode": "iRoamly-unite-584535",
       "data": "10GB",
       "type": "Total",
       "package_type": "Data Only",
       "duration": "10",
       "speed": "4G / 5G",
       "operator": "T-Mobile/AT&T",
       "region": "United States",
       "region_index": "united-states",
       "credit": 6.43,
       "remark": "After accumulating 10GB, the speed will be reduced to 128 Kbps",
       "created_at": "2025-05-16T04:02:31Z"
     }
    ]
  }
}

Purchase Redeem Code

Request URL:https://api.iroamly.shop/openapi/purchaseCode
Request Method:POST

Request Parameters:

ParameterDescriptionType
emailEmailString
productListProduct collectionObject[]

productList Fields:

FieldDescriptionType
planPlan NameString
quantityQuantityInt

Test Plan:iRoamly-Test-10GB

Example Parameters
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
Example Return
{
  "code": 1,
  "msg": "success",
  "orderId": "xxx-xxxx-sd9hn8df333" // Order number, can be used to query redeem code
}

Query Redeem Code

Request URL:https://api.iroamly.shop/openapi/codeQuery

Request Parameters:

ParameterDescriptionType
orderIdOrder numberString
Example Parameters
{
  "orderId": "xxx-xxx-dh239jdu28",
}
Example Return
{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "productCode": "m8hed7h2fed",
      "redeemCode": "3cd2m3f23f3f3",
      "expire_at": "2024-06-30", // Expiry date
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "status": 0
    },
    {
      "productCode": "v2jf28dj2w",
      "redeemCode": "d923j29ef2323",
      "expire_at": "2024-06-30",
      "plan": "Albania-10GB-15 Days-Total",
      "status": 2
    }
  ]
}

Redeem QR Code

(Note: Will be sent to the specified email, the more you redeem, the longer the waiting time)

Request URL:https://api.iroamly.shop/openapi/redeemQRcode

Request Parameters:

ParameterDescriptionType
emailEmailString
codeListCollection of redeem codesObject[]

productList Fields:

FieldDescriptionType
redeemCodeRedeem codeString
Example Parameters
{
  "email": "2m827n32d@gmail.com",
  "codeList": [
    {
      "redeemCode": "m8hed7h2fed",
    },
    {
      "redeemCode": "cn88beg9edj",
    }
  ]
}
Example Return
{
  "code": 1,
  "msg": "success",
}

Query QR Code

Request URL:https://api.iroamly.shop/openapi/qrcodeQuery

Request Parameters:

ParameterDescriptionType
codeRedeem codeString
Example Parameters
{
  "redeemCode": "m8hed7h2fed",
}
Example Return
{
  "code": 1,
  "msg": "success",
  "redeemCode": "m8hed7h2fed",
  "qrcode": "https://dsfjigewafe/qrcode.jpg"
}

Response Status Code Definitions

CodeDescription
1Success
2Request parameter authentication failed
3Parameters not filled as required
4Product code does not exist
5Insufficient balance
6Insufficient balance
7Redeem code has been redeemed or does not exist
-1Request failed

Redeem Code Status Definitions

StatusDescription
0Not redeemed
1Redeeming
2Redeemed
3Redemption failed