Profile Management

Manage the lifecycle of eSIM profiles including cancellation, suspension, and revocation.

Cancel Profile

Cancel an unused eSIM profile before it's downloaded. Funds will be refunded.

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

Request Parameters

Name	Type	Required	Description
`orderNo`	String	Required*	Platform order number
`esimTranNo`	String	Required*	eSIM transaction number

Provide either orderNo OR esimTranNo, not both. Cancellation is only allowed before the profile is downloaded/activated.

Example Request - Cancel by Order Number

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/cancel' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "orderNo": "ORD20240101123456"
}'

Example Request - Cancel by eSIM Transaction Number

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/cancel' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "esimTranNo": "ESIM123456"
}'

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "orderNo": "ORD20240101123456",
        "status": "CANCEL_SUCCESS",
        "refundAmount": 45000
    }
}

Suspend Profile

Temporarily suspend an active eSIM profile. The profile can be unsuspended later.

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

Request Parameters

Name	Type	Required	Description
`iccid`	String	Required	eSIM ICCID

Example Request

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

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "iccid": "8901234567890123456",
        "status": "SUSPENDED"
    }
}

Unsuspend Profile

Reactivate a previously suspended eSIM profile.

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

Request Parameters

Name	Type	Required	Description
`iccid`	String	Required	eSIM ICCID

Example Request

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

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "iccid": "8901234567890123456",
        "status": "ACTIVATED"
    }
}

Revoke Profile

Permanently revoke an eSIM profile. This action cannot be undone. No refund will be issued.

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

Request Parameters

Name	Type	Required	Description
`iccid`	String	Required	eSIM ICCID

Warning: Revoking a profile is permanent. The profile will be disabled and cannot be reactivated.

Example Request

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

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "iccid": "8901234567890123456",
        "status": "REVOKED"
    }
}

Status Lifecycle

GOT_RESOURCE → ACTIVATED → IN_USE → USED_UP
                  ↓           ↓        ↓
              SUSPENDED ← (can unsuspend)
                  ↓
              REVOKED (permanent)

CANCEL_SUCCESS ← GOT_RESOURCE (before download)

Action	Allowed From Status	Result Status
Cancel	`GOT_RESOURCE`	`CANCEL_SUCCESS`
Suspend	`ACTIVATED`, `IN_USE`	`SUSPENDED`
Unsuspend	`SUSPENDED`	`ACTIVATED`
Revoke	Any active status	`REVOKED`

Error Handling

Cannot Cancel Activated Profile

{
    "errorCode": "200002",
    "errorMsg": "This operation is not allowed due to the order status",
    "success": false,
    "obj": null
}

Profile Not Found

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

Query Profiles Balance Query