回调通知代付合作商接口文档
1. 通知接口背景
合作商发起 Pix 代付交易后，交易的最终结果可能无法在同步请求中确定。Adopay 在代付订单成功或失败后，通过 HTTP 异步回调将最终结果通知给合作商。
合作商应根据 platOrderNo 或 merchantOrderNo 对通知做幂等处理。同一订单可能因重试收到多次通知。
2. 回调地址和请求方式
| 项目 | 内容 |
|---|---|
| 请求方式 | POST |
| 请求地址 | {notifyUrl} |
| Content-Type | application/json |
| 接口用途 | 通知 Pix 代付最终结果 |
{notifyUrl} 为合作商提供的代付回调地址，必须是完整的 HTTP 或 HTTPS 地址。
3. 请求头字段
| 字段名 | 类型 | 字段长度 | 是否必传 | 说明 |
|---|---|---|---|---|
Content-Type | string | 16 | 是 | 固定为 application/json。 |
X-Merchant-Id | string | 64 | 是 | 接收通知的商户号。 |
X-Timestamp | string | 19 | 是 | Unix 秒级时间戳。 |
X-Nonce | string | 64 | 是 | 本次请求的随机串，用于防重放。 |
Digest | string | 52 | 是 | 原始请求体摘要，格式为 SHA-256=<Base64(SHA256(body_bytes))>。 |
Authorization | string | - | 是 | ES256 HTTP Signature 签名信息。 |
Digest 和 Authorization 均基于最终发送的原始 JSON 字节计算。合作商验签时不能先对 JSON 重新序列化。
4. 请求体字段
业务状态判断：status 为整数；status = 200 表示业务正常，此时 msg = "sucesso"。非 200 表示业务错误，错误原因见 msg。
| 字段名 | 类型 | 字段长度 | 是否必返 | 说明 |
|---|---|---|---|---|
event | string | 64 | 是 | 见下属事件枚举。 |
subMerchantNo | string | 64 | 是 | 该代付订单所属的二级商户号。 |
attach | string | 128 | 是 | 原付款订单下单时合作商传入的 attach 值；下单时已传入则原样返回，未传入则为空。 |
merchantOrderNo | string | 64 | 是 | 合作商发起代付时传入的商户订单号。 |
platOrderNo | string | 64 | 是 | Adopay 代付平台订单号。 |
orderStatus | string | 16 | 是 | 代付结果：SUCCESS 表示代付成功，FAILED 表示代付失败。 |
e2eId | string | 64 | 是 | 银行 E2E 交易号/外部渠道代付流水号；未生成时可为空。 |
amount | decimal | 25,2 | 是 | 商户订单金额。 |
receivedAmount | decimal | 25,2 | 是 | 收款方实际到账金额。 |
fee | decimal | 25,2 | 是 | 商户手续费；失败时为 0。 |
fromIspb | string | 16 | 是 | 付款机构 ISPB 编码。 |
fromIspbName | string | 512 | 是 | 付款机构名称。 |
fromCnpj | string | 64 | 是 | 付款方 CNPJ。 |
fromName | string | 128 | 是 | 付款方名称。 |
toPix | string | 64 | 是 | 收款方 Pix Key；属于敏感信息。 |
toIspb | string | 16 | 是 | 收款机构 ISPB 编码；未取得时可为空。 |
toIspbName | string | 512 | 是 | 收款机构名称；未取得时可为空。 |
toName | string | 128 | 是 | 收款人名称；属于敏感信息。 |
toCpfCnpj | string | 64 | 是 | 收款方 CPF/CNPJ；属于敏感信息。 |
payTime | int | 19 | 是 | 代付完成时间，Unix 秒级时间戳；未取得时为 0。 |
status | int | - | 是 | 响应码 |
msg | string | 128 | 是 | 与 status 对应 |
事件和状态对照
event | orderStatus | 含义 |
|---|---|---|
PIX_CASHOUT_SUCCESS | SUCCESS | 代付成功。 |
PIX_CASHOUT_ERROR | FAILED | 代付失败。 |
5. 请求示例
http
POST /notify/adopay/cashout HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786838460
X-Nonce: 4de901987ca14b25acf2639056ac6002
Digest: SHA-256=<REQUEST_BODY_SHA256_BASE64>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"
{
"status": 200,
"msg": "sucesso",
"event": "PIX_CASHOUT_SUCCESS",
"subMerchantNo": "SUBMERCHANT0001",
"attach": "merchant-data-001",
"merchantOrderNo": "CASHOUT202608170001",
"platOrderNo": "APS202608170000000001",
"orderStatus": "SUCCESS",
"e2eId": "E0000000020260817000000000000002",
"amount": 100.00,
"receivedAmount": 100.00,
"fee": 1.50,
"fromIspb": "87654321",
"fromIspbName": "ADOX INSTITUICAO DE PAGAMENTO LTDA",
"fromCnpj": "12345678000195",
"fromName": "",
"toPix": "maria.oliveira@example.com",
"toIspb": "60701190",
"toIspbName": "ITAÚ UNIBANCO S.A.",
"toName": "MARIA OLIVEIRA",
"toCpfCnpj": "12345678901",
"payTime": 1786838460
}6. 合作商响应要求
合作商完成幂等处理后，应返回 HTTP 200—299，且响应体严格为纯文本 SUCCESS 或 OK：
http
HTTP/1.1 200 OK
Content-Type: text/plain
SUCCESS7. 通知场景与重试次数
代付成功或代付失败时，Adopay 会向合作商发送回调通知。
每笔通知首次发送失败后，最多重试 9 次，合计最多发送 10 次。合作商成功接收并返回规定的成功响应后，不再重试。
是否重试由 HTTP 状态码和响应体共同决定：
| HTTP 状态码 | 响应体 | 处理结果 |
|---|---|---|
200—299 | 去除首尾空白后严格等于 SUCCESS 或 OK | 通知成功，不再重试 |
200—299 | 空响应体、JSON、其他文本或非规定大小写 | 通知失败，继续重试 |
非 2xx | 任意内容 | 通知失败，继续重试 |
| 未收到 HTTP 响应 | 网络超时或连接失败 | 通知失败，继续重试 |
SUCCESS 和 OK 区分大小写。例如 success、Success 或 {"status":"SUCCESS"} 均不会被识别为成功响应。HTTP 204 虽属于 2xx，但因响应体为空，仍会继续重试。
8. 接入注意事项
- 建议以
event和orderStatus判断交易结果，不能只使用event判断成功或失败。 - 收到成功通知时，应复核
amount、收款人和 Pix Key。 toPix、toName、fromCnpj和toCpfCnpj属于敏感信息，日志和审计系统中应脱敏存储。