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

# Match Collection and Trade Order

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

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

{% hint style="info" %}
Each entry in `targetOrderList` may optionally carry its own `matchAmount`, but only when `type=COLLECT_MATCH_TRADE` — see the field table below. The response returns one match-result record per source/target pairing in `data.data` — see below.
{% endhint %}

## Request

This single endpoint handles **both directions** of matching, selected via `type`:

| Field Name                     | Type               | Required    | Description                                                                                                                                                                                                                                                                              |
| ------------------------------ | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId                      | string(32)         | Yes         | Merchant-generated unique request ID (idempotency).                                                                                                                                                                                                                                      |
| subMerchantId                  | string(32)         | Conditional | Sub-merchant identifier, if operating on behalf of a sub-merchant. Optional in general; **required when the merchant operates in PSP mode.**                                                                                                                                             |
| type                           | string             | Yes         | Enum: `COLLECT_MATCH_TRADE` (source = a collection transaction's `orderId`, targets = trade orders — this is the primary flow, matching the endpoint's URL name) \| `TRADE_MATCH_COLLECT` (reverse: source = a trade order's `orderId`, targets = collection transactions).              |
| sourceOrderId                  | string(32)         | Yes         | The source record's `orderId`.                                                                                                                                                                                                                                                           |
| targetOrderList                | array (min 1 item) | Yes         | `[{ targetOrderId: string, matchAmount?: number }]` — one or more target order identifiers. Each item's `targetOrderId` is required (max 32 chars); `matchAmount` is optional and only permitted when `type=COLLECT_MATCH_TRADE` (rejected if supplied when `type=TRADE_MATCH_COLLECT`). |
| targetOrderList\[].matchAmount | number             | No          | Amount matched against this specific target order (minimum `0.01`, at most two decimal places). Only permitted when `type=COLLECT_MATCH_TRADE`; supplying it when `type=TRADE_MATCH_COLLECT` is rejected.                                                                                |

Business rules (server-enforced): the source must exist for the calling merchant; every `targetOrderId` must resolve to an existing record; if the connector reports the match as `PROCESSING`, the source and all targets transition to `PROCESSING` status.

#### Request sample

Real captured example:

```json
{
  "requestId": "{{$guid}}",
  "subMerchantId": "10000002",
  "type": "COLLECT_MATCH_TRADE",
  "sourceOrderId": "785745752783000016",
  "targetOrderList": [
    { "targetOrderId": "785745767436000017" }
  ]
}
```

(`requestId` should be a merchant-generated unique value — the capture above used a client-generated UUID template, e.g. from a Postman-style `{{$guid}}` variable.)

### Response

#### Response Field Descriptions

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

#### `data` object fields:

| Field Name | Type   | Description                                                                                                                                                                         |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId  | string | System-generated correlation ID for this match request. Equals `matchRequestId` on each record in `data.data`. Distinct from the merchant-supplied `requestId` in the request body. |
| data       | array  | List of match-result records, one per `targetOrderList` entry.                                                                                                                      |

#### `data.data[]` record fields:

| Field Name                 | Type   | Description                                                                             |
| -------------------------- | ------ | --------------------------------------------------------------------------------------- |
| collectionOrderId          | string | The collection transaction's `orderId` (the source, in the `COLLECT_MATCH_TRADE` flow). |
| matchCurrency              | string | Currency the match was settled in.                                                      |
| fxRate                     | string | FX rate applied for the match, if a conversion occurred.                                |
| usedAmount                 | number | Amount used from the collection order for this match, in `matchCurrency`.               |
| tradeOrderMatchSrcCurrency | string | Currency of the trade order's side of the match.                                        |
| tradeOrderId               | string | The trade order's identifier (the target, in the `COLLECT_MATCH_TRADE` flow).           |
| tradeOrderMatchSrcAmount   | number | Amount matched against the trade order, in `tradeOrderMatchSrcCurrency`.                |
| matchRequestId             | string | Correlation ID for this match request; equals the parent `data.requestId`.              |
| matchAmount                | number | Matched amount for this source/target pairing.                                          |
| status                     | string | Status of this match record (e.g. `PROCESSING`).                                        |

#### Response sample

Real captured example:

```json
{
    "code": 1,
    "data": {
        "requestId": "1785745774526",
        "data": [
            {
                "collectionOrderId": "785745752783000016",
                "matchCurrency": "USD",
                "fxRate": "1",
                "usedAmount": 102,
                "tradeOrderMatchSrcCurrency": "USD",
                "tradeOrderId": "785745767436000017",
                "tradeOrderMatchSrcAmount": 102,
                "matchRequestId": "1785745774526",
                "matchAmount": 102,
                "status": "PROCESSING"
            }
        ]
    },
    "message": "Successful",
    "neoResponseId": "5dc6bfc1-8ef0-4eb4-80f2-2e3546148da2"
}
```

### 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 match operation.
* When `type=COLLECT_MATCH_TRADE`, set `sourceOrderId` to a collection transaction's `orderId` and each `targetOrderList[].targetOrderId` to a trade order's identifier.
* When `type=TRADE_MATCH_COLLECT`, set `sourceOrderId` to a trade order's identifier and each `targetOrderList[].targetOrderId` to a collection transaction's `orderId`.
* Poll [Get Detail Collection Order](/docs/global/global-collections/integration/collections/get-detail-collection-order.md) to track the resulting match status.