收款订单查询

按商户订单号查询支付状态。

接口

GET /cashin/check

认证

Merchant Credential。详见 认证。

接口背景

商户通过商户订单号 merchantOrderNo 或 Pix 端到端交易 ID e2eId（银行交易流水号），查询自有收款订单的当前状态、金额、付款人信息及 Pix 交易信息。

本接口支持按商户订单号或 E2E ID 查询，具体规则及示例见下文。查询响应成功不代表收款成功，实际交易结果以 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	条件必填	商户订单号；与 e2eId 至少提供一个。
e2eId	Query	string	64	条件必填	Pix 端到端交易 ID；与 merchantOrderNo 至少提供一个。

查询规则

• 两个字段都未提供或都为空白时，请求会被拒绝；传入的字段均不能超过 64 字节。
• 仅传 merchantOrderNo 时，按当前商户下的商户订单号查询。
• 仅传 e2eId 时，按银行交易流水号定位支付记录，再查询当前商户下的关联订单。
• 同时传入时，优先使用 merchantOrderNo，不会校验 e2eId 是否匹配，也不会在商户订单号查询失败后改用 e2eId。建议每次只传一种查询条件。
• merchantOrderNo 与下单时使用的商户订单号一致。platOrderNo 仅在响应中返回，不支持作为本接口的查询条件。
• 尚未获得银行交易流水号时，请使用 merchantOrderNo 查询。

请求示例

GET /cashin/check?e2eId=E1234567820260816000000000000001 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>"

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

GET /cashin/check?merchantOrderNo=CASHIN202608160001 HTTP/1.1

接口响应字段

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

接口使用统一的 status、msg、data 响应结构。查询响应不代表收款成功，实际交易结果以 orderStatus 为准。

当前查询结果限制

当前版本在部分未找到订单、支付记录缺失或查询异常场景下，仍可能返回成功响应码，但订单字段为空或信息不完整。请同时检查 data.merchantOrderNo、data.platOrderNo 和 data.orderStatus；订单号或状态为空时不能据此确认订单存在或支付成功，也不要将空值或默认金额直接覆盖本地已有的支付结果。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	代收订单查询结果；请求在验签或协议解析阶段失败时可能不返回。
data.attach	string	128	是	原收款订单下单时商户传入的 attach 值；下单时已传入则原样返回，未传入则为空。
data.merchantOrderNo	string	64	条件必返	商户订单号，对应下单时的 merchantOrderNo。
data.platOrderNo	string	64	条件必返	平台订单号。
data.e2eId	string	64	条件必返	Pix 端到端交易 ID，对应银行侧支付流水号。
data.orderStatus	string	16	是	代收订单当前状态。
data.amount	decimal(25,2)	25,2	是	订单金额 / 应收金额。
data.payAmount	decimal(25,2)	25,2	是	实际支付金额。
data.fee	decimal(25,2)	25,2	是	手续费，巴西默认是BRL。
data.payerName	string	128	否	付款人姓名，通常在成功时返回。
data.payerTaxNo	string	64	否	支付方税号；CPF 为 11 位数字，CNPJ 为 14 位数字，通常在成功时返回。
data.payTime	int	19	条件必返	支付时间，Unix 秒级时间戳。
data.expireTime	int	19	条件必返	订单过期时间，Unix 秒级时间戳。
data.dataStatus	int	-	是	响应码
data.dataMsg	string	128	是	与 dataStatus 对应

orderStatus 枚举

枚举值	状态说明	是否终态
PENDING	待支付或处理中；应继续查询或等待异步通知。	否
SUCCESS	收款成功。	是
FAILED	收款失败。	是

响应示例

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "attach": "order-source=checkout",
    "merchantOrderNo": "CASHIN202608160001",
    "platOrderNo": "BAS202608160000000001",
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "amount": 100.00,
    "payAmount": 100.00,
    "fee": 0.60,
    "payerName": "Maria Oliveira",
    "payerTaxNo": "12345678901",
    "payTime": 1786887025,
    "expireTime": 1786901100,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}