ADOPAY 开发者平台

外观

收款 Webhook ​

支付状态异步通知。

接口 ​

POST /merchant-callback-url

认证 ​

Merchant Credential。详见 认证。

1. 通知接口背景 ​

商户发起收款交易后，交易的最终结果可能无法在同步请求中确定。收款成功后，Adopay 通过 HTTP 异步回调将收款成功结果通知给商户；收款失败不发送回调通知。

商户应根据 platOrderNo 或 merchantOrderNo 对通知做幂等处理。同一订单可能因重试收到多次通知。

2. 回调地址和请求方式 ​

Adopay 使用 POST 向商户提供的收款回调地址发送 JSON 通知，Content-Type 为 application/json。回调地址必须是完整的 HTTP 或 HTTPS 地址。验签与成功响应要求见 Webhook 规范。

3. 请求头字段 ​

字段名类型字段长度是否必传说明
Content-Typestring16是固定为 application/json。
X-Merchant-Idstring64是接收通知的商户号。
X-Timestampstring19是Unix 秒级时间戳。
X-Noncestring64是本次请求的随机串，用于防重放。
Digeststring52是原始请求体摘要，格式为 SHA-256=<Base64(SHA256(body_bytes))>。
Authorizationstring不定长是ES256 HTTP Signature 签名信息。

Digest 和 Authorization 均基于最终发送的原始 JSON 字节计算。商户验签时不能先对 JSON 重新序列化。

4. 请求体字段 ​

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

字段名类型字段长度是否必返说明
eventstring64是见下属事件枚举。
attachstring128是原收款订单下单时商户传入的 attach 值；下单时已传入则原样返回，未传入则为空。
merchantOrderNostring64是商户下单时传入的商户订单号。
platOrderNostring64是Adopay 代收平台订单号。
orderStatusstring16是订单结果，固定为 SUCCESS，表示收款成功。
amountdecimal25,2是商户订单金额，商户应校验该字段。
payAmountdecimal25,2是实际支付金额；
feedecimal25,2是手续费。
payTimeint19是付款完成时间，Unix 秒级时间戳；未取得时为 0。
e2eIdstring64是银行 E2E 交易号/外部渠道支付流水号；未生成时可为空。
payerNamestring128否付款方名称，通常在成功时返回。
payerTaxNostring64否支付方税号（CPF/CNPJ），通常在成功时返回。
statusint-是响应码
msgstring128是与 status 对应

事件和状态对照 ​

eventorderStatus含义
QR_CODE_COPY_AND_PASTE_PAIDSUCCESSpix二维码代收/收单-收款成功。

5. 请求示例 ​

http
POST /notify/adopay/cashin HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786838400
X-Nonce: 8f6e17d07f8b4fe19318d9c4dd6fc001
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": "QR_CODE_COPY_AND_PASTE_PAID",
  "attach": "order-source=checkout",
  "merchantOrderNo": "CASHIN202608170001",
  "platOrderNo": "BAS202608170000000001",
  "orderStatus": "SUCCESS",
  "amount": 100.25,
  "payAmount": 100.25,
  "fee": 1.25,
  "payTime": 1786838400,
  "e2eId": "E0000000020260817000000000000001",
  "payerName": "JOAO DA SILVA",
  "payerTaxNo": "12345678901"
}

6. 商户响应要求 ​

商户完成幂等处理后，应返回 HTTP 200—299，且响应体严格为纯文本 SUCCESS 或 OK：

http
HTTP/1.1 200 OK
Content-Type: text/plain

SUCCESS

7. 通知场景与重试次数 ​

仅在收款成功时，Adopay 向商户发送本回调通知。收款失败不回调；退款通知见 收款退款 Webhook。

每笔通知首次发送失败后，最多重试 9 次，合计最多发送 10 次。商户成功接收并返回规定的成功响应后，不再重试。

是否重试由 HTTP 状态码和响应体共同决定：

HTTP 状态码响应体处理结果
200—299去除首尾空白后严格等于 SUCCESS 或 OK通知成功，不再重试
200—299空响应体、JSON、其他文本或非规定大小写通知失败，继续重试
非 2xx任意内容通知失败，继续重试
未收到 HTTP 响应网络超时或连接失败通知失败，继续重试

SUCCESS 和 OK 区分大小写。例如 success、Success 或 {"status":"SUCCESS"} 均不会被识别为成功响应。HTTP 204 虽属于 2xx，但因响应体为空，仍会继续重试。

8. 接入注意事项 ​

  1. 应校验 event 为 QR_CODE_COPY_AND_PASTE_PAID，且 orderStatus 为 SUCCESS。
  2. 收到成功通知时，应复核 amount。
  3. payerName 和 payerTaxNo 属于敏感信息，日志和审计系统中应脱敏存储。