> 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: GET /v2/gc/payment-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.

{% hint style="info" %}
This endpoint uses method **`GET`** with query parameters (not `POST` with a JSON body).
{% endhint %}

## Request

#### Request Params Field Descriptions (query string)

| 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      | The `requestId` of the registered beneficiary (payee) for whom the inquiry is being performed.                                      |
| subMerchantId  | string | No       | Sub-merchant identifier, if applicable.                                                                                             |
| 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).                                                     |

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| code          | number | Response code.                               |
| 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/lock token. Pass this value in the `token` field of [Create Payout Request](/docs/global/global-collections/integration/payout-requests/api-create-payout-request.md). Cached server-side for approximately **55 seconds** — submit the payout before it expires. |
| requestId         | string | Echo of the `requestId` submitted in the request.                                                                                                                                                                                                                                   |
| originCurrency    | string | ISO 4217 currency code of the source (sending) currency.                                                                                                                                                                                                                            |
| targetCurrency    | string | ISO 4217 currency code of the destination (receiving) currency.                                                                                                                                                                                                                     |
| originAmount      | string | Amount in the origin (sending) currency.                                                                                                                                                                                                                                            |
| targetAmount      | string | Amount in the target (receiving) currency after conversion.                                                                                                                                                                                                                         |
| exchangeRate      | string | Locked FX rate between `originCurrency` and `targetCurrency`.                                                                                                                                                                                                                       |
| feeAmount         | string | Transaction fee amount charged in `feeCurrency`.                                                                                                                                                                                                                                    |
| feeCurrency       | string | ISO 4217 currency code in which `feeAmount` is denominated.                                                                                                                                                                                                                         |
| targetFeeAmount   | string | Transaction fee amount charged in `targetFeeCurrency`.                                                                                                                                                                                                                              |
| targetFeeCurrency | string | ISO 4217 currency code in which `targetFeeAmount` is denominated.                                                                                                                                                                                                                   |
| targetFeeFxRate   | string | FX rate applied between `feeCurrency` and `targetFeeCurrency` for the fee amount.                                                                                                                                                                                                   |
| expireTime        | string | ISO 8601 UTC timestamp (`Z` suffix) after which `token` is no longer valid. Converted server-side from the upstream connector's UTC+8 timestamp.                                                                                                                                    |

#### Response sample

```json
{
  "code": 1,
  "data": {
    "targetCurrency": "USD",
    "targetAmount": "14.79",
    "originCurrency": "CNY",
    "targetFeeAmount": "1.00",
    "targetFeeFxRate": "1",
    "feeCurrency": "CNY",
    "targetFeeCurrency": "CNY",
    "token": "785740956796000019",
    "originAmount": "100",
    "feeAmount": "1.00",
    "expireTime": "2026-08-03T07:10:16.000Z",
    "exchangeRate": "0.14793400000",
    "requestId": "1785740957"
  },
  "message": "Successful",
  "neoResponseId": "266e1be3-019d-4b5f-b5b9-d926aae6b32c"
}
```

### 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 (\~55 seconds); pass it to the `token` field of [Create Payout Request](/docs/global/global-collections/integration/payout-requests/api-create-payout-request.md) before it expires, or the create call will fail with `INVALID TOKEN`.
* `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 only needed for cross-currency payouts; omit it for same-currency payouts.