# Transaction Inquiry ::: tip 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/ `` - **Integration Environment**: https:// `pay-gate.payermax.com`/aggregate-pay/api/gateway/ `` ## 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 ``` json { "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](https://docs.payermax.com/en/202606-version/appendix/disbursement/transaction-status.md#_3-transaction-status-errorcode) 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 |