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.

This endpoint uses method GET with query parameters (not POST with a JSON body).

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	Conditional	Sub-merchant identifier, if applicable. Optional in general; required when the merchant operates in PSP mode.
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. 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

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