> 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/fx/api-create-fx-order.md).

# 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

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

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

```bash
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`).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neox.vn/docs/global/global-collections/integration/fx/api-create-fx-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.