API list

Return request 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 complete request body using your checksumKey. Recalculate the signature whenever the body changes. See signature generation. GET requests do not require X-Signature. Data is scoped to your institution and the API key’s test/live mode.

Return flow

Read the order details and select eligible items from a SUCCESS order.
Create a return with a new returnTrackId and explicit items.
A manual request starts at REQUESTED;
Poll the return details or process RETURN_ORDER_UPDATE webhooks. REFUNDING means processing; COMPLETED means the return has completed.
Refresh order details to obtain cumulative returned quantities, refund amount and remaining total.

Return request statuses

`REQUESTED`	Waiting for review; may be canceled.
`REFUNDING`	Refund processing; cannot be canceled.
`COMPLETED`	Return completed. A positive refund creates a payment account credit transaction, processed asynchronously.
`REJECTED`	Rejected; inspect `rejectionReason`.
`CANCELED`	Canceled while awaiting review.

Eligibility

Order and selected items must be SUCCESS, within 6 months of order creation, and belong to the same institution/mode.
Only one pending or refunding request may exist for an order at a time. A new request can be created once the previous request has reached the COMPLETED or CANCELED/REJECTED status.
Exclude quantities and ICCIDs already reserved or returned by requests other than CANCELED/REJECTED. eSIMs must also have return status NONE.
To return everything, explicitly include all remaining eligible quantities/ICCIDs. The server calculates FULL or PARTIAL against the remaining eligible units.

Fees and processing

The current base fee is 15,000 VND per returned eSIM or physical SIM; SIM recharge has no base return fee. Each item’s initial refund is max(unit price × returned quantity − return fee, 0). The request sums these amounts; an order with a non-positive total has request-level refund fee and amount set to zero. Review may add extraFee with extraFeeNote; use the API’s final refundAmount for reconciliation.

The example returns one of two eSIMs priced at 100,000 VND each: base fee 15,000 VND, refund 85,000 VND.

Create return request API

Request Headers

X-Signature - required

string

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

Request Body

returnTrackId - required

string

Required non-empty string, unique per institution and mode. It is separate from the original order’s trackId.

orderId - required

string

Required non-empty string: SimplifyTrip order ID or original order trackId.

reason

string

Optional string.

items - required

object[]

Required array with at least one item. Include each order item once; do not submit both its ID and its tracking reference as separate entries.

`subOrderId` - required	`string`	Required: `subOrderId` from creation, `items[].id` from order details, or the item’s `subTrackId`. Prefer the SimplifyTrip item ID.
`quantity`	`number`	For physical `SIM`: positive integer, no more than the remaining eligible quantity.
`iccids`	`string[]`	For `eSIM` or `SIM_RECHARGE`: non-empty array of unique ICCID strings belonging to the item and still eligible. The server derives quantity from this array. For physical SIM, send quantity instead.

Responses

201 Created

application/json

Success

id

string

SimplifyTrip return request ID.

returnTrackId

string

Your return tracking reference.

orderId

string

SimplifyTrip order ID.

orderTrackId

string

Original order tracking reference.

createdAt

datetime | null

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

refundingAt

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.

rejectedAt

datetime | null

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

reason

string

Request or cancellation reason; may be null.

rejectionReason

string

Rejection reason; may be null.

status

string

Processing status. See the flow and conditions for this endpoint.

returnType

string

FULL or PARTIAL, calculated by the server against remaining eligible units.

refundFee

number

Base return fee (VND).

extraFee

number

Extra fee (VND).

extraFeeNote

string

Extra fee explanation; may be null.

refundAmount

number

Refund amount (VND); on an order, the cumulative amount of completed refunds.

items

object[]

Item list.

`subOrderId`	`string`	Original order item ID.
`subOrderTrackId`	`string`	Original order item tracking reference.
`spu`	`string`	Product ID.
`sku`	`string`	Product SKU.
`type`	`string`	Product type: eSIM, SIM or SIM_RECHARGE.
`returnType`	`string`	FULL or PARTIAL, calculated by the server against remaining eligible units.
`iccids`	`string[]`	ICCID list. Empty for physical SIM returns.
`quantity`	`number`	Quantity.

4xx/5xx Error

application/json

Error

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

POST

/api/v1/return-requests

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_27import axios from "axios";
_27
_27const response = await axios.request({
_27  method: "POST",
_27  url: "https://merchant.simplifytrip.com/api/v1/return-requests",
_27  headers: {
_27  "accept": "application/json",
_27  "authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxx",
_27  "x-api-key": "pk_live_xxxxxxxxxxxxxxxxxx",
_27  "content-type": "application/json",
_27  "x-signature": "REPLACE_WITH_SIGNATURE_FOR_THIS_BODY"
_27},
_27  data: {
_27  "returnTrackId": "partner-return-001",
_27  "orderId": "658441501843542",
_27  "reason": "Customer requested a return",
_27  "items": [
_27    {
_27      "subOrderId": "6740ce7f9d04259159bc6401",
_27      "iccids": [
_27        "8985200000000000001"
_27      ]
_27    }
_27  ]
_27}
_27});
_27console.log(response.data);

Physical SIM body

SIM


_10{
_10  "returnTrackId": "partner-return-sim-001",
_10  "orderId": "658441501843542",
_10  "items": [
_10    {
_10      "subOrderId": "6740ce7f9d04259159bc6401",
_10      "quantity": 1
_10    }
_10  ]
_10}

Sample Response

Success

Error


_33{
_33  "id": "6741ae68e65369e169a70757",
_33  "returnTrackId": "partner-return-001",
_33  "orderId": "658441501843542",
_33  "orderTrackId": "partner-order-001",
_33  "createdAt": "2026-09-12T08:00:00.000Z",
_33  "refundingAt": null,
_33  "completedAt": null,
_33  "canceledAt": null,
_33  "rejectedAt": null,
_33  "reason": "Customer requested a return",
_33  "rejectionReason": null,
_33  "status": "REQUESTED",
_33  "returnType": "PARTIAL",
_33  "refundFee": 15000,
_33  "extraFee": 0,
_33  "extraFeeNote": null,
_33  "refundAmount": 85000,
_33  "items": [
_33    {
_33      "subOrderId": "6740ce7f9d04259159bc6401",
_33      "subOrderTrackId": "partner-item-001",
_33      "spu": "example-product",
_33      "sku": "E23XY06GB08DFX",
_33      "type": "eSIM",
_33      "returnType": "PARTIAL",
_33      "iccids": [
_33        "8985200000000000001"
_33      ],
_33      "quantity": 1
_33    }
_33  ]
_33}

Cancel refund request API

Send required string returnId, containing either the SimplifyTrip return ID or your returnTrackId. Only REQUESTED can be canceled. This endpoint also requires a signature of the cancel body.

Request Headers

X-Signature - required

string

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

Request Body

returnId - required

string

SimplifyTrip return ID or your returnTrackId.

Returns the same response schema with status: CANCELED and canceledAt populated. It clears the order’s pending/refunding flags and releases the selected eSIMs for later requests. It does not cancel the original order or complete a refund.

Responses

201 Created

application/json

Success

id

string

SimplifyTrip return request ID.

returnTrackId

string

Your return tracking reference.

orderId

string

SimplifyTrip order ID.

orderTrackId

string

Original order tracking reference.

createdAt

datetime | null

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

refundingAt

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.

rejectedAt

datetime | null

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

reason

string

Request or cancellation reason; may be null.

rejectionReason

string

Rejection reason; may be null.

status

string

Processing status. See the flow and conditions for this endpoint.

returnType

string

FULL or PARTIAL, calculated by the server against remaining eligible units.

refundFee

number

Base return fee (VND).

extraFee

number

Extra fee (VND).

extraFeeNote

string

Extra fee explanation; may be null.

refundAmount

number

Refund amount (VND); on an order, the cumulative amount of completed refunds.

items

object[]

Item list.

`subOrderId`	`string`	Original order item ID.
`subOrderTrackId`	`string`	Original order item tracking reference.
`spu`	`string`	Product ID.
`sku`	`string`	Product SKU.
`type`	`string`	Product type: eSIM, SIM or SIM_RECHARGE.
`returnType`	`string`	FULL or PARTIAL, calculated by the server against remaining eligible units.
`iccids`	`string[]`	ICCID list. Empty for physical SIM returns.
`quantity`	`number`	Quantity.

4xx/5xx Error

application/json

Error

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

POST

/api/v1/return-requests/cancel

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_17import axios from "axios";
_17
_17const response = await axios.request({
_17  method: "POST",
_17  url: "https://merchant.simplifytrip.com/api/v1/return-requests/cancel",
_17  headers: {
_17  "accept": "application/json",
_17  "authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxx",
_17  "x-api-key": "pk_live_xxxxxxxxxxxxxxxxxx",
_17  "content-type": "application/json",
_17  "x-signature": "REPLACE_WITH_SIGNATURE_FOR_THIS_BODY"
_17},
_17data: {
_17  "returnId": "6741ae68e65369e169a70757"
_17}
_17});
_17console.log(response.data);

Sample Response

Success

Error


_33{
_33  "id": "6741ae68e65369e169a70757",
_33  "returnTrackId": "partner-return-001",
_33  "orderId": "658441501843542",
_33  "orderTrackId": "partner-order-001",
_33  "createdAt": "2026-09-12T08:00:00.000Z",
_33  "refundingAt": null,
_33  "completedAt": null,
_33  "canceledAt": "2026-09-12T08:01:00.000Z",
_33  "rejectedAt": null,
_33  "reason": "Customer requested a return",
_33  "rejectionReason": null,
_33  "status": "CANCELED",
_33  "returnType": "PARTIAL",
_33  "refundFee": 15000,
_33  "extraFee": 0,
_33  "extraFeeNote": null,
_33  "refundAmount": 85000,
_33  "items": [
_33    {
_33      "subOrderId": "6740ce7f9d04259159bc6401",
_33      "subOrderTrackId": "partner-item-001",
_33      "spu": "example-product",
_33      "sku": "E23XY06GB08DFX",
_33      "type": "eSIM",
_33      "returnType": "PARTIAL",
_33      "iccids": [
_33        "8985200000000000001"
_33      ],
_33      "quantity": 1
_33    }
_33  ]
_33}

Get refund request details API

Use returnId or returnTrackId. Returns the same schema as creation, with the latest status, fees and timestamps. After a create timeout or duplicate-reference error, query this endpoint using the existing reference before deciding to create another request.

Path Parameters

id - required

string

The request’s returnId or returnTrackId.

Responses

200 OK

application/json

Success

id

string

SimplifyTrip return request ID.

returnTrackId

string

Your return tracking reference.

orderId

string

SimplifyTrip order ID.

orderTrackId

string

Original order tracking reference.

createdAt

datetime | null

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

refundingAt

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.

rejectedAt

datetime | null

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

reason

string

Request or cancellation reason; may be null.

rejectionReason

string

Rejection reason; may be null.

status

string

Processing status. See the flow and conditions for this endpoint.

returnType

string

FULL or PARTIAL, calculated by the server against remaining eligible units.

refundFee

number

Base return fee (VND).

extraFee

number

Extra fee (VND).

extraFeeNote

string

Extra fee explanation; may be null.

refundAmount

number

Refund amount (VND); on an order, the cumulative amount of completed refunds.

items

object[]

Item list.

`subOrderId`	`string`	Original order item ID.
`subOrderTrackId`	`string`	Original order item tracking reference.
`spu`	`string`	Product ID.
`sku`	`string`	Product SKU.
`type`	`string`	Product type: eSIM, SIM or SIM_RECHARGE.
`returnType`	`string`	FULL or PARTIAL, calculated by the server against remaining eligible units.
`iccids`	`string[]`	ICCID list. Empty for physical SIM returns.
`quantity`	`number`	Quantity.

4xx/5xx Error

application/json

Error

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

GET

/api/v1/return-requests/: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/return-requests/6741ae68e65369e169a70757",
_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


_33{
_33  "id": "6741ae68e65369e169a70757",
_33  "returnTrackId": "partner-return-001",
_33  "orderId": "658441501843542",
_33  "orderTrackId": "partner-order-001",
_33  "createdAt": "2026-09-12T08:00:00.000Z",
_33  "refundingAt": null,
_33  "completedAt": null,
_33  "canceledAt": null,
_33  "rejectedAt": null,
_33  "reason": "Customer requested a return",
_33  "rejectionReason": null,
_33  "status": "REQUESTED",
_33  "returnType": "PARTIAL",
_33  "refundFee": 15000,
_33  "extraFee": 0,
_33  "extraFeeNote": null,
_33  "refundAmount": 85000,
_33  "items": [
_33    {
_33      "subOrderId": "6740ce7f9d04259159bc6401",
_33      "subOrderTrackId": "partner-item-001",
_33      "spu": "example-product",
_33      "sku": "E23XY06GB08DFX",
_33      "type": "eSIM",
_33      "returnType": "PARTIAL",
_33      "iccids": [
_33        "8985200000000000001"
_33      ],
_33      "quantity": 1
_33    }
_33  ]
_33}

Errors and HTTP status

GET succeeds with HTTP 200; POST currently uses HTTP 201. Validation, duplicate returnTrackId, duplicate items, expired/fully returned orders, an existing active request, unavailable quantities/ICCIDs or canceling a non-REQUESTED request return 400. A missing or non-SUCCESS order and a missing return request return 404.

API list Errors