/cashout/check 代付订单查询接口介绍

接口背景

/cashout/check 提供给合作商的 Pix 代付订单查询接口。合作商可以通过商户订单号 merchantOrderNo 或 Pix 端到端交易 ID e2eId（银行交易流水号）查询订单的当前状态、交易金额、手续费、收付款方信息及银行交易信息。

merchantOrderNo 和 e2eId 至少提供一个。查询范围由请求头 X-Merchant-Id 中的一级商户号限定，无需传入 subMerchantNo。订单金额、实际到账金额和手续费的单位均为 BRL。

接口请求地址

项目	内容
请求方式	GET
请求路径	/cashout/check
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	是	请求摘要，格式为 SHA-256=<Base64摘要>。GET 请求无报文体时使用空字节串计算。
Authorization	Header	string	不定长	是	ES256 请求签名信息，其中 keyId 为合作商密钥版本号。
merchantOrderNo	Query	string	64	条件必填	商户订单号；与 e2eId 至少提供一个。
e2eId	Query	string	64	条件必填	Pix 端到端交易 ID；与 merchantOrderNo 至少提供一个。

查询规则

• 两个字段都未提供或都为空白时，请求会被拒绝；传入的字段均不能超过 64 字节。
• 仅传 merchantOrderNo 或仅传 e2eId 时，按对应编号查询当前一级商户下的订单。
• 同时传入时，两个编号必须匹配同一订单；不匹配时返回未找到记录，不会退回到只按其中一个编号查询。
• 同一查询条件命中多笔 E2E 订单时返回查询异常，不会任取一笔订单返回。
• merchantOrderNo 与下单时使用的商户订单号一致。platOrderNo 仅在响应中返回，不支持作为本接口的查询条件。
• 尚未获得银行交易流水号时，请使用 merchantOrderNo 查询。

请求示例

GET /cashout/check?e2eId=E1234567820260816000000000000001 HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786845600
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>"

按商户订单号查询，或同时提供两个编号时，使用相同的认证请求头，并重新计算签名：

GET /cashout/check?merchantOrderNo=CASHOUT202608160001 HTTP/1.1

GET /cashout/check?merchantOrderNo=CASHOUT202608160001&e2eId=E1234567820260816000000000000001 HTTP/1.1

接口响应字段

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

接口使用统一的 status、msg、data 响应结构。查询成功表示系统已返回订单当前信息，不代表代付订单最终成功，交易结果应以 orderStatus 为准。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	代付订单查询结果；请求在验签、协议解析或订单查询阶段失败时可能不返回。
data.subMerchantNo	string	64	是	该代付订单所属的二级商户号。
data.attach	string	128	是	原付款订单下单时合作商传入的 attach 值；下单时已传入则原样返回，未传入则为空。
data.merchantOrderNo	string	64	是	商户订单号，对应下单时的 merchantOrderNo。
data.platOrderNo	string	64	是	平台订单号。
data.orderStatus	string	16	是	代付订单当前状态。
data.e2eId	string	64	否	Pix 端到端交易 ID。
data.amount	decimal	25,2	是	代付订单金额。
data.receivedAmount	decimal	25,2	是	收款方实际到账金额；交易未完成时可能为 0。
data.fee	decimal	25,2	是	代付手续费。
data.fromIspb	string	16	是	出款方银行或支付机构的 ISPB 编码。
data.fromIspbName	string	512	是	出款方银行或支付机构名称。
data.fromCnpj	string	64	是	出款方 CNPJ。
data.fromName	string	128	是	出款方名称。
data.toPix	string	64	是	收款方 Pix 账号或 Pix Key。
data.toIspb	string	16	是	收款方银行或支付机构的 ISPB 编码。
data.toIspbName	string	512	是	收款方银行或支付机构名称。
data.toName	string	128	是	收款人姓名。
data.toCpfCnpj	string	64	是	收款方 CPF 或 CNPJ。
data.payTime	int	19	是	支付时间或订单处理完成时间，Unix 秒级时间戳。
data.dataStatus	int	-	是	响应码
data.dataMsg	string	128	是	与 dataStatus 对应

orderStatus 枚举

枚举值	状态说明	是否终态
PENDING	处理中；代付订单仍在执行中，应继续查询或等待异步通知。	否
SUCCESS	代付成功；收款方已成功到账。	是
FAILED	代付失败；可结合 dataMsg 查看失败原因。	是

响应示例

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUBMERCHANT0001",
    "attach": "merchant-data-001",
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "orderStatus": "SUCCESS",
    "e2eId": "E1234567820260816000000000000001",
    "amount": 100.25,
    "receivedAmount": 99.75,
    "fee": 0.50,
    "fromIspb": "87654321",
    "fromIspbName": "Example Payment Institution",
    "fromCnpj": "12345678000195",
    "fromName": "Example Merchant Ltda.",
    "toPix": "maria.oliveira@example.com",
    "toIspb": "12345678",
    "toIspbName": "Example Receiving Institution",
    "toName": "Maria Oliveira",
    "toCpfCnpj": "12345678901",
    "payTime": 1786887025,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}

响应错误码

• 响应状态