# 批量查询订单 ::: tip 该接口用于分页查询指定时间范围内的`付款订单明细`，支持按照`时间`、`订单状态`、`国家`、`支付方式`、`渠道`等维度进行过滤，帮助商户或系统运营人员快速定位并获取历史交易记录。 ::: **推荐使用场景**： - 日志分析与异常排查； - 按天对账参考； - 后台数据导出与数据治理。 ## 1. 接口路径 ``` POST https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry ``` ## 2. 环境信息 - **测试环境**：https:// `pay-gate-uat.payermax.com`/aggregate-pay/api/gateway/ `<接口PATH>` - **集成环境**：https:// `pay-gate.payermax.com`/aggregate-pay/api/gateway/ `<接口PATH>` ## 3. 请求参数说明 ### 3.1 Headers | 参数名 | 类型 | 是否必须 | 示例值 | 说明 | | ------ | -------- | -------- | -------------------- | ---------------------------- | | sign | `String` | M | FPFVT3o227JrFRbqu... | 请求签名，请参照签名生成规则 | ### 3.2 Body | 参数名 | 类型 | 是否必须 | 示例值 | 说明 | | ---------------------- | -------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- | | version | `String` | M | 1.4 | 接口版本，当前版本1.4 | | keyVersion | `String` | M | 1 | 密钥版本，当前版本1 | | requestTime | `String` | M | 2025-04-23T10:00:00.500+08:00 | 请求时间，符合rfc3339规范，格式：yyyy-MM-dd’T’HH:mm:ss.SSSXXX | | appId | `String` | M | 6666c83333a24666674497c444a33333 | 商户应用ID，PayerMax分配给商户应用的唯一标识 | | merchantNo | `String` | M | 10213834123456 | 商户号，商户与PayerMax业务签约时生成的唯一标识 | | data | `Object` | M | | 请求数据体 | | └─ queryBeginTime | `String` | M | 2025-04-23 01:00:00 | 交易查询起始时间，时区UTC+0，格式：yyyy-MM-dd HH:mm:ss，`起始时间和截止时间间隔不能超过1天` | | └─ queryEndTime | `String` | M | "2025-04-23 02:00:00" | 交易查询截止时间，时区UTC+0，格式：yyyy-MM-dd HH:mm:ss，`起始时间和截止时间间隔不能超过1天` | | └─ pageSize | `Long` | O | 20 | 一次查询返回的最大交易笔数，最大不能超过100笔，不送该字段时，本次查询将返回按照订单创建时间升序排列的前20笔 | | └─ currentPageIndex | `Long` | O | 3 | 本次查询需要查第几页的数据，不送该字段时，本次查询将返回结果集中的第一页数据 | | └─ status | `String` | O | PENDING | 本次需要查询的订单状态，SUCCESS成功，FAILED失败 ，PENDING进行中，BOUNCEBACK退票 | | └─ country | `String` | O | PH | 本次需要查询的订单国家 | | └─ paymentMethodType | `String` | O | WALLET | 本次需要查询的订单支付方式类型 | | └─ targetOrg | `String` | O | GCASH | 本次需要查询的订单目标机构 | | └─ clearingRail | `String` | O | LOCAL | 本次需要查询的订单清算网络，主要针对银行转账类 | ### 3.3 请求示例 ``` 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": "" } } ``` 此查询示例的含义是： - 查询时间范围为`2025年4月23日` `01:00`至`02:00`之间菲律宾`GCASH`钱包状态为`PENDING`的所有交易； - 每页返回`20`条记录，当前请求第`2`页。 ## 4. 响应参数说明 ### 4.1 顶层字段（code/msg/data） | 字段名 | 类型 | 是否必须 | 示例值 | 说明 | | ------ | -------- | -------- | ------------- | --------------------------------------------------------------------- | | code | `String` | M | APPLY_SUCCESS | 返回码，`APPLY_SUCCESS`代表成功。只代表接口请求成功，不代表订单状态。 | | msg | `String` | M | Success. | 返回描述。 | | data | `Object` | M | - | 返回数据体 | ### 4.2 data字段结构 | 字段名 | 类型 | 是否必须 | 示例值 | 说明 | | ------------------- | ------- | -------- | ------ | ---------------------------------------------------------------------------------------------------- | | totalTransactionNum | `Long` | M | 98 | 查询时间间隔内的订单总笔数，当总笔数为0时，不会有`pageIndex`和`transactionList`字段 | | maxPageIndex | `Long` | O | 10 | 当前查询条件查询结果按照入参中的`pageSize`分页后的最大页码数，入参未传`pageSize`时默认一页`20`笔数据 | | currentPageIndex | `Long` | O | 2 | 当前结果集页码数，不超过`maxPageIndex` | | transactionList | `Array` | O | - | 订单信息列表，当`totalTransactionNum`大于`0`时，该字段不为空 | ### 4.3 transactionList字段结构 | 字段路径 | 类型 | 是否必须 | 示例值 | 说明 | | ------------------------ | -------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | transactionUtcTime | `String` | M | 2024-07-29T12:32:53+0000 | 交易创建时间，符合rfc3339规范，格式：yyyy-MM-dd’T’HH:mm:ss Z | | outTradeNo | `String` | M | ORDER123456789 | 商户订单号 | | tradeNo | `String` | M | 20250423012658PO71330000270184 | PayerMax 交易流水号 | | accountInfo.accountNo | `String` | M | 123456****1234 | 收款账号，脱敏返回，前6后4 | | name.fullName | `String` | O | Antonio Maldonado Evangelista | 收款方名称 | | status | `String` | M | FAILED | 交易状态 | | responseCode | `String` | O | INVALID_ACCOUNT | 订单失败错误码，详见[交易状态/错误码](https://docs.payermax.com/202606-version/appendix/disbursement/transaction-status.md#_3-交易状态-错误码) | | responseMsg | `String` | O | Invalid account | 订单失败错误描述 | | reference | `String` | O | this is reference | 附加数据，下单上送值 | | redeemCode | `String` | O | - | 1.FAWRY取款码，2.运营商充值PIN码 | | expiryTime | `String` | O | 2022-12-02T11:35:23+0000 | 订单过期时间，符合rfc3339规范，格式：yyyy-MM-dd’T’HH:mm:ss Z | | bounceBackTime | `String` | O | 2022-12-02T11:35:23+0000 | 退票时间，符合rfc3339规范，格式：yyyy-MM-dd’T’HH:mm:ss Z | | payFinishTime | `String` | O | 2022-12-02T11:35:23+0000 | 交易完成时间，符合rfc3339规范，格式：yyyy-MM-dd’T’HH:mm:ss Z | | country | `String` | M | PH | 国家 | | paymentMethodType | `String` | M | WALLET | 支付方式类型 | | targetOrg | `String` | O | GCASH | 目标机构 | | clearingRail | `String` | O | LOCAL | 清算网络 | | trade.amount | `String` | M | 3223.59 | 请求中传入的付款金额 | | trade.currency | `String` | M | PHP | 付款币种，请求中传入的付款金额对应货币代码 | | source.amount | `String` | M | 3223.59 | 付款方-扣款金额 | | source.currency | `String` | M | PHP | 付款方-扣款币种 | | source.exchangeRate | `String` | O | 1.00000000 | 交易币种转换为扣款币种的汇率 | | source.fee | `String` | O | 0 | 付款方-手续费 | | source.feeCurrency | `String` | O | PHP | 付款方-手续费币种 | | source.tax | `String` | O | 0 | 付款方-税费 | | source.taxCurrency | `String` | O | PHP | 付款方-税费币种 | | destination.amount | `String` | M | 3223 | 收款方到账金额 | | destination.currency | `String` | M | PHP | 收款方到账金额币种 | | destination.exchangeRate | `String` | O | 1.00000000 | 交易币种转换为到账币种的汇率 | | destination.fee | `String` | O | 0.59 | 收款方-手续费 | | destination.feeCurrency | `String` | O | PHP | 收款方-手续费币种 | | destination.tax | `String` | O | 0 | 收款方-税费 | | destination.taxCurrency | `String` | O | PHP | 收款方-税费币种 | | notifyPhone | `String` | O | 1234454556 | 收款方通知手机号 | | notifyEmail | `String` | O | xxxx@gmail.com | 收款方通知邮箱 | ### 4.4 响应示例 ``` json { "code": "APPLY_SUCCESS", "msg": "Success.", "data": { "totalTransactionNum": 98, "pageIndex": 2, "transactionList": [{ "createTime": "2025-04-23 01:26:58", "outTradeNo": "ORDER123456789", "tradeNo": "20250423012658PO71330000270184", "accountInfo": { "accountNo": "12345" }, "name": { "fullName": "Antonio Maldonado Evangelista" }, "status": "FAILED", "responseCode": "INVALID_ACCOUNT", "responseMsg": "Invalid account", "country": "PH", "paymentMethodType": "WALLET", "targetOrg": "GCASH", "transactionUtcTime": "2022-12-02T11:35:17 +0000", "payFinishTime": "2022-12-02T11:35:23 +0000", "reference": "this is reference", "redeemCode": "", "expiryTime": "", "bounceBackTime": "", "trade": { "amount": "3223.59", "currency": "PHP" }, "destination": { "amount": "3223.00", "taxCurrency": "PHP", "exchangeRate": "1.0000000000", "fee": "0.59", "feeCurrency": "PHP", "currency": "PHP", "tax": "0.00" }, "source": { "amount": "3223.59", "taxCurrency": "PHP", "exchangeRate": "1.0000000000", "fee": "0.00", "feeCurrency": "PHP", "currency": "PHP", "tax": "0.00" } }] } } ``` ## 5. 接口响应码说明 | code | msg | 描述 | | ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `APPLY_SUCCESS` | Success. | 请求成功，可正常解析`data`中的内容 | | `PARAMS_INVALID` | queryBeginTime cannot be empty | 交易查询起始时间不能为空 | | `PARAMS_INVALID` | Invalid queryBeginTime format | 交易查询起始时间格式错误 | | `PARAMS_INVALID` | queryEndTime cannot be empty | 交易查询结束时间不能为空 | | `PARAMS_INVALID` | Invalid queryEndTime format | 交易查询结束时间格式错误 | | `PARAMS_INVALID` | queryBeginTime must be earlier than current time | 起始时间必须小于当前时间 | | `PARAMS_INVALID` | queryEndTime must be earlier than current time | 截止时间必须小于当前时间 | | `PARAMS_INVALID` | queryBeginTime cannot exceed six months from current time | 起始时间距离现在不能超过6个月 | | `PARAMS_INVALID` | Time interval between queryBeginTime and queryEndTime exceeds maximum allowed duration | 起止时间间隔超过限制 | | `PARAMS_INVALID` | queryEndTime must be later than queryBeginTime | 结束时间必须晚于起始时间 | | `PARAMS_INVALID` | pageSize cannot exceed maxPageSize | `pageSize`超过最大限制 | | `PARAMS_INVALID` | currentPageIndex must not exceed maxPageIndex | `currentPageIndex`超过最大页码 | | `PARAMS_INVALID` | The status is incorrect. | `status`参数错误，仅支持`SUCCESS`、`FAILED`、`PENDING`、`BOUNCEBACK` | | `PARAMS_INVALID` | The country is incorrect. | `country`参数无效 | | `PARAMS_INVALID` | The paymentMethodType is incorrect. | `paymentMethodType`参数无效 | | `SYSTEM_ERROR` | System is busy, please try again later. | 系统异常，请稍后重试 |