Transaction Inquiry

This API is used to query payment order details within a specified time range in a paginated manner. It supports filtering by time, order status, country, payment method, channel, and other dimensions, helping merchants or system operators quickly locate and retrieve historical transaction records.

Recommended Use Cases:

• Log analysis and exception troubleshooting;

• Daily reconciliation reference;

• Backend data export and data governance.

1. API Path

POST https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry

2. Environment Information

• Test Environment: https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <API PATH>

• Integration Environment: https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <API PATH>

3. Request Parameter Description

3.1 Headers

Parameter Name	Type	Mandatory (Y/N)	Example Value	Description
sign	String	M	FPFVT3o227JrFRbqu...	Request signature, please refer to the signature generation rules

3.2 Body

Parameter Name	Type	Mandatory (Y/N)	Example Value	Description
version	String	M	1.4	API version; the current version is 1.4
keyVersion	String	M	1	Key version; the current version is 1
requestTime	String	M	2025-04-23T10:00:00.500+08:00	Request time, compliant with RFC 3339 standard, format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX
appId	String	M	6666c83333a24666674497c444a33333	Merchant App ID; the unique identifier assigned by PayerMax to the merchant's application
merchantNo	String	M	10213834123456	Merchant Number; the unique identifier generated when the merchant signs a business contract with PayerMax
data	Object	M		Request data body
└─ queryBeginTime	String	M	2025-04-23 01:00:00	Transaction query start time, time zone UTC+0, format: yyyy-MM-dd HH:mm:ss; the time interval between start time and end time cannot exceed 1 day
└─ queryEndTime	String	M	"2025-04-23 02:00:00"	Transaction query end time, time zone UTC+0, format: yyyy-MM-dd HH:mm:ss; the time interval between start time and end time cannot exceed 1 day
└─ pageSize	Long	O	20	Maximum number of transactions returned per query; cannot exceed 100. If this field is not provided, the query will return the first 20 transactions sorted by order creation time in ascending order
└─ currentPageIndex	Long	O	3	The page number of data to be queried in this request. If this field is not provided, the query will return the first page of the result set
└─ status	String	O	PENDING	Status of the orders to be queried in this request: SUCCESS (Successful), FAILED (Failed), PENDING (Processing), BOUNCEBACK (Payment Reversed)
└─ country	String	O	PH	Country of the orders to be queried in this request
└─ paymentMethodType	String	O	WALLET	Payment method type of the orders to be queried in this request
└─ targetOrg	String	O	GCASH	Target institution of the orders to be queried in this request
└─ clearingRail	String	O	LOCAL	Clearing network of the orders to be queried in this request, mainly for bank transfer types

3.3 Request Example

{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2025-04-23T10:00:00.500+08:00",
  "appId": "6666c83333a24666674497c444a33333",
  "merchantNo": "010213834123456",
  "data": {
    "queryBeginTime": "2025-04-23 01:00:00",
    "queryEndTime": "2025-04-23 02:00:00",
    "pageSize": 20,
    "currentPageIndex": 2,
    "status": "PENDING",
    "country": "PH",
    "paymentMethodType": "WALLET",
    "targetOrg": "GCASH",
    "clearingRail": ""
  }
}

This query example means:

• Query all transactions with a PENDING status in the Philippines GCASH wallet between 01:00 and 02:00 on April 23, 2025;

• Returns 20 records per page, currently requesting page 2.

4. Response Parameter Description

4.1 Top-Level Fields (code/msg/data)

Field Name	Type	Mandatory (Y/N)	Example Value	Description
code	String	M	APPLY_SUCCESS	Return code; APPLY_SUCCESS indicates success. It only means the API request is successful, not the order status.
msg	String	M	Success.	Return description.
data	Object	M	-	Return data body

4.2 data Field Structure

Field Name	Type	Mandatory (Y/N)	Example Value	Description
totalTransactionNum	Long	M	98	Total number of orders within the query time interval. When the total number is 0, the pageIndex and transactionList fields will not be present
maxPageIndex	Long	O	10	Maximum page number after paginating the query results according to the pageSize in the input parameters. If pageSize is not provided in the input parameters, the default is 20 items per page
currentPageIndex	Long	O	2	Current result set page number, which does not exceed maxPageIndex
transactionList	Array	O	-	List of order information. This field is not empty when totalTransactionNum is greater than 0

4.3 transactionList Field Structure

Field Path	Type	Mandatory (Y/N)	Example Value	Description
transactionUtcTime	String	M	2024-07-29T12:32:53+0000	Transaction creation time, compliant with RFC 3339 standard, format: yyyy-MM-dd’T’HH:mm:ss Z
outTradeNo	String	M	ORDER123456789	Merchant Order Number
tradeNo	String	M	20250423012658PO71330000270184	PayerMax Transaction Serial Number
accountInfo.accountNo	String	M	123456****1234	Payee Account Number, returned in desensitized format (showing first 6 and last 4 digits)
name.fullName	String	O	Antonio Maldonado Evangelista	Payee Name
status	String	M	FAILED	Transaction Status
responseCode	String	O	INVALID_ACCOUNT	Order Failure Error Code, see Transaction Status/Error Codes for details
responseMsg	String	O	Invalid account	Order Failure Error Description
reference	String	O	this is reference	Additional Data, value submitted during order placement
redeemCode	String	O	-	1. FAWRY Withdrawal Code; 2. Telecom Operator Top-up PIN Code
expiryTime	String	O	2022-12-02T11:35:23+0000	Order Expiration Time, compliant with RFC 3339 standard, format: yyyy-MM-dd’T’HH:mm:ss Z
bounceBackTime	String	O	2022-12-02T11:35:23+0000	Payment Reversal Time, compliant with RFC 3339 standard, format: yyyy-MM-dd’T’HH:mm:ss Z
payFinishTime	String	O	2022-12-02T11:35:23+0000	Transaction Completion Time, compliant with RFC 3339 standard, format: yyyy-MM-dd’T’HH:mm:ss Z
country	String	M	PH	Country
paymentMethodType	String	M	WALLET	Payment Method Type
targetOrg	String	O	GCASH	Target Institution
clearingRail	String	O	LOCAL	Clearing Network
trade.amount	String	M	3223.59	Payment Amount Submitted in the Request
trade.currency	String	M	PHP	Payment Currency, currency code corresponding to the payment amount submitted in the request
source.amount	String	M	3223.59	Payer - Debited Amount
source.currency	String	M	PHP	Payer - Debited Currency
source.exchangeRate	String	O	1.00000000	Exchange Rate for Converting Transaction Currency to Debited Currency
source.fee	String	O	0	Payer - Service Fee
source.feeCurrency	String	O	PHP	Payer - Service Fee Currency
source.tax	String	O	0	Payer - Tax
source.taxCurrency	String	O	PHP	Payer - Tax Currency
destination.amount	String	M	3223	Payee - Received Amount
destination.currency	String	M	PHP	Payee - Received Amount Currency
destination.exchangeRate	String	O	1.00000000	Exchange Rate for Converting Transaction Currency to Received Currency
destination.fee	String	O	0.59	Payee - Service Fee
destination.feeCurrency	String	O	PHP	Payee - Service Fee Currency
destination.tax	String	O	0	Payee - Tax
destination.taxCurrency	String	O	PHP	Payee - Tax Currency
notifyPhone	String	O	1234454556	Payee Notification Phone Number
notifyEmail	String	O	xxxx@gmail.com	Payee Notification Email

5. Interface Response Code Description

Code	Msg	Description
APPLY_SUCCESS	Success.	The request is successful, and the content in data can be parsed normally
PARAMS_INVALID	queryBeginTime cannot be empty	The transaction query start time cannot be empty
PARAMS_INVALID	Invalid queryBeginTime format	The transaction query start time format is incorrect
PARAMS_INVALID	queryEndTime cannot be empty	The transaction query end time cannot be empty
PARAMS_INVALID	Invalid queryEndTime format	The transaction query end time format is incorrect
PARAMS_INVALID	queryBeginTime must be earlier than current time	The start time must be earlier than the current time
PARAMS_INVALID	queryEndTime must be earlier than current time	The end time must be earlier than the current time
PARAMS_INVALID	queryBeginTime cannot exceed six months from current time	The start time cannot be more than 6 months from the current time
PARAMS_INVALID	Time interval between queryBeginTime and queryEndTime exceeds maximum allowed duration	The time interval between the start time and end time exceeds the maximum limit
PARAMS_INVALID	queryEndTime must be later than queryBeginTime	The end time must be later than the start time
PARAMS_INVALID	pageSize cannot exceed maxPageSize	pageSize exceeds the maximum limit
PARAMS_INVALID	currentPageIndex must not exceed maxPageIndex	currentPageIndex exceeds the maximum page number
PARAMS_INVALID	The status is incorrect.	The status parameter is incorrect; only SUCCESS, FAILED, PENDING, and BOUNCEBACK are supported
PARAMS_INVALID	The country is incorrect.	The country parameter is invalid
PARAMS_INVALID	The paymentMethodType is incorrect.	The paymentMethodType parameter is invalid
SYSTEM_ERROR	System is busy, please try again later.	System exception, please try again later