> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/refund-requests/api-create-refund-request.md).

# 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

```json
{
  "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](/docs/global/global-collections/integration/error-codes.md). |
| 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

```json
{
  "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

```bash
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.