Create Refund Request

Endpoint: POST /v2/gc/refund-requests

Description: Initiate a refund of an incoming collection order back to the original payer.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
orderId	string	Yes	The orderId of the collection transaction to refund (same value delivered on the collection webhooks).
feeChargeWay	string	Yes	Party responsible for bearing the refund fee. Enum: OUR | BEN.
reason	string(256)	No	Free-text reason for the refund.
requestId	string(64)	No	Merchant-generated unique request ID for this refund, used for idempotency.
webhookUrl	string(256)	No	Merchant-hosted callback URL. See the hint on Webhook — this field is accepted by the DTO, but the actual refund-status events are delivered through the collection-transaction webhook group, not necessarily to this URL.

Business rule (not schema-enforced): a collection transaction is only refundable if its status is WAIT_MATCH/REJ_WAIT_MATCH, or if it's SUCCESS and was credited within the last 7 days.

UI-enforced business rule: the Merchant Portal restricts feeChargeWay to BEN only (hiding OUR and auto-selecting BEN) when the transaction's virtual account is "BEN-only" — defined as: vaRegCountry=HKG AND the VA has more than one currency, OR vaRegCountry=USA. This is not confirmed to be enforced at the API layer independently of the UI.

Request sample

Real captured example:

{
    "requestId": "1785580178393",
    "orderId": "785481516079000004",
    "feeChargeWay": "OUR",
    "reason": "refund gd",
    "webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76"
}

(requestId should be a merchant-generated unique value — the original capture used a client-side templated placeholder.)

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code. Refer to Error Codes.
data	object	Refund request details.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier (UUID).

There is no state field in the response envelope. This response is notably thin per the backend code — it does not return an id or status field, only the four fields below. Poll Get Detail Collection Order or listen for the refund webhooks (see Webhook) to track the outcome.

data object fields:

Field Name	Type	Description
requestId	string	Echoes the merchant-supplied requestId.
orderId	string	The collection transaction's orderId.
refundOrderId	string	NeoX identifier assigned to this refund.
feeChargeWay	string	Echoes the submitted feeChargeWay.

No real captured response sample is available yet — field names above are derived from the backend code; values below are placeholders.

Response sample

{
  "code": 1,
  "data": {
    "requestId": "",
    "orderId": "",
    "refundOrderId": "",
    "feeChargeWay": ""
  },
  "message": "Successful"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/refund-requests" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "1785580178393",
    "orderId": "785481516079000004",
    "feeChargeWay": "OUR",
    "reason": "refund gd",
    "webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76"
  }'

Notes

• Requires Bearer token in the Authorization header.

• The Accept-Language header can be used to specify the response language (Support: "vi", "en").

• Use a unique requestId for each request to avoid duplicate refund submissions.

• There is currently no public GET endpoint for refund-request detail — a getRefundRequestDetail action exists in the backend but is not exposed under /v2/gc/. Track outcomes via Get Detail Collection Order or the webhooks below.

• The final refund outcome is delivered asynchronously via the TRADE_COLLECTION_REFUND_PROCESS/TRADE_COLLECTION_REFUND_SUCCESS webhooks — see Webhook.

• Refund progress can also be observed by polling the related collection transaction — its status transitions to REFUND_PROCESS while the refund is underway and REFUND_SUCCESS upon completion.

• feeChargeWay must be set to OUR if the merchant agrees to bear the refund transfer fee, or BEN if the fee is deducted from the amount returned to the payer.