> 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/trade-orders/api-match-collection-trade-order.md).

# Match Collection and Trade Order

#### Endpoint: POST /v2/gc/trade-orders/match

#### Description: Match a collection order to one or more trade orders, or a trade order to one or more collection orders, to associate incoming funds with their commercial background.

## Request

#### Request Body Field Descriptions (JSON)

| Field Name      | Type   | Required | Description                                                                                                                                                                    |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| requestId       | string | Yes      | Merchant-generated unique request ID (*UUID recommended*). Used for idempotency.                                                                                               |
| type            | string | Yes      | Direction of the match. Enum: `COLLECT_MATCH_TRADE` (match a collection order to trade orders), `TRADE_MATCH_COLLECT` (match a trade order to collection orders).              |
| sourceOrderId   | string | Yes      | Identifier of the source order driving the match. When `type=COLLECT_MATCH_TRADE`, supply the `collectionOrderId`; when `type=TRADE_MATCH_COLLECT`, supply the `tradeOrderId`. |
| targetOrderList | array  | Yes      | List of target orders to match against the source. See `targetOrderList` object item fields below.                                                                             |
| subMerchantId   | string | No       | Sub-merchant identifier. Required when operating on behalf of a sub-merchant.                                                                                                  |

#### `targetOrderList` object item fields:

| Field Name    | Type   | Required | Description                                                                                                                                              |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetOrderId | string | Yes      | Identifier of the target order. When `type=COLLECT_MATCH_TRADE`, supply a `tradeOrderId`; when `type=TRADE_MATCH_COLLECT`, supply a `collectionOrderId`. |
| matchAmount   | number | Yes      | Amount to be matched against this target order, in the collection order currency.                                                                        |

#### Request sample

```json
{
  "requestId": "d4e5f6a7-8901-4bcd-ef23-456789012345",
  "type": "COLLECT_MATCH_TRADE",
  "sourceOrderId": "CO-20240302-000091",
  "targetOrderList": [
    {
      "targetOrderId": "TO-20240301-000182",
      "matchAmount": 15800.00
    }
  ]
}
```

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                      |
| ------------- | ------ | -------------------------------- |
| code          | number | Response code.                   |
| state         | number | State of the response.           |
| data          | object | Match operation result.          |
| message       | string | Response message.                |
| neoResponseId | string | Unique NeoX response identifier. |

#### `data` object fields:

| Field Name | Type  | Description                                                            |
| ---------- | ----- | ---------------------------------------------------------------------- |
| docs       | array | List of individual match results. See `docs` object item fields below. |

#### `docs` object item fields:

| Field Name        | Type   | Description                                                                          |
| ----------------- | ------ | ------------------------------------------------------------------------------------ |
| collectionOrderId | string | NeoX identifier of the collection (incoming-funds) order involved in this match.     |
| tradeOrderId      | string | NeoX identifier of the trade order involved in this match.                           |
| usedAmount        | number | Cumulative amount of the trade order already consumed by previous matches.           |
| status            | string | Status of this individual match result. Enum: `PROCESSING`, `SUCCESS`, `REJECT`.     |
| matchAmount       | number | Amount matched between the collection order and the trade order in this operation.   |
| matchCurrency     | string | Currency used for the match amount (e.g. `USD`, `EUR`, `HKD`).                       |
| fxRate            | number | Foreign exchange rate applied when the collection and trade order currencies differ. |

#### Response sample

```json
{
  "code": 1,
  "state": 2,
  "data": {
    "docs": [
      {
        "collectionOrderId": "CO-20240302-000091",
        "tradeOrderId": "TO-20240301-000182",
        "usedAmount": 0.00,
        "status": "PROCESSING",
        "matchAmount": 15800.00,
        "matchCurrency": "USD",
        "fxRate": 1.0
      }
    ]
  },
  "message": "Successful",
  "neoResponseId": "e5f6a7b8-9012-4cde-f345-6789012345ab"
}
```

## Example cURL

```bash
curl -X POST "https://{base_url_openapi}/v2/gc/trade-orders/match" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "d4e5f6a7-8901-4bcd-ef23-456789012345",
    "type": "COLLECT_MATCH_TRADE",
    "sourceOrderId": "CO-20240302-000091",
    "targetOrderList": [
      {
        "targetOrderId": "TO-20240301-000182",
        "matchAmount": 15800.00
      }
    ]
  }'
```

### 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 match operations.
* The request body must be in JSON format.
* When `type=COLLECT_MATCH_TRADE`, set `sourceOrderId` to a `collectionOrderId` and each `targetOrderList[].targetOrderId` to a `tradeOrderId`.
* When `type=TRADE_MATCH_COLLECT`, set `sourceOrderId` to a `tradeOrderId` and each `targetOrderList[].targetOrderId` to a `collectionOrderId`.
* Match results are returned asynchronously; a `status=PROCESSING` entry in `docs` will transition to `SUCCESS` or `REJECT`. Poll using the Get Detail Collection Order or Get Detail Trade Order endpoints to track the final outcome.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.neox.vn/docs/global/global-collections/integration/trade-orders/api-match-collection-trade-order.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.