Exchange Application

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

Description

Currency exchange function is used to exchange the available balance between different currencies of the merchant (one of which is USD).

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		Current value:1.5
keyVersion	string	Yes		Current value: 1
requestTime	string	Yes		compliant with rfc3339 specification, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX The time must be within two minutes of the current time
appId	string	Yes		The unique identifier assigned to the merchant app by PayerMax
memberId	string	Yes		the unique identifier generated when the merchant signs the contract with PayerMax
data	object	Yes
data.accountInfo	object	Yes		Account information
data.accountInfo.buyFundsAccountNo	string	Yes		Buy funds account number,Funds will be credited to this account upon successful transaction
data.accountInfo.sellFundsAccountNo	string	Yes		Sell funds account number,Funds will be debited from this account upon successful transaction
data.outTradeNo	string	Yes	maxLength: 64	Merchant order id (must be unique under the merchant)
data.side	string	Yes		Buy/Sell direction for the transaction currency
data.targetCurrency	string	Yes	maxLength: 3, minLength: 3	Target currency
data.transactionAmount	string	Yes		Transaction amount
data.transactionCurrency	string	Yes	maxLength: 3, minLength: 3	Transaction currency
data.callBackUrl	string	No	maxLength: 512	Callback URL when the order reaches terminal state
data.rateReferenceId	string	No		Exchange rate version,obtained via the Funds account exchange rate query API

Example

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2025-12-05T20:55:13.712+08:00",
  "appId": "798b79c2e33a4d8e866410bf401551a7",
  "memberId": "20250619P01B00000075000002",
  "data": {
    "accountInfo": {
      "buyFundsAccountNo": "P25101038985",
      "sellFundsAccountNo": "P25101038984"
    },
    "outTradeNo": "20251201004059PO66350070490846T04",
    "side": "SELL",
    "targetCurrency": "PHP",
    "transactionAmount": "1001",
    "transactionCurrency": "USD",
    "callBackUrl": "http://xxxx/yyyy"
  }
}

Responses

200

Field	Type	Required	Constraints	Description	Enum
msg	string	Yes		‘Success.’
code	string	Yes		‘APPLY_SUCCESS’ means success
data	object	Yes
data.accountInfo	object	Yes
data.accountInfo.buyFundsAccountNo	string	Yes		Buy funds account number
data.accountInfo.sellFundsAccountNo	string	Yes		Sell funds account number
data.transactionCurrency	string	Yes		Transaction currency
data.side	string	Yes		Buy/Sell direction for the transaction currency
data.tradeNo	string	Yes		Platform order number
data.targetCurrency	string	Yes		Target currency
data.targetAmount	string	Yes		Target amount
data.completeTime	string	Yes		Completion time
data.rateReferenceId	string	Yes		Exchange rate version
data.ccyPair	string	Yes		(= transaction currency + target currency)
data.rate	string	Yes		(1 transaction currency = ? target currency)
data.outTradeNo	string	Yes		Merchant order id
data.transactionAmount	string	Yes		Transaction amount
data.status	string	Yes		- PROCESSING: Processing - SUCCESS: Success - FAILED: Failed

Response Example

{
  "msg": "",
  "code": "APPLY_SUCCESS",
  "data": {
    "accountInfo": {
      "buyFundsAccountNo": "P25101038985",
      "sellFundsAccountNo": "P25101038984"
    },
    "transactionCurrency": "USD",
    "side": "SELL",
    "tradeNo": "20251205125637TU9495336408000531T05",
    "targetCurrency": "PHP",
    "targetAmount": "58624.94",
    "completeTime": "2025-12-05T12:56:37.000Z",
    "rateReferenceId": "tieredBatchId0076176493939752933802672",
    "ccyPair": "USDPHP",
    "rate": "58.56637500",
    "outTradeNo": "20251201004059PO66350070490846T04",
    "transactionAmount": "1001.00",
    "status": "SUCCESS"
  }
}