> 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/payout-requests/api-payout-inquiry.md). # Payout Inquiry #### Endpoint: POST /v2/gc/payout-requests/inquiry #### Description: Lock an FX rate and fees for an upcoming cross-currency payout, returning a short-lived quote token to be used when creating the payout request. ## Request #### Request Body Field Descriptions (JSON) | Field Name | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | requestId | string | Yes | Unique request ID (*UUID recommended*) used for idempotency. | | originCurrency | string | Yes | ISO 4217 currency code of the source (sending) currency (e.g. `USD`). | | targetCurrency | string | Yes | ISO 4217 currency code of the destination (receiving) currency (e.g. `CNH`). | | tradeSide | string | Yes | Determines which side the `amount` refers to. Enum: `CUSTOMER_SELL` (pay-amount based) \| `CUSTOMER_BUY` (receive-amount based). | | amount | number | Yes | Payout amount. Interpreted as the origin amount when `tradeSide=CUSTOMER_SELL`, or the target amount when `tradeSide=CUSTOMER_BUY`. | | payeeRequestId | string | Yes | Identifier of the registered beneficiary (payee) for whom the inquiry is being performed. | | pobo | string | No | Pay-on-behalf-of flag. Enum: `N` (default) \| `Y`. | | feeBear | string | No | Fee-bearing arrangement. Enum: `SHA` (shared) \| `OUR` (sender bears all fees). | #### Request sample ```json { "requestId": "a1b2c3d4-1111-2222-3333-aabbccddeeff", "originCurrency": "USD", "targetCurrency": "CNH", "tradeSide": "CUSTOMER_SELL", "amount": 5000.00, "payeeRequestId": "SUP-20240801-00098765", "pobo": "N", "feeBear": "SHA" } ``` ### Response #### Response Field Descriptions | Field Name | Type | Description | | ------------- | ------ | -------------------------------------------- | | code | number | Response code. | | state | number | State of the response. | | data | object | FX inquiry result including the quote token. | | message | string | Response message. | | neoResponseId | string | Unique NeoX response identifier. | #### `data` object fields: | Field Name | Type | Description | | ----------------- | ----------- | ---------------------------------------------------------------------------------------------------- | | token | string | Short-lived quote token. Pass this value in the `token` field of Create Payout Request. | | exchangeRate | number | Locked FX rate between `originCurrency` and `targetCurrency`. | | originAmount | number | Amount in the origin (sending) currency. | | targetAmount | number | Amount in the target (receiving) currency after conversion. | | feeAmount | number | Transaction fee amount charged in `feeCurrency`. | | feeCurrency | string | ISO 4217 currency code in which the fee is denominated. | | targetFeeAmount | number | Fee amount expressed in the target currency. | | targetFeeCurrency | string | ISO 4217 currency code of the target-side fee. | | targetFeeFxRate | number | FX rate applied when converting the fee to the target currency. | | expireTime | date string | Timestamp after which the `token` is no longer valid (ISO 8601). Submit the payout before this time. | #### Response sample ```json { "code": 1, "state": 2, "data": { "token": "INQ-TOKEN-7f3a9c2b-ee41-4d8e-91fa-0012ab34cd56", "exchangeRate": 7.2815, "originAmount": 5000.00, "targetAmount": 36407.50, "feeAmount": 15.00, "feeCurrency": "USD", "targetFeeAmount": 109.22, "targetFeeCurrency": "CNH", "targetFeeFxRate": 7.2815, "expireTime": "2024-08-15T10:15:00Z" }, "message": "Successful", "neoResponseId": "ac23ea1c-98db-4ed6-b927-7e7692ef2f69" } ``` ## Example cURL ```bash curl -X POST "https://{base_url_openapi}/v2/gc/payout-requests/inquiry" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept-Language: en" \ -d '{ "requestId": "a1b2c3d4-1111-2222-3333-aabbccddeeff", "originCurrency": "USD", "targetCurrency": "CNH", "tradeSide": "CUSTOMER_SELL", "amount": 5000.00, "payeeRequestId": "SUP-20240801-00098765", "pobo": "N", "feeBear": "SHA" }' ``` ### 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 inquiries. * The returned `token` is short-lived; pass it to the `token` field of the Create Payout Request API before `expireTime` is reached. * `tradeSide=CUSTOMER_SELL` means the `amount` is in the origin currency (you specify how much to send); `tradeSide=CUSTOMER_BUY` means the `amount` is in the target currency (you specify how much the beneficiary receives). * This endpoint is optional; omit it for same-currency payouts or when rate locking is not required. --- # 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/payout-requests/api-payout-inquiry.md?ask= ``` 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.