文档

FuturePay 订单列表查询

该接口用于统一分页查询支付、退款、拒付、拒付预警订单列表

1.请求地址（POST）

实时 API: https://api.futurepay.global/payin/queryOrders

沙盒 API: https://api.futurepay-develop.com/payin/queryOrders


2.请求参数（JSON 格式）

本接口有两种用法，按需二选一：

  • 用法 A —— 按时间分页查：传 startDate + endDate
  • 用法 B —— 查一笔交易的全部关联单：传 originalReference
参数名类型必填说明
startDateString用法 A开始时间（UTC，格式 yyyy-MM-dd HH:mm:ss），按订单创建时间筛选，含边界
endDateString用法 A结束时间（UTC，格式 yyyy-MM-dd HH:mm:ss），按订单创建时间筛选，含边界
originalReferenceString用法 B原交易的 FuturePay 平台订单号。传入后返回该笔交易及其全部关联单
orderTypeString否订单类型，不传表示全部类型，取值见下方枚举说明。两种用法都可叠加
merchantReferenceString否商户订单号，精确匹配（仅用法 A）
pspReferenceString否FuturePay 平台订单号，精确匹配（仅用法 A）
pageSizeInteger否每页条数，不传默认 10（仅用法 A）
currentPageInteger否页码，从 1 开始，不传默认 1（仅用法 A）

参与签名的字段以你实际发送的报文为准。 不传的字段不参与签名，传了就要参与。
不要在签名时补上自己并没有发送的字段（比如替 currentPage / pageSize 填上默认值），
否则签名串与我方计算的不一致，会返回签名无效。

用法 A —— 按时间分页查

查询时间范围最长 7 天，endDate - startDate 超过 7 天返回错误码 40004。
结果按订单创建时间倒序返回（最新的在前）。

{
    "startDate": "2026-02-12 00:00:00",
    "endDate": "2026-02-12 23:21:31",
    "currentPage": 1,
    "pageSize": 10,
    "orderType": "efw"
}

用法 B —— 查一笔交易的全部关联单

传 originalReference，返回原交易本身 + 挂在它名下的全部关联单（退款、正式拒付、调单、拒付预警）。

{
    "originalReference": "2098369735585562624"
}

几点需要注意：

  1. 传 originalReference 时不要传 startDate / endDate，本用法不按时间筛选。
    拒付通常在原交易之后 30~120 天才发生，退款和预警也大多不在同一天，
    如果沿用用法 A 的 7 天时间窗，恰好会查不到你真正想找的那几笔单。
  2. 可以直接传关联单的单号。比如手上只有一笔拒付单号 CB2098370142512742400，
    传进来会自动向上找到它对应的原交易，再把整组返回。
  3. 结果按完成时间倒序返回，最新的一条在最前（与用法 A 一致）。尚未完成的单（例如
    预警单的 completeTime 为 null）按其创建时间参与排序，不会被排到末尾。
  4. 可叠加 orderType 只看某一类，例如只看这笔交易的拒付单： 
    {
    "originalReference": "2098369735585562624",
    "orderType": "chargeback"
}
  5. 本用法不分页，一次返回全部（上限 100 条），响应里 currentPage 恒为 1、hasMore 恒为 false。
  6. 单号不存在或不属于当前商户时返回空列表，不报错。

3.响应参数（JSON格式）

顶层字段

参数名类型示例值描述
codeString"0"响应码，0 表示成功
msgString"success"响应消息
serverTimeLong1770916097050服务器时间戳（毫秒，UTC）
successBooleantrue请求是否成功
dataObject见下表分页订单数据对象

data 字段

参数名类型示例值描述
currentPageInteger1当前页码（从 1 开始）
pageSizeInteger10每页条数
totalCountInteger2总记录数
totalPageInteger1总页数
hasMoreBooleanfalse是否还有下一页
itemsArray见下表订单列表

items 字段（订单对象）

参数名类型示例值描述
merchantReferenceString"C4AD695A83234FBEBC2D6536B8474B3A"商户订单号
pspReferenceString"2021903193281265664"FuturePay 平台订单号
resultCodeString"SUCCEED"订单状态，见下方说明。预警类订单（rdr/ethoca/efw）返回 null
failReasonString"RDR_WARNING"失败或预警原因
amountObject见下表支付金额信息
providerReferenceString"202500016422"支付渠道订单号
paymentMethodString"intercards"支付方式（如 cards、alipay 等）
completeTimeString"2026-02-12T11:04:15.000+00:00"完成时间（UTC）。订单尚未终态时为 null
orderCreateTimeString"2026-02-12T11:04:15.000+00:00"订单创建时间（UTC）
orderTypeString"rdr"订单类型，见下方枚举说明
additionalDataObject见下表仅争议类订单返回，普通交易与退款不返回该字段

响应中还会出现 refusalReason、currency 两个恒为 null 的历史保留字段，请勿依赖。失败/预警原因统一读 failReason。

amount 字段

参数名类型示例值描述
currencyString"USD"币种代码
valueLong200支付金额，单位为“分”

additionalData 字段（仅争议类订单返回）

争议类订单指 chargeback、inquiry、rdr、ethoca、efw 五种。

字段名类型示例值描述
originalReferenceString"2098369735585562624"被争议的原交易的 FuturePay 平台订单号，用它关联回原始支付
fundImpactString"FROZEN"资金影响，见下表
disputeDueByString"2026-09-19 00:00:00"抗辩截止时间（UTC，yyyy-MM-dd HH:mm:ss）。仅 chargeback / inquiry 返回
networkReasonCodeString"10.4"卡组织争议原因码。仅 chargeback / inquiry 返回

字段无值时不会出现在 additionalData 中，请按「可能不存在」处理。

fundImpact 枚举说明

值含义典型场景
AUTO_REFUNDED已自动退款解决，商户无需操作RDR / Ethoca / EFW 预警已按规则自动退款
MERCHANT_ACTION待商户决定，当前尚未产生资金影响调单（inquiry）等待提交资料或接受
FROZEN本金与手续费已冻结，等待裁决结果正式拒付（chargeback）受理中
SETTLED_WON争议胜诉，冻结金额已释放抗辩成功
SETTLED_LOST争议败诉，本金与手续费已扣除抗辩失败或超期未回应
NONE不产生资金影响争议已撤销 / 已关闭

disputeDueBy 是抗辩截止时间，超过该时间提交证据会被卡组织拒绝、争议直接判负。 建议收到争议后立即入库并设置提醒，不要依赖轮询本接口来发现临期争议。

时间说明

所有时间字段均为 UTC 时间，但存在两种格式，解析时请注意区分：

字段格式示例
startDate、endDate（请求）yyyy-MM-dd HH:mm:ss2026-02-12 00:00:00
completeTime、orderCreateTimeISO-8601（带时区）2026-02-12T11:04:15.000+00:00
additionalData.disputeDueByyyyy-MM-dd HH:mm:ss2026-09-19 00:00:00

服务器时间戳（serverTime）为毫秒级 Unix 时间戳（UTC）。

orderType 枚举说明

值含义资金说明
transaction交易—
refund退款—
chargeback正式拒付冻结本金与手续费，败诉则扣除
inquiry调单（发卡行索取资料，尚未形成拒付）不冻结资金，可提交资料或接受
rdrRDR 预警（Visa Rapid Dispute Resolution）按规则自动退款解决，不进入拒付流程
ethocaEthoca 预警自动退款解决
efwEFW 早期欺诈预警自动退款解决

orderType 既是响应字段，也是请求里的筛选条件，取值完全一致。

resultCode 字段说明

resultCode 表示当前业务对象的处理状态，不同业务场景下其语义不同，需结合 orderType 理解。
预警类订单（rdr / ethoca / efw）不返回 resultCode，其处理结果请以 additionalData.fundImpact 为准。

交易场景

值英文描述中文含义
INITIALIZEDTransaction initialization支付已创建 / 预支付
PENDINGTrade is pending processing支付处理中（如 3DS 认证、跳转或异步确认）
SUCCEEDTrade has been successful支付成功
FAILEDTrade is failed支付失败
NOT_CAPTUREDNot captured未完成捕获
AUTHORIZEDTrade has been authorized已授权

退款场景

值英文描述中文含义
SUCCEEDTrade has been successful退款成功
FAILEDTrade is failed退款失败
REFUND_PARTTrade has Partial refund successful部分退款成功

拒付场景（chargeback / inquiry）

值英文描述中文含义
INITIALIZEDDispute has been initialized需要回应（调单）
PENDINGDispute is pending response需要回应
PENDING_REVIEWEvidence pending review证据待审核
UNDER_REVIEW_INQUIRYEvidence under review (inquiry)证据审核中（调单）
UNDER_REVIEWEvidence under review证据审核中
SUCCEEDDispute has been won by merchant争议胜诉（商户赢）
FAILEDDispute has been lost by merchant争议败诉（商户输）
CANCELDispute has been cancelled or closed争议已撤销 / 已关闭
EXPIREDDispute has expired争议已过期

4.错误码

codemsg说明
0success成功
40001Missing Required Arguments未传 originalReference 时缺少 startDate 或 endDate
40003The order type is not supported.orderType 不在枚举范围内
40004The query time range is too large.查询时间跨度超过 7 天
40005The time format is incorrect.时间格式不是 yyyy-MM-dd HH:mm:ss

5.示例

5.1 查询预警订单（orderType = rdr）

预警类订单 resultCode 与 completeTime 为 null，资金结果看 additionalData.fundImpact。

{
    "code": "0",
    "msg": "success",
    "serverTime": 1770916097050,
    "data": {
        "currentPage": 1,
        "pageSize": 10,
        "totalCount": 2,
        "totalPage": 1,
        "hasMore": false,
        "items": [
            {
                "merchantReference": "C4AD695A83234FBEBC2D6536B8474B3A",
                "pspReference": "2021903193281265664",
                "resultCode": null,
                "refusalReason": null,
                "failReason": "RDR_WARNING",
                "amount": {
                    "currency": "USD",
                    "value": 200
                },
                "currency": null,
                "providerReference": "202500016422",
                "paymentMethod": "intercards",
                "completeTime": null,
                "orderCreateTime": "2026-02-12T11:04:15.000+00:00",
                "orderType": "rdr",
                "additionalData": {
                    "originalReference": "2021903100000000000",
                    "fundImpact": "AUTO_REFUNDED"
                }
            },
            {
                "merchantReference": "120447CBA56042348C235D9624DB73E4",
                "pspReference": "2021884830421221376",
                "resultCode": null,
                "refusalReason": null,
                "failReason": "RDR_WARNING",
                "amount": {
                    "currency": "USD",
                    "value": 200
                },
                "currency": null,
                "providerReference": "202502422432422",
                "paymentMethod": "intercards",
                "completeTime": null,
                "orderCreateTime": "2026-02-12T09:51:18.000+00:00",
                "orderType": "rdr",
                "additionalData": {
                    "originalReference": "2021884700000000000",
                    "fundImpact": "AUTO_REFUNDED"
                }
            }
        ]
    },
    "success": true
}

5.2 查询拒付订单（orderType = chargeback）

正式拒付会返回 resultCode、抗辩截止时间与卡组织原因码。

{
    "code": "0",
    "msg": "success",
    "serverTime": 1789194960363,
    "data": {
        "currentPage": 1,
        "pageSize": 10,
        "totalCount": 1,
        "totalPage": 1,
        "hasMore": false,
        "items": [
            {
                "merchantReference": "35D58738ACA345E3BB380D6003747DD8",
                "pspReference": "CB2098370142512742400",
                "resultCode": "FAILED",
                "refusalReason": null,
                "failReason": "Fraud",
                "amount": {
                    "currency": "USD",
                    "value": 200
                },
                "currency": null,
                "providerReference": "du_1UESQM08pryDCbBWNzLD28lZ",
                "paymentMethod": "intercards",
                "completeTime": "2026-09-11T11:20:36.000+00:00",
                "orderCreateTime": "2026-09-11T11:16:42.000+00:00",
                "orderType": "chargeback",
                "additionalData": {
                    "originalReference": "2098369735585562624",
                    "fundImpact": "SETTLED_LOST",
                    "disputeDueBy": "2026-09-19 00:00:00",
                    "networkReasonCode": "10.4"
                }
            }
        ]
    },
    "success": true
}

上例中 pspReference 是拒付单自身的单号（CB 开头），additionalData.originalReference 才是被争议的原交易单号；fundImpact 为 SETTLED_LOST 表示该争议已判负、本金与手续费已扣除。

5.3 查一笔交易的全部关联单（用法 B）

请求：

{
    "originalReference": "2098369735585562624"
}

响应：按完成时间倒序，最新的一条在最前。

{
    "code": "0",
    "msg": "success",
    "serverTime": 1789202518745,
    "data": {
        "currentPage": 1,
        "pageSize": 100,
        "totalCount": 2,
        "totalPage": 1,
        "hasMore": false,
        "items": [
            {
                "merchantReference": "35D58738ACA345E3BB380D6003747DD8",
                "pspReference": "CB2098370142512742400",
                "resultCode": "FAILED",
                "failReason": "Fraud",
                "amount": {
                    "currency": "USD",
                    "value": 200
                },
                "providerReference": "du_1UESQM08pryDCbBWNzLD28lZ",
                "paymentMethod": "intercards",
                "completeTime": "2026-09-11T11:20:36.000+00:00",
                "orderCreateTime": "2026-09-11T11:16:42.000+00:00",
                "orderType": "chargeback",
                "additionalData": {
                    "originalReference": "2098369735585562624",
                    "fundImpact": "SETTLED_LOST",
                    "disputeDueBy": "2026-09-19 00:00:00",
                    "networkReasonCode": "10.4"
                }
            },
            {
                "merchantReference": "35D58738ACA345E3BB380D6003747DD8",
                "pspReference": "2098369735585562624",
                "resultCode": "SUCCEED",
                "amount": {
                    "currency": "USD",
                    "value": 200
                },
                "providerReference": "pi_3UESQJ08pryDCbBW1YEygC1u",
                "paymentMethod": "intercards",
                "completeTime": "2026-09-11T11:15:21.000+00:00",
                "orderCreateTime": "2026-09-11T11:15:15.000+00:00",
                "orderType": "transaction",
                "additionalData": null
            }
        ]
    },
    "success": true
}

两笔单的 merchantReference 相同（都是原交易的商户订单号），靠 pspReference 区分：
2098369735585562624 是原交易，CB2098370142512742400 是它的拒付单。
拒付单的 additionalData.originalReference 指回原交易，fundImpact 为 SETTLED_LOST
表示争议已判负、本金与手续费已扣除。

普通交易不是争议单，additionalData 为 null。

Updated 17 days ago

Did this page help you?