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

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

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

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.