Payin or payout rate query

• Endpoint: POST /aggregate-pay/api/gateway/queryClientExchangeRate
• Tags: Forex(New)

Description

This API supports querying exchange rates for payin or payout transactions, providing reference for your forex trading decisions. Please note that the queried rates are for reference only and do not constitute a trading commitment. Note: Before using this API, please ensure that you have activated the relevant product services.

Parameters

Field	In	Type	Required	Constraints	Description
Content-Type	header	string	Yes
sign	header	string	Yes		签名信息请参考技术文档

Parameter Examples

• Content-Type: "application/json"
• sign: "FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Request Body

Required

Content-Type: application/json

Field	Type	Required	Constraints	Description	Enum
version	string	Yes		API version,Current value: 1.5
keyVersion	string	Yes		Key version,Current value: 1
requestTime	string	Yes		Request timestamp,must comply with RFC3339 format and be within two minutes of the current time.
appId	string	Yes		The unique application identifier assigned to you by PayerMax
merchantNo	string	Yes		Your unique merchant identifier.
data	object	Yes		The main body of the request data
data.ccyPairList	array[object]	Yes		List of currency pairs to query,maximum 40
data.ccyPairList[].side	string	Yes		The buying/selling direction for the transaction currency from the client's perspective.
data.ccyPairList[].targetCurrency	string	Yes		FX targetCurrency
data.ccyPairList[].transactionCurrency	string	Yes		FX transactionCurrency
data.product	string	Yes		Product type,PAY_IN / PAY_OUT
data.validTime	string	No		To specify the date for the rate query format: yyyyMMdd this field applies only to the acquiring locked rate scenario. - If the locked rate service is not activated, this field is invalid (the current rate is returned by default). - For the acquiring locked rate scenario: - If this field is empty, the current period's locked rate is returned by default. - You can query the next period's locked rate 15 minutes in advance (by passing the next day's date). - Historical expired rates are not supported for query

Example

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-06-10T20:30:53.732+08:00",
  "appId": "46153e2b787241ae8b01857bb087d1bd",
  "merchantNo": "010229810189301",
  "data": {
    "ccyPairList": [
      {
        "side": "BUY",
        "targetCurrency": "AED",
        "transactionCurrency": "USD"
      },
      {
        "side": "SELL",
        "targetCurrency": "IDR",
        "transactionCurrency": "USD"
      }
    ],
    "product": "PAY_IN"
  }
}

Responses

200

Field	Type	Required	Constraints	Description	Enum
code	string	Yes		Status code
data	object	Yes		The main body of the response data
data.currencyList	array[object]	Yes		List of exchange rate information
data.currencyList[].ccyPair	string	Yes		Currency pair,transactionCurrency targetCurrency
data.currencyList[].rate	number	Yes		Exchange rate value,indicating the amount of target currency equivalent to one unit of the transaction currency.
data.currencyList[].rateType	string	Yes		Rate type
data.currencyList[].side	string	Yes		The buying/selling direction for the transaction currency from the client‘s perspective.
data.currencyList[].targetCurrency	string	Yes		FX target Currency
data.currencyList[].transactionCurrency	string	Yes		FX transaction Currency
data.currencyList[].rateReferenceId	string	No		Unique Exchange Rate ID,Unique Exchange Rate ID. Returned only in Tradable scenarios.
data.currencyList[].effectTime	string	No		Rate effective time format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
data.currencyList[].expiryTime	string	No		Rate expiry time format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
data.currencyList[].validTime	string	No		Rate last usable time format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
msg	string	Yes		Error message

Response Example

{
  "code": "APPLY_SUCCESS",
  "data": {
    "currencyList": [
      {
        "ccyPair": "USDAED",
        "rate": 3.6844202,
        "rateType": "Reference",
        "side": "BUY",
        "targetCurrency": "AED",
        "transactionCurrency": "USD",
        "rateReferenceId": "payerMax123456",
        "effectTime": "2025-09-11T12:04:13.629Z",
        "expiryTime": "2025-09-11T12:04:13.629Z",
        "validTime": "2025-09-11T12:04:13.629Z"
      },
      {
        "ccyPair": "USDIDR",
        "rate": 15422.562,
        "rateType": "Reference",
        "side": "SELL",
        "targetCurrency": "IDR",
        "transactionCurrency": "USD"
      }
    ]
  },
  "msg": ""
}