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
requestId	string	Yes	Merchant-generated unique request ID (UUID recommended) used for idempotency.
collectionOrderId	string	Yes	The NeoX identifier of the collection order to refund.
feeChargeWay	string	Yes	Party responsible for bearing the refund fee. Enum: OUR (merchant bears fee) or BEN (payer bears fee).
subMerchantId	string	No	Sub-merchant identifier. Required when operating on behalf of a sub-merchant.

Request sample

{
  "requestId": "a3f1c2d4-1234-4e56-b789-0abc12345678",
  "collectionOrderId": "CO-20240501-000123456",
  "feeChargeWay": "OUR",
  "subMerchantId": "SUB-MERCH-00091"
}

Response

Response Field Descriptions

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

data object fields:

Field Name	Type	Description
collectionOrderId	string	The NeoX collection order ID associated with this refund.
refundRequestId	string	Unique NeoX identifier for the refund request.
status	string	Initial processing status of the refund request. Enum: PROCESSING | SUCCESS | FAILED.

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "collectionOrderId": "CO-20240501-000123456",
    "refundRequestId": "RF-20240501-000987654",
    "status": "PROCESSING"
  },
  "message": "Successful",
  "neoResponseId": "ac23ea1c-98db-4ed6-b927-7e7692ef2f69"
}

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": "a3f1c2d4-1234-4e56-b789-0abc12345678",
    "collectionOrderId": "CO-20240501-000123456",
    "feeChargeWay": "OUR",
    "subMerchantId": "SUB-MERCH-00091"
  }'

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.

• The final refund outcome is delivered asynchronously via the REFUND webhook event; subscribe to it at your notifyUrl.

• Refund progress can also be observed by polling the related collection order — the order status will transition 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.