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