代付退款结果回调通知合作商接口文档

1. 通知接口背景

adopay发生了退款，adopay处理退款完成后通知给合作商退款结果。

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

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	是	本次代付退款并非由商户主动发起；该字段取自 origPlatOrderNo 对应的原付款订单，为合作商调用付款下单接口时传入的 attach 值。原付款下单时已传入则原样返回，未传入则为空。
merchantOrderNo	string	64	是	本次退款的商户退款订单号。
platOrderNo	string	64	是	本次退款的平台退款订单号。
origMerchantOrderNo	string	64	是	原商户代付订单号。
origPlatOrderNo	string	64	是	原平台代付订单号。
origAmount	decimal(25,2)	25,2	是	原代付订单金额。
origTotalRefundAmount	decimal(25,2)	25,2	是	截至本次退款完成时，原代付订单累计退还的本金金额，不包含手续费。
origTotalFeeRefundAmount	decimal(25,2)	25,2	是	截至本次退款完成时，原代付订单累计退还的手续费金额，不包含退款本金。
refundAmount	decimal(25,2)	25,2	是	本次成功退还的本金金额，不包含手续费；本次退还的手续费见 feeRefundAmount。
feeRefundAmount	decimal(25,2)	25,2	是	本次退还的手续费金额；未退还手续费时为 0。
currency	string	3	是	退款币种，与原订单币种一致，例如 BRL。
e2eId	string	64	否	Pix 端到端交易 ID；渠道尚未返回时可为空。
refundTime	int	19	否	退款时间，Unix 秒级时间戳。
orderStatus	string	16	是	退款订单当前状态。
status	int	-	是	响应码
msg	string	128	是	与 status 对应

事件和状态对照

event	orderStatus	含义
PIX_CASHOUT_REFUND	SUCCESS	退款成功。

5. 请求示例

以下示例为原订单的首次退款：本次退还本金 200.00、手续费 2.50，原订单累计退款本金为 200.00，累计退还的手续费为 2.50。

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_REFUND",
  "subMerchantNo": "SUB10000000001",
  "attach": "merchant-data-001",
  "merchantOrderNo": "MR20260825000001",
  "platOrderNo": "PR20260825000001",
  "origMerchantOrderNo": "MO20260824000001",
  "origPlatOrderNo": "PO20260824000001",
  "origAmount": 1000.00,
  "origTotalRefundAmount": 200.00,
  "origTotalFeeRefundAmount": 2.50,
  "refundAmount": 200.00,
  "feeRefundAmount": 2.50,
  "currency": "BRL",
  "e2eId": "D1234567820260825123456789012345",
  "refundTime": 1786887025,
  "orderStatus": "SUCCESS"
}

6. 合作商响应要求

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

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

SUCCESS

7. 通知场景与重试次数

代付退款成功时，Adopay 会向合作商发送回调通知。

每笔通知首次发送失败后，最多重试 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 和 orderStatus 判断交易结果，不能只使用 event 判断成功或失败。