收款退款 Webhook

退款状态异步通知。

接口

POST /merchant-callback-url

认证

Merchant Credential。详见 认证。

1. 通知接口背景

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

同一笔退款订单可能因重试收到多次通知。商户应使用商户号与商户退款订单号，或 platOrderNo 进行幂等处理。

2. 回调地址和请求方式

Adopay 使用 POST 发送 JSON 通知，Content-Type 为 application/json。回调地址优先使用发起退款时上送的 notifyUrl；未上送时，使用商户已配置且启用的退款通知地址。地址必须是完整的 HTTP 或 HTTPS 地址。

验签与成功响应要求见 Webhook 规范。

3. 请求头字段

字段名	类型	是否必传	说明
Content-Type	string	是	固定为 application/json。
X-Merchant-Id	string	是	接收通知的商户号。
X-Timestamp	string	是	Unix 秒级时间戳。
X-Nonce	string	是	本次请求的随机串，用于防重放；每次重试重新生成。
Digest	string	是	原始请求体摘要，格式为 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	32	是	退款事件类型，见下方退款事件和状态说明。
attach	string	128	是	原收款订单下单时商户传入的 attach 值；下单时已传入则原样返回，未传入则为空。
merchantOrderNo	string	64	是	商户发起退款时传入的商户退款订单号。
platOrderNo	string	64	是	Adopay 平台退款订单号。
origMerchantOrderNo	string	64	是	原商户代收订单号。
origPlatOrderNo	string	64	是	原 Adopay 代收平台订单号。
origAmount	decimal(25,2)	25,2	是	原代收订单金额
origTotalRefundAmount	decimal(25,2)	25,2	是	截至本次退款处理完成时，原代收订单累计成功退还的本金金额，不包含手续费。
origTotalFeeRefundAmount	decimal(25,2)	25,2	是	截至本次退款处理完成时，原代收订单累计成功退还的手续费金额，不包含退款本金。
amount	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；渠道未返回时可为空。
orderStatus	string	16	是	退款结果：SUCCESS 表示退款成功，FAILED 表示退款失败。
refundTime	int	19	否	退款时间，Unix 秒级时间戳。
status	int	-	是	响应码
msg	string	128	是	与 status 对应

退款事件和状态说明

event	orderStatus	含义
QR_CODE_COPY_AND_PASTE_REFUNDED	SUCCESS	pix二维码代收/收单-退款成功。
QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR	FAILED	pix二维码代收/收单-退款失败。

回调仅通知退款终态。退款仍处于 PENDING 时不发送结果通知，商户可通过退款订单查询接口获取当前状态。

5. 请求示例

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

POST /notify/adopay/cashin/refund 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": "QR_CODE_COPY_AND_PASTE_REFUNDED",
  "attach": "order-source=checkout",
  "merchantOrderNo": "REFUND202608160001",
  "platOrderNo": "RFD202608160000000001",
  "origMerchantOrderNo": "CASHIN202608160001",
  "origPlatOrderNo": "BAS202608160000000001",
  "origAmount": 100,
  "origTotalRefundAmount": 50,
  "origTotalFeeRefundAmount": 0.30,
  "amount": 50,
  "refundAmount": 50,
  "feeRefundAmount": 0.3,
  "currency": "BRL",
  "e2eId": "E1234567820260816000000000000001",
  "orderStatus": "SUCCESS",
  "refundTime": 1786887025
}

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，但因响应体为空，仍会继续重试。

X-Timestamp、X-Nonce、Digest 和 Authorization 按本次发送重新生成。

8. 接入注意事项

1. 建议使用商户号 + 商户退款订单号（merchantOrderNo），或 platOrderNo 作为等价唯一键；不能根据通知次数判断是否重复。
2. 商户应先完成验签，再校验商户号、原订单号、退款订单号、币种及金额，全部一致后才能更新退款结果。
3. e2eId 及订单号应纳入审计记录；涉及商户、付款人或渠道的敏感信息时，日志中应脱敏或只记录摘要。
4. 验签、幂等处理和业务数据落库全部成功后再返回规定的成功响应，避免通知被错误确认后无法重试。