退款订单查询

按商户退款单号查询退款详情。

接口

GET /cashin/check-refund

认证

Merchant Credential。详见 认证。

接口背景

商户通过商户退款订单号 merchantOrderNo 或平台退款订单号 platOrderNo，查询自有退款订单的当前状态、退款金额、累计退款金额、退还手续费及原收款订单信息。

两个退款订单号至少填写一个，同时填写时必须指向同一笔退款订单。查询成功仅表示已返回当前订单信息，不代表退款最终成功，退款结果应以 orderStatus 为准。本接口可用于同步超时、漏通知或状态核对场景。

接口请求字段

字段名	位置	类型	字段长度	是否必填	说明
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.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": {
    "attach": "order-source=checkout",
    "merchantOrderNo": "REFUND202608160001",
    "platOrderNo": "RFD202608160000000001",
    "origMerchantOrderNo": "CASHIN202608160001",
    "origPlatOrderNo": "BAS202608160000000001",
    "origAmount": 100,
    "origTotalRefundAmount": 50,
    "origTotalFeeRefundAmount": 0.30,
    "amount": 50,
    "refundAmount": 50,
    "feeRefundAmount": 0.3,
    "currency": "BRL",
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "refundTime": 1786887025,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}