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

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

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

curl -X POST "https://{base_url_openapi}/v2/gc/payout-requests/inquiry" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -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.