FuturePay 收单订单查询

1.请求地址（POST）

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

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

2.请求参数（JSON 格式）

参数可以 二选一传入：

参数名	类型	必填	说明
merchantReference	String	否	商户订单号
pspReference	String	否	FuturePay 平台订单号
providerReference	String	否	FuturePay 三方订单号

{
  "merchantReference": "商户订单号（可选）",
  "pspReference": "平台订单号（可选）",
  "providerReference": "平台订单号（可选）"
}

注意： merchantReference 和 pspReference 至少需传一个

3.响应参数（JSON格式）

顶层字段

参数名	类型	示例值	描述
code	String	"0"	响应码，0 表示成功
msg	String	"success"	响应消息
serverTime	Long	1747904980771	服务器时间戳（毫秒）
success	Boolean	true	请求是否成功
data	Object	见下表	订单数据对象

data 字段内参数

参数名	类型	示例值	描述
merchantReference	String	"3753595377629466860"	商户订单号
pspReference	String	"1925475282161106944"	FuturePay 平台订单号
resultCode	String	"SUCCEED"更多结果可参考该地址	订单处理结果
refusalReason	String	null	拒绝原因（如有）。与 failReason 取值相同
failReason	String	"Fraud"	失败或争议原因。与 refusalReason 取值相同，建议使用本字段（与订单列表查询接口一致）
amount	Object	见下表	支付金额信息
providerReference	String	"202505221940109000001888A0234862571"	支付渠道方订单号
paymentMethod	String	"cards"	支付方式（如 cards, alipay 等）
orderType	String	"transaction"	订单类型，见下表
completeTime	String	"2026-07-14T09:38:21.000+00:00"	订单完成时间，ISO-8601 格式
orderCreateTime	String	"2026-07-14T09:37:39.000+00:00"	订单创建时间，ISO-8601 格式
additionalData	Object	请参考示例响应	费用信息；争议类订单还包含争议信息

orderType 取值

取值	说明
`transaction`	收单交易
`refund`	退款
`chargeback`	正式拒付
`inquiry`	调单（发卡行索取资料，非拒付）
`rdr`	RDR 拒付预警
`ethoca`	Ethoca 拒付预警
`efw`	早期欺诈预警

争议类订单（chargeback、inquiry、rdr、ethoca、efw）的资金后果说明详见 Webhook 争议订单回调。

amount 字段内参数

参数名	类型	示例值	描述
currency	String	"USD"	币种代码
value	Long	1299	支付金额，单位为“分”

additionalData 对象字段

费用信息（所有订单类型）

字段名	类型	说明
ACQUIRING_FEE	Object	固定费
DISCOUNT_FEE	Object	百分比手续费
GATEWAY_FEE	Object	网关费
IOF_FEE	Object	税费

争议信息（仅争议类订单返回）

字段名	类型	说明
originalReference	String	原交易的 FuturePay 平台订单号，用它关联回被争议的那笔交易
fundImpact	String	资金影响，见下表
disputeDueBy	String	抗辩截止时间，UTC，格式 `yyyy-MM-dd HH:mm:ss`。仅 chargeback / inquiry
networkReasonCode	String	卡组织原因码。仅 chargeback / inquiry

fundImpact 取值

取值	说明
`AUTO_REFUNDED`	已自动退款，无需操作
`MERCHANT_ACTION`	需商户决定，当前尚未产生资金影响
`FROZEN`	本金及手续费已冻结，等待裁决
`SETTLED_WON`	争议已赢，冻结金额已释放
`SETTLED_LOST`	争议已输，已扣款
`NONE`	不影响资金

disputeDueBy 为抗辩截止时间，超过该时间提交证据会被卡组织拒绝，争议直接判输。 建议在收到争议后立即记录并设置提醒。

金额对象结构（ACQUIRING_FEE/ DISCOUNT_FEE/ GATEWAY_FEE/ IOF_FEE）

字段名	类型	说明
`currency`	String	币种，例如：`UGX`（乌干达先令）
`value`	String	金额，精确到小数点后10位

4.时间字段格式说明

本接口返回两种时间格式，解析时请注意区分：

字段	格式	示例
completeTime、orderCreateTime	ISO-8601（带时区）	`2026-07-14T09:38:21.000+00:00`
additionalData.disputeDueBy	`yyyy-MM-dd HH:mm:ss`（UTC）	`2026-09-19 00:00:00`

disputeDueBy 与 Webhook 回调中的同名字段格式一致，处理逻辑可复用。

5.示例

5.1 普通交易订单

{
    "code": "0",
    "msg": "success",
    "serverTime": 1784022863898,
    "data": {
        "merchantReference": "BB910AADF2C849369E2C393387B9AEB6",
        "pspReference": "2076964133567332352",
        "resultCode": "SUCCEED",
        "amount": {
            "currency": "USD",
            "value": 200
        },
        "providerReference": "202607141140108001001886I0281206515",
        "paymentMethod": "pix",
        "completeTime": "2026-07-14T09:38:21.000+00:00",
        "orderCreateTime": "2026-07-14T09:37:39.000+00:00",
        "orderType": "transaction",
        "additionalData": {
            "ACQUIRING_FEE": {
                "currency": "USD",
                "value": "0"
            },
            "IOF_FEE": {
                "currency": "BRL",
                "value": "5.185000000"
            },
            "DISCOUNT_FEE": {
                "currency": "BRL",
                "value": "10"
            },
            "GATEWAY_FEE": {
                "currency": "USD",
                "value": "0"
            }
        }
    },
    "success": true
}

5.2 拒付订单

{
    "code": "0",
    "msg": "success",
    "serverTime": 1789194960363,
    "data": {
        "merchantReference": "35D58738ACA345E3BB380D6003747DD8",
        "pspReference": "CB2098370142512742400",
        "resultCode": "FAILED",
        "refusalReason": "Fraud",
        "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": {
            "ACQUIRING_FEE": {
                "currency": "USD",
                "value": "10"
            },
            "originalReference": "2098369735585562624",
            "fundImpact": "SETTLED_LOST",
            "disputeDueBy": "2026-09-19 00:00:00",
            "networkReasonCode": "10.4"
        }
    },
    "success": true
}

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