Order eSIM Profiles

Order new eSIM profiles with data packages for your customers.

Order Profiles

Endpoint: POST /api/v1/open/esim/order

Request Parameters

Name	Type	Required	Description	Example
`transactionId`	String	Required	Your unique transaction ID (max 64 chars)	`order_123456`
`amount`	Integer	Optional	Total order amount * 10,000	`45000`
`packageInfoList`	Array	Required	List of packages to order

Package Info Object

Name	Type	Required	Description	Example
`packageCode`	String	Required	Package code or slug	`TH_1_7`
`count`	Integer	Required	Number of eSIMs to order	`1`
`price`	Integer	Optional	Package price * 10,000	`45000`
`periodNum`	Integer	Optional	Number of days for day pass plans	`3`

Example Request - Single eSIM

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/order' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId": "order_123456",
    "amount": 45000,
    "packageInfoList": [{
        "packageCode": "TH_1_7",
        "count": 1,
        "price": 45000
    }]
}'

Example Request - Multiple eSIMs

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/order' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId": "order_789012",
    "amount": 135000,
    "packageInfoList": [{
        "packageCode": "TH_1_7",
        "count": 3,
        "price": 45000
    }]
}'

Example Request - Day Pass Plan

For day pass plans, include periodNum to specify the number of days.

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/order' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId": "order_daypass_001",
    "packageInfoList": [{
        "packageCode": "JP_DAYPASS_1",
        "count": 1,
        "periodNum": 5
    }]
}'

Response Parameters

Name	Type	Description
`success`	Boolean	`true` = succeeded, `false` = failed
`errorCode`	String	Error code when failed
`errorMsg`	String	Error message
`obj`	Object	Order result data

Order Result Object

Field	Type	Description	Example
`orderNo`	String	Platform order number	`ORD20240101123456`
`transactionId`	String	Your transaction ID	`order_123456`
`orderStatus`	String	Order status	`GOT_RESOURCE`
`profileList`	Array	List of eSIM profiles

Profile Object

Field	Type	Description	Example
`iccid`	String	eSIM ICCID	`8901234567890123456`
`esimTranNo`	String	eSIM transaction number	`ESIM123456`
`packageCode`	String	Package code	`TH_1_7`
`smdpAddress`	String	SM-DP+ server address	`smdp.example.com`
`matchId`	String	eSIM activation code	`XXXX-XXXX-XXXX-XXXX`
`profileStatus`	String	Profile status	`GOT_RESOURCE`
`qrCode`	String	Base64 QR code image	`data:image/png;base64,...`
`appleInstallUrl`	String	Apple direct install URL	`https://esimsetup.apple.com/...`

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "orderNo": "ORD20240101123456",
        "transactionId": "order_123456",
        "orderStatus": "GOT_RESOURCE",
        "profileList": [
            {
                "iccid": "8901234567890123456",
                "esimTranNo": "ESIM123456",
                "packageCode": "TH_1_7",
                "smdpAddress": "smdp.example.com",
                "matchId": "XXXX-XXXX-XXXX-XXXX",
                "profileStatus": "GOT_RESOURCE",
                "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
                "appleInstallUrl": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=..."
            }
        ]
    }
}

Order Status Values

Status	Description
`GOT_RESOURCE`	eSIM profile allocated successfully
`IN_PROGRESS`	Order is being processed
`FAILED`	Order failed
`CANCEL_SUCCESS`	Order cancelled

Profile Status Values

Status	Description
`GOT_RESOURCE`	Profile allocated, ready for download
`ACTIVATED`	Profile downloaded and activated
`IN_USE`	Profile is actively being used
`USED_UP`	Data exhausted
`EXPIRED`	Profile validity expired
`CANCELLED`	Profile cancelled

Error Handling

Insufficient Balance

{
    "errorCode": "200007",
    "errorMsg": "Insufficient account balance",
    "success": false,
    "obj": null
}

Invalid Package

{
    "errorCode": "310241",
    "errorMsg": "The packageCode does not exist",
    "success": false,
    "obj": null
}

Price Mismatch

{
    "errorCode": "200005",
    "errorMsg": "Package price error. Check price",
    "success": false,
    "obj": null
}

Best Practices

Always use unique transactionId - This prevents duplicate orders and allows tracking
Verify prices before ordering - Use the package list API to get current prices
Store the orderNo and iccid - You'll need these for queries and profile management
Handle the QR code - Display to customer for eSIM installation
Use webhooks - Get notified of order status changes

Data Packages Query Profiles