Create FX Order

Endpoint: POST /v2/gc/fx/orders

Description: Execute a currency-conversion trade against a locked FX rate token obtained from the FX Inquiry API.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string	Yes	Unique request ID (UUID recommended) used for idempotency.
token	string	Yes	FX rate lock token obtained from the FX Inquiry API (POST /v2/gc/fx/inquiry). Must not be expired.
notifyUrl	string	No	Callback URL to receive the FX order result webhook notification when the trade outcome is available.

Request sample

{
  "requestId": "d4e5f6a7-4444-5555-6666-ddeeff001122",
  "token": "FX-TOKEN-9e1f2a3b-cc44-5d6e-bf7a-8899aabbcc00",
  "notifyUrl": "https://merchant.example.com/webhooks/fx-order"
}

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
state	number	State of the response.
data	object	FX order submission result.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier.

data object fields:

Field Name	Type	Description
fxOrderId	string	NeoX identifier for this FX order. Use this to track the trade and delivery status.
requestId	string	Echo of the requestId submitted in the request.
serialNum	string	Platform serial number assigned to this FX trade.
status	string	Initial processing status of the FX order (e.g. PROCESSING).

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "fxOrderId": "FX-20240815-00223344",
    "requestId": "d4e5f6a7-4444-5555-6666-ddeeff001122",
    "serialNum": "SN2024081500223344",
    "status": "PROCESSING"
  },
  "message": "Successful",
  "neoResponseId": "ac23ea1c-98db-4ed6-b927-7e7692ef2f69"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/fx/orders" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "d4e5f6a7-4444-5555-6666-ddeeff001122",
    "token": "FX-TOKEN-9e1f2a3b-cc44-5d6e-bf7a-8899aabbcc00",
    "notifyUrl": "https://merchant.example.com/webhooks/fx-order"
  }'

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 FX order submissions.

• The token must be obtained from the FX Inquiry API (POST /v2/gc/fx/inquiry) and submitted before its fxRateExpireDt expiry.

• The trade outcome is delivered asynchronously via webhook to the notifyUrl if provided. Poll the result using the Get Detail FX Order API (GET /v2/gc/fx/orders/{requestId}) or track settlement via the Get FX Delivery Status API (GET /v2/gc/fx/orders/{requestId}/delivery).