Top Up eSIM

Add additional data to an existing eSIM profile.

Top Up Profile

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

Request Parameters

Name	Type	Required	Description	Example
`transactionId`	String	Required	Your unique transaction ID	`topup_123456`
`iccid`	String	Required	Target eSIM ICCID	`8901234567890123456`
`packageCode`	String	Required	Top-up package code	`TH_TOPUP_1`
`price`	Integer	Optional	Package price * 10,000	`35000`
`amount`	Integer	Optional	Total amount * 10,000	`35000`

Example Request

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/topup' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId": "topup_123456",
    "iccid": "8901234567890123456",
    "packageCode": "TH_TOPUP_1",
    "price": 35000,
    "amount": 35000
}'

Response Parameters

Name	Type	Description
`success`	Boolean	`true` = succeeded, `false` = failed
`errorCode`	String	Error code when failed
`errorMsg`	String	Error message
`obj.orderNo`	String	Top-up order number
`obj.status`	String	Top-up status

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "orderNo": "TOP20240115123456",
        "transactionId": "topup_123456",
        "iccid": "8901234567890123456",
        "status": "SUCCESS",
        "addedVolume": 1073741824,
        "newExpiredTime": "2024-02-15 00:00:00"
    }
}

Finding Top-Up Packages

Before topping up, query available top-up packages for the ICCID:

curl --location --request POST 'https://your-api-domain.com/api/v1/open/package/list' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "type": "TOPUP",
    "iccid": "8901234567890123456"
}'

Or query by the original package code:

curl --location --request POST 'https://your-api-domain.com/api/v1/open/package/list' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "type": "TOPUP",
    "packageCode": "TH_1_7"
}'

Top-Up Compatibility

Country plans: Can be topped up with same country top-up packages
Regional plans: Can be topped up with same region top-up packages
Check supportTopUpType: 2 = Top-up supported, 1 = No top-up available

// Check if package supports top-up
const package = packageList.find(p => p.packageCode === 'TH_1_7');
if (package.supportTopUpType === 2) {
    // Top-up is available for this package
}

Error Handling

ICCID Not Found

{
    "errorCode": "310403",
    "errorMsg": "The ICCID does not exist in the order",
    "success": false,
    "obj": null
}

Top-Up Not Supported

{
    "errorCode": "310243",
    "errorMsg": "The package does not exist",
    "success": false,
    "obj": null
}

Insufficient Balance

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

Best Practices

Check compatibility first - Query available top-up packages before attempting
Use unique transactionId - Prevents duplicate top-ups
Verify current status - Only top-up active profiles
Notify customers - Send confirmation after successful top-up

Balance Query Webhooks