> 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                                                                                                                                                                                                                                                                                           |
| ------------ | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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](/docs/global/global-collections/integration/refund-requests/webhook.md) — 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. |

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

#### Request sample

Real captured example:

```json
{
    "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](/docs/global/global-collections/integration/error-codes.md). |
| data          | object | Refund request details.                                                                            |
| message       | string | Response message.                                                                                  |
| neoResponseId | string | Unique NeoX response identifier (UUID).                                                            |

{% hint style="warning" %}
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](/docs/global/global-collections/integration/collections/get-detail-collection-order.md) or listen for the refund webhooks (see [Webhook](/docs/global/global-collections/integration/refund-requests/webhook.md)) to track the outcome.
{% endhint %}

#### `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

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

## 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": "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](/docs/global/global-collections/integration/collections/get-detail-collection-order.md) or the webhooks below.
* The final refund outcome is delivered asynchronously via the `TRADE_COLLECTION_REFUND_PROCESS`/`TRADE_COLLECTION_REFUND_SUCCESS` webhooks — see [Webhook](/docs/global/global-collections/integration/refund-requests/webhook.md).
* 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.