API list

Order API

All endpoints require Authorization: Bearer <secretKey> and X-Api-Key: <publicKey>. Every POST also requires Content-Type: application/json and X-Signature, calculated from the entire request body using checksumKey. Recalculate the signature whenever the body changes. See signature generation. GET requests do not require X-Signature. Data is scoped to the institution and the API key’s test/live mode.

Order and return flow

Create an eSIM or physical SIM order using POST /api/v1/orders; use /orders/recharge for data recharges. Save orderId, trackId, and each subOrderId. Look up GET /orders/:id or receive webhooks to track updates.

Order status is separate from return progress. Successfully delivered orders remain SUCCESS during and after returns. Track returns using returnStatus, hasPendingReturn, hasRefundingReturn, refundAmount, items[].quantityReturned, and returns[]. Only newly created physical SIM orders can be canceled; for successful orders, use the Return Request API.

`status`	`string`	`NEW`, `PROCESSING`, `CONFIRMED`, `DELIVERING`, `SUCCESS`, `ERROR`, `CANCELED`.
`items[].status`	`string`	Same values as the order status.
`returnStatus`	`string`	`NONE`: No returns; `PARTIAL`: partially returned; `FULL`: all remaining quantities have been returned.
`hasPendingReturn`	`boolean`	There is a pending return request.
`hasRefundingReturn`	`boolean`	There is a return request with a refund in progress.

Create order API

The payment account must be eligible for payment and able to cover the order. Physical SIM orders require the institution to have an address and phone number configured. Shipping information is taken from this profile.

Request Headers

X-Signature - required

string

HMAC_SHA256 signature of the entire request body using checksumKey. See signature generation.

Request Body

trackId - required

string

Required string, unique per institution and mode. Reusing an ID is rejected; after a timeout, look up the order before retrying.

items - required

object[]

Required array containing at least one item. All items must have the same product type (eSIM or SIM).

`subTrackId` - required	`string`	Required string, unique within the request.
`sku` - required	`string`	Required SKU of an active product, unique within the request.
`quantity` - required	`number`	Required integer from 1 to 500.

deliveryType

string

Optional: WEBHOOK (default) or EMAIL. Email delivery of eSIMs requires both customer fields below.

customerEmail

string

Valid email address; required for eSIM delivery via EMAIL.

customerName

string

Customer name; required for eSIM delivery via EMAIL.

Responses

201 Created

application/json

Success

success

boolean

Confirms successful order creation; does not confirm completed delivery. success: true confirms order creation, not successful delivery. The initial status is PROCESSING for eSIMs and NEW for physical SIMs. The response does not include eSIM QR codes. Retrieve this data from the order details or delivery webhook.

orderId

string

SimplifyTrip order ID.

trackId

string

Your order reference.

status

string

Processing status. See the endpoint’s flow and conditions.

items

object[]

List of items.

`subOrderId`	`string`	SimplifyTrip item ID; use as orderItemId when requesting a return.
`subTrackId`	`string`	Your item reference.
`sku`	`string`	Product SKU.
`quantity`	`number`	Quantity.
`status`	`string`	Processing status. See the endpoint’s flow and conditions.
`type`	`string`	Product type: eSIM, SIM, or SIM_RECHARGE.

4xx/5xx Error

application/json

Error

`timestamp`	`number`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

POST

/api/v1/orders

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_24import axios from "axios";
_24
_24const response = await axios.request({
_24  method: "POST",
_24  url: "https://merchant.simplifytrip.com/api/v1/orders",
_24  headers: {
_24  "accept": "application/json",
_24  "authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxx",
_24  "x-api-key": "pk_live_xxxxxxxxxxxxxxxxxx",
_24  "content-type": "application/json",
_24  "x-signature": "REPLACE_WITH_SIGNATURE_FOR_THIS_BODY"
_24},
_24  data: {
_24  "trackId": "partner-order-001",
_24  "items": [
_24    {
_24      "subTrackId": "partner-item-001",
_24      "sku": "E23XY06GB08DFX",
_24      "quantity": 2
_24    }
_24  ]
_24}
_24});
_24console.log(response.data);

Sample Response

Success

Error


_16{
_16  "success": true,
_16  "orderId": "658441501843542",
_16  "trackId": "partner-order-001",
_16  "status": "PROCESSING",
_16  "items": [
_16    {
_16      "subOrderId": "6740ce7f9d04259159bc6401",
_16      "subTrackId": "partner-item-001",
_16      "sku": "E23XY06GB08DFX",
_16      "quantity": 2,
_16      "status": "PROCESSING",
_16      "type": "eSIM"
_16    }
_16  ]
_16}

SIM data recharge API

Send a unique trackId and exactly one item containing subTrackId, a SKU of type SIM_RECHARGE, and iccids with 1–50 unique ICCIDs. Quantity is calculated from the ICCIDs; do not send quantity. China Telecom plans support only one ICCID. A successful response has the same structure as order creation, with status: SUCCESS for the order and item, and type: SIM_RECHARGE.

Request Headers

X-Signature - required

string

HMAC_SHA256 signature of the entire request body using checksumKey. See signature generation.

Request Body

trackId - required

string

Order reference, unique per institution and mode.

items - required

object[]

Exactly one item.

subTrackId - required

string

Item reference.

sku - required

string

SKU of type SIM_RECHARGE.

iccids - required

string[]

1–50 unique ICCIDs; China Telecom plans allow only one ICCID.

In TEST_MODE, try the following ICCIDs:

89860012017201244064, 89860012017201244085, 89860012017201244086, 89860012017201244087, 89860012017201244088, 89860012017201244092, 89860012017201244093, 89860012017201244094, 89860012017201244095, 89860012017201244096

Responses

201 Created

application/json

Success

success

boolean

Confirms successful order creation; does not confirm completed delivery.

orderId

string

SimplifyTrip order ID.

trackId

string

Your order reference.

status

string

Processing status. See the endpoint’s flow and conditions.

items

object[]

List of items.

`subOrderId`	`string`	SimplifyTrip item ID; use as orderItemId when requesting a return.
`subTrackId`	`string`	Your item reference.
`sku`	`string`	Product SKU.
`quantity`	`number`	Quantity.
`status`	`string`	Processing status. See the endpoint’s flow and conditions.
`type`	`string`	Product type: eSIM, SIM, or SIM_RECHARGE.

4xx/5xx Error

application/json

Error

`timestamp`	`number`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

POST

/api/v1/orders/recharge

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_26import axios from "axios";
_26
_26const response = await axios.request({
_26  method: "POST",
_26  url: "https://merchant.simplifytrip.com/api/v1/orders/recharge",
_26  headers: {
_26  "accept": "application/json",
_26  "authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxx",
_26  "x-api-key": "pk_live_xxxxxxxxxxxxxxxxxx",
_26  "content-type": "application/json",
_26  "x-signature": "REPLACE_WITH_SIGNATURE_FOR_THIS_BODY"
_26},
_26  data: {
_26  "trackId": "partner-recharge-001",
_26  "items": [
_26    {
_26      "subTrackId": "partner-recharge-item-001",
_26      "sku": "REPLACE_WITH_RECHARGE_SKU",
_26      "iccids": [
_26        "8985200000000000001"
_26      ]
_26    }
_26  ]
_26}
_26});
_26console.log(response.data);

Sample Response

Success

Error


_16{
_16  "success": true,
_16  "orderId": "658441501843542",
_16  "trackId": "partner-recharge-001",
_16  "status": "SUCCESS",
_16  "items": [
_16    {
_16      "subOrderId": "6740ce7f9d04259159bc6401",
_16      "subTrackId": "partner-recharge-item-001",
_16      "sku": "REPLACE_WITH_RECHARGE_SKU",
_16      "quantity": 1,
_16      "status": "SUCCESS",
_16      "type": "SIM_RECHARGE"
_16    }
_16  ]
_16}

Cancel order API

Only physical SIM orders with order status NEW, where all items are of type SIM and have status NEW, can be canceled. orderId is the SimplifyTrip order ID or trackId. reason is optional. Cancellation changes the order and items to CANCELED and refunds the full order amount to the payment account. Ineligible orders return 404.

Request Headers

X-Signature - required

string

HMAC_SHA256 signature of the entire request body using checksumKey. See signature generation.

Request Body

`orderId` - required	`string`	SimplifyTrip order ID or trackId.
`reason`	`string`	Cancellation reason (optional).

Responses

201 Created

application/json

Success

id string

trackId

string

Your order reference.

createdAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

updatedAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

status

string

Processing status. See the endpoint’s flow and conditions.

reason

string

Request/cancellation reason; may be null.

items

object[]

List of items.

`id`	`string`
`subTrackId`	`string`	Your item reference.
`sku`	`string`	Product SKU.
`quantity`	`number`	Quantity.
`type`	`string`	Product type: `SIM_RECHARGE`.
`status`	`string`	Processing status. See the endpoint’s flow and conditions.

4xx/5xx Error

application/json

Error

`timestamp`	`number`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

POST

/api/v1/orders/cancel

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_18import axios from "axios";
_18
_18const response = await axios.request({
_18  method: "POST",
_18  url: "https://merchant.simplifytrip.com/api/v1/orders/cancel",
_18  headers: {
_18  "accept": "application/json",
_18  "authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxx",
_18  "x-api-key": "pk_live_xxxxxxxxxxxxxxxxxx",
_18  "content-type": "application/json",
_18  "x-signature": "REPLACE_WITH_SIGNATURE_FOR_THIS_BODY"
_18},
_18  data: {
_18  "orderId": "658441501843542",
_18  "reason": "Customer canceled"
_18}
_18});
_18console.log(response.data);

Sample Response

Success

Error


_18{
_18  "id": "658441501843542",
_18  "trackId": "partner-order-001",
_18  "createdAt": "2026-09-12T07:00:00.000Z",
_18  "updatedAt": "2026-09-12T07:01:00.000Z",
_18  "status": "CANCELED",
_18  "reason": "Customer canceled",
_18  "items": [
_18    {
_18      "id": "6740ce7f9d04259159bc6401",
_18      "subTrackId": "partner-item-001",
_18      "sku": "REPLACE_WITH_PHYSICAL_SIM_SKU",
_18      "quantity": 2,
_18      "type": "SIM",
_18      "status": "CANCELED"
_18    }
_18  ]
_18}

Get order details API

Use the order ID or unique trackId.

Path Parameters

id - required

string

Order ID or unique trackId.

Responses

200 OK

application/json

Success

id string

trackId

string

Your order reference.

createdAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

confirmedAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

deliveringAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

canceledAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

succeededAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

status

string

Processing status. See the endpoint’s flow and conditions.

returnStatus

string

NONE, PARTIAL, or FULL; separate from the order status.

hasPendingReturn

boolean

There is a pending return request.

hasRefundingReturn

boolean

There is a return request with a refund in progress.

totalBeforeRefund

number

Total amount before returns (VND).

total

number

Remaining total amount after returns (VND).

refundAmount

number

Refund amount (VND); on the order, this is the sum of all completed refunds.

error string

shippingAddress object | null

items

object[]

List of items.

id string

subTrackId

string

Your item reference.

status

string

Processing status. See the endpoint’s flow and conditions.

quantity

number

Quantity.

quantityReturned

number

Quantity successfully returned.

iccids

string[]

List of ICCIDs.

price

number

Unit price (VND).

type

string

Product type: eSIM, SIM, or SIM_RECHARGE.

spu string

sku string

eSims

>object[]

eSIM activation information.

`iccid`	`string`
`planAPN`	`string`
`smdpAddress`	`string`
`pin`	`string`
`puk`	`string`
`activationCode`	`string`
`qrCodeContent`	`string`
`qrCodeImg`	`string`
`returnStatus`	`string`	`NONE` \| `REFUNDING \|` REFUNDED`

returns

object[]

Return history, newest first.

id string

trackId

string

Your order reference.

orderId

string

SimplifyTrip order ID.

orderTrackId

string

Original order reference.

createdAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

rejectedAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

completedAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

canceledAt

datetime | null

ISO timestamp; may be null if the event has not occurred.

status

string

Processing status. See the endpoint’s flow and conditions.

reason

string

Request/cancellation reason; may be null.

rejectionReason

string

Rejection reason; may be null.

returnType

string

FULL or PARTIAL, calculated by the server based on the remaining eligible quantity.

refundFee

number

Base refund fee (VND).

extraFee

number

Additional fee (VND).

extraFeeNote

string

Additional fee note; may be null.

refundAmount

number

Refund amount (VND); on the order, this is the sum of all completed refunds.

items

object[]

List of items.

`id`	`string`
`orderItemId`	`string`	Item ID from the original order.
`subOrderTrackId`	`string`	Item reference from the original order.
`spu`	`string`	Product code (spu in the return-request API).
`sku`	`string`	SKU (sku in the return-request API).
`productType`	`string`	Product type (type in the return-request API).
`returnType`	`string`	FULL or PARTIAL, calculated by the server based on the remaining eligible quantity.
`iccids`	`string[]`	List of ICCIDs. This array is empty for physical SIM returns.
`originalPrice`	`number`	Original unit price (VND).
`quantity`	`number`	Quantity.

4xx/5xx Error

application/json

Error

`timestamp`	`number`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

GET

/api/v1/orders/:id

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_12import axios from "axios";
_12
_12const response = await axios.request({
_12  method: "GET",
_12  url: "https://merchant.simplifytrip.com/api/v1/orders/658441501843542",
_12  headers: {
_12  "accept": "application/json",
_12  "authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxx",
_12  "x-api-key": "pk_live_xxxxxxxxxxxxxxxxxx"
_12}
_12});
_12console.log(response.data);

Sample Response

Success

Error


_90{
_90  "id": "658441501843542",
_90  "trackId": "partner-order-001",
_90  "createdAt": "2026-09-12T07:00:00.000Z",
_90  "confirmedAt": null,
_90  "deliveringAt": null,
_90  "canceledAt": null,
_90  "succeededAt": "2026-09-12T07:00:10.000Z",
_90  "status": "SUCCESS",
_90  "returnStatus": "NONE",
_90  "hasPendingReturn": false,
_90  "hasRefundingReturn": false,
_90  "totalBeforeRefund": 200000,
_90  "total": 200000,
_90  "refundAmount": 0,
_90  "error": null,
_90  "shippingAddress": null,
_90  "items": [
_90    {
_90      "id": "6740ce7f9d04259159bc6401",
_90      "subTrackId": "partner-item-001",
_90      "status": "SUCCESS",
_90      "quantity": 2,
_90      "quantityReturned": 0,
_90      "iccids": [],
_90      "price": 100000,
_90      "type": "eSIM",
_90      "spu": "example-product",
_90      "sku": "E23XY06GB08DFX",
_90      "eSims": [
_90        {
_90          "iccid": "8985200000000000001",
_90          "planAPN": "internet",
_90          "smdpAddress": "example.smdp.com",
_90          "pin": "",
_90          "puk": "",
_90          "activationCode": "EXAMPLE-1",
_90          "qrCodeContent": "LPA:1$example.smdp.com$EXAMPLE-1",
_90          "qrCodeImg": "https://example.com/qr-1.png",
_90          "returnStatus": "NONE"
_90        },
_90        {
_90          "iccid": "8985200000000000002",
_90          "planAPN": "internet",
_90          "smdpAddress": "example.smdp.com",
_90          "pin": "",
_90          "puk": "",
_90          "activationCode": "EXAMPLE-2",
_90          "qrCodeContent": "LPA:1$example.smdp.com$EXAMPLE-2",
_90          "qrCodeImg": "https://example.com/qr-2.png",
_90          "returnStatus": "NONE"
_90        }
_90      ]
_90    }
_90  ],
_90  "returns": [
_90    {
_90      "id": "6aa577e10a519efcfb0e8755",
_90      "returnTrackId": "partner-return-id",
_90      "orderId": "658441501843542",
_90      "orderTrackId": "partner-order-001",
_90      "createdAt": "2026-09-12T16:03:45.714Z",
_90      "completedAt": null,
_90      "canceledAt": null,
_90      "rejectedAt": null,
_90      "reason": "string",
_90      "rejectionReason": null,
_90      "status": "REQUESTED",
_90      "returnType": "PARTIAL",
_90      "refundFee": 15000,
_90      "extraFee": 0,
_90      "extraFeeNote": null,
_90      "refundAmount": 85000,
_90      "items": [
_90        {
_90          "subOrderId": "6aa51f9be25063893dc033fd",
_90          "subOrderTrackId": "11",
_90          "spu": "example-product",
_90          "sku": "E23XY06GB08DFX",
_90          "type": "eSIM",
_90          "returnType": "PARTIAL",
_90          "iccids": [
_90            "8985200000000000001"
_90          ],
_90          "quantity": 1
_90        }
_90      ]
_90    }
_90  ]
_90}

Errors and HTTP status

Successful GET requests return HTTP 200. POST requests currently return HTTP 201. Handle all successful 2xx responses. Validation errors or duplicate references may return 400; missing products/orders or orders ineligible for cancellation return 404; product, shipping, or payment account condition errors return 422; a busy system may return 503.

API list Errors