/cashin/check-refund 代收退款订单查询接口介绍

接口背景

/cashin/check-refund 提供给合作商的代收退款订单查询接口。合作商可以通过商户退款订单号 merchantOrderNo 或平台退款订单号 platOrderNo 查询退款订单的当前状态、退款金额、累计退款金额、退还手续费及原代收订单信息。

merchantOrderNo 和 platOrderNo 至少填写一个。如果两个字段同时填写，必须指向同一笔退款订单。退款查询成功仅表示系统已返回退款订单的当前信息，不代表退款最终成功；退款结果应以 orderStatus 为准。

接口请求地址

项目	内容
请求方式	GET
请求路径	/cashin/check-refund
Content-Type	application/json
接口用途	查询代收退款订单

接口接入规范

• common接入规范

接口请求字段

字段名	位置	类型	字段长度	是否必填	说明
X-Merchant-Id	Header	string	64	是	一级商户号，从请求头读取，用于隔离不同合作商的退款订单数据。
X-Timestamp	Header	int	19	是	Unix 秒级请求时间戳，用于请求时效校验。
X-Nonce	Header	string	64	是	请求防重放随机字符串。
Digest	Header	string	52	是	请求体摘要；GET 无请求体时按空字节计算，格式为 SHA-256=<Base64摘要>。
Authorization	Header	string	-	是	ES256 请求签名信息，其中 keyId 为合作商密钥版本号。
merchantOrderNo	Query	string	64	二选一	商户退款订单号；与 platOrderNo 至少填写一个。
platOrderNo	Query	string	64	二选一	平台退款订单号；与 merchantOrderNo 至少填写一个。

如果 merchantOrderNo 和 platOrderNo 同时填写但未指向同一笔退款订单，接口返回参数错误，不返回订单数据。

请求示例

GET /cashin/check-refund?merchantOrderNo=REFUND202608160001 HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<Base64摘要>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

接口响应字段

业务状态判断：dataStatus 为整数；dataStatus = 200 表示业务正常，此时 dataMsg = "SUCCESS"。非 200 表示业务错误，错误原因见 dataMsg。

接口使用统一的 status、msg、data 响应结构。接口响应成功不代表退款成功；退款仍在处理中时，合作商应继续查询或等待退款结果异步通知。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	退款订单查询结果；请求在验签、协议解析、参数校验或订单查询阶段失败时可能不返回。
data.subMerchantNo	string	64	是	二级商户号。
data.attach	string	128	是	原收款订单下单时合作商传入的 attach 值；下单时已传入则原样返回，未传入则为空。
data.merchantOrderNo	string	64	是	商户退款订单号。
data.platOrderNo	string	64	是	平台退款订单号。
data.origMerchantOrderNo	string	64	是	原商户代收订单号。
data.origPlatOrderNo	string	64	是	原平台代收订单号。
data.origAmount	decimal(25,2)	25,2	是	原代收订单金额。
data.origTotalRefundAmount	decimal(25,2)	25,2	是	原代收订单当前累计成功退还的本金金额，不包含手续费。
data.origTotalFeeRefundAmount	decimal(25,2)	25,2	是	原代收订单当前累计成功退还的手续费金额，不包含退款本金。
data.amount	decimal(25,2)	25,2	是	本次申请退还的本金金额，不包含手续费。
data.refundAmount	decimal(25,2)	25,2	是	本次成功退还的本金金额，不包含手续费；本次退还的手续费见 data.feeRefundAmount。
data.feeRefundAmount	decimal(25,2)	25,2	是	本次退还的手续费金额；未退还手续费时为 0。
data.currency	string	3	是	退款币种，与原订单币种一致，例如 BRL。
data.e2eId	string	64	否	Pix 端到端交易 ID；渠道尚未返回时可为空。
data.orderStatus	string	16	是	退款订单当前状态。
data.refundTime	int	19	否	退款时间，Unix 秒级时间戳。
data.dataStatus	int	-	是	响应码
data.dataMsg	string	128	是	与 dataStatus 对应

orderStatus 枚举

枚举值	状态说明	是否终态
PENDING	退款处理中；退款申请已受理，资金处理尚未完成，应继续查询或等待异步通知。	否
SUCCESS	退款成功；退款资金处理已经完成。	是
FAILED	退款失败；本次退款已经结束，可结合 dataMsg 查看失败原因。	是

响应示例

以下示例为原订单首次退款成功：退还本金 50.00、手续费 0.30，累计退款本金为 50.00，累计退还的手续费为 0.30。

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUB00000001",
    "attach": "order-source=checkout",
    "merchantOrderNo": "REFUND202608160001",
    "platOrderNo": "RFD202608160000000001",
    "origMerchantOrderNo": "CASHIN202608160001",
    "origPlatOrderNo": "BAS202608160000000001",
    "origAmount": 100.00,
    "origTotalRefundAmount": 50.00,
    "origTotalFeeRefundAmount": 0.30,
    "amount": 50,
    "refundAmount": 50.00,
    "feeRefundAmount": 0.30,
    "currency": "BRL",
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "refundTime": 1786887025,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}

接入注意事项

1. 查询范围由请求头 X-Merchant-Id 中的一级商户号限定，无需传入 subMerchantNo，不能通过订单号查询其他合作商的退款数据。
2. orderStatus 是判断退款结果的唯一业务状态字段，不能将接口 status = 200 当作退款成功。
3. 合作商应使用十进制高精度类型处理，并核对币种、原订单金额、本次退款金额和累计退款金额。
4. 退款查询接口用于同步超时、漏通知或状态核对场景。退款终态通知和主动查询可能同时到达，合作商应以退款订单号和状态进行幂等处理。

响应错误码

• 响应状态