商户创建结果回调通知接口文档

1. 通知接口背景

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

商户应根据 X-Merchant-Id、registrationNo 和 createStatus 对通知做幂等处理，并以 createStatus 判断创建结果。同一笔商户创建申请可能因重试收到多次通知。

2. 回调地址和请求方式

项目	内容
请求方式	POST
请求地址	{notifyUrl}
Content-Type	application/json
接口用途	通知二级商户创建最终结果

{notifyUrl} 为一级商户提供的商户创建结果回调地址，必须是完整的 HTTP 或 HTTPS 地址。

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。

字段名	类型	字段长度	是否必返	说明
seqNo	string	64	是	请求流水号。对应创建接口的seqNo
subMerchantNo	string	64	是	二级商户号；创建失败或尚未生成时可为空。
subMerchantName	string	128	是	二级商户名称。
createStatus	string	16	是	创建状态：SUCCESS 表示创建成功，FAILED 表示创建失败。
errorMsg	string	128	否	错误信息。
status	int	-	是	响应码
msg	string	128	是	与 status 对应

创建状态说明

createStatus	含义
SUCCESS	二级商户创建成功；subMerchantNo 应返回已创建的二级商户号。
FAILED	二级商户创建失败；subMerchantNo 可为空。

5. 请求示例

POST /notify/adopay/merchant/create 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",
  "seqNo":"1234234234234",
  "subMerchantNo": "92315566000200",
  "subMerchantName": "MERCHANT DEMO LTDA",
  "createStatus": "SUCCESS",
  "errorMsg": ""
}

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. 建议使用“一级商户号 + 注册号 + 创建状态”或等价唯一键实现幂等；不能仅依赖通知次数判断是否重复。
2. createStatus 为 SUCCESS 时，应校验并保存 subMerchantNo；为 FAILED 时，subMerchantNo 可能为空。
3. 金额单位为元，应使用十进制高精度类型处理 monthlyTransactionAmount 和 averageOrderAmount。
4. 商户名称、注册号、税号、官网和业务信息可能包含敏感或受限信息，日志和审计系统中应按数据分级要求脱敏存储。
5. 验签、幂等处理和业务数据落库全部成功后再返回规定的成功响应，避免通知被错误确认后无法重试。