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:

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

Direct purchase QR code

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

Request Parameters:

ParameterDescriptionType
emailThe mailbox for receiving QR codes. If it is empty, no email will be sent.String
productListProduct collectionObject[]

productList Fields:

FieldDescriptionType
planPlan NameString
quantityQuantityInt

Test Plan:iRoamly-Test-10GB

Next step: Use Query QR Code (https://api.iroamly.shop/openapi/qrcodeQuery) to get the QR code

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,
  "data": {
    "orderId": "Open-Global-DXDWFBKG578913",
    "redeem_list": [
      {
        "productCode": "",
        "plan": "United States-eSIM-10GB-10 Days-Total",
        "redeemCode": "tjMxpYfvk5dFMQg",
        "status": 0,
        "expire_at": "2026-03-01"
      },
      {
        "productCode": "",
        "plan": "Albania-10GB-15 Days-Total",
        "redeemCode": "sLSHNkAv2ojbNBG",
        "status": 0,
        "expire_at": "2026-03-01"
      }
    ]
  },
  "msg": "success"
}

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

Get Renewal Plan Status

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

Request Parameters:

ParameterDescriptionType
codeRedeem codeString

Response Field Descriptions:

FieldDescriptionType
code
0 - renewal possible
-1 - renewal not possible
Int
renewtype
You can choose the type of renewal:
0 - Automatically active after expiration
1 - Active immediately (clears remaining data)
2 - Active at a specified time
Int
starttimeWhen setting the time, you can choose the start time.String
endtimeWhen setting the time, you can choose the end time.String
Example Parameters
{
  "code": "3cd2m3f23f3f3",
}
Example Return
{
  "code": 0,
  "data": {
    "renewList": [
      {
        "renewtype": 1,
        "starttime": "",
        "endtime": ""
      },
      {
        "renewtype": 2,
        "starttime": "2025-08-04 06:13:08",
        "endtime": "2025-09-20 14:23:51"
      }
    ],
    "lasttime": "0001-01-01T00:00:00Z"
  },
  "msg": "Success"
}

Renewal Code

(Note: When renewing, the selected "renewal group" must match the original plan's renewal group [renewtype].)

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

Request Parameters:

ParameterDescriptionType
redeemCodeCode that requires renewalString
planRenewal PlanString
renewtype
Renewal Type:
0 - Automatically effective once it expires
1 - Effective immediately (any remaining data is cleared)
2 - Effective at a specified time
Int
renewtimeEffective Date and TimeString
Example Parameters
{
  redeemCode: "DEF456UVW",
  plan: "basic_yearly",
  renewtype: 0,
  renewtime: "2024-12-31T23:59:59Z"
}
Example Return
{
  code: 1,
  data: {
    orderId: "Open-Global-DXDWFBKG578913",
    plan: "United States-eSIM-10GB-10 Days-Total",
    redeemCode: "tjMxpYfvk5dFMQg",
    status: 0,
    expire_at: "2026-03-01"
  },
  msg: "success"
}

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
iRoamly Travel eSIM Wholesale API Documentation