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.

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.

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:

{
  "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:

{
    "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 to track the resulting match status.