支付引擎
支付引擎 Webhook 回调机制
支付引擎回调通知的接收、响应、验签和幂等处理规则。
适用范围
本页仅适用于支付引擎回调通知。团队 API 不使用这套 Webhook 回调签名规则。
全面了解 Cregis 事件推送机制：包含接收规范与签名防伪验证算法。
为何采用异步回调机制
由于区块链出块确认（网络同步）及 Cregis 风控引擎审核逻辑具有异步性和不可预估的时长，Cregis 的资金核心操作（如：WaaS 充值入账、业务平台提币、支付引擎订单成交 等）将全部基于 Webhook / Callback 作为最终业务确定状态的准则。使用回调而非长期 HTTP 短轮询（Polling）机制，能极致降低您服务器的 I/O 损耗。
在创建业务地址或提交提币申请时，您可以通过 callback_url 参数显式定义对应业务的接收入口。当该单据状态变化时（例如上链成功），Cregis 服务将主动向此 URL 推送通知。
接收与响应规范
- 请求体格式：
POST application/json - 响应成功标识：当您成功接收消息并处理完自身核心逻辑后，必须使响应返回
HTTP 200并且返回体内容必须精确等于 字符串success（纯文本，不可附加其他内容）。若返回其余状态码（如404,500）或返回体内容不是精确的success字符串，均视为当前通知处理失败。
成功与失败示例
成功响应示例：验签通过、幂等检查通过且业务处理成功后，返回 HTTP 200 和纯文本 success。
HTTP/1.1 200 OK
Content-Type: text/plain
success失败响应示例：以下返回体虽然包含 success，但不是纯文本 success，均不会被视为成功确认。任何非 HTTP 200 状态码也会被视为处理失败。
{
"code": "00000",
"message": "success"
}{
"code": "00000",
"msg": "success"
}{
"msg": "success"
}HTTP/1.1 500 Internal Server Error
success请在完成签名验证、幂等检查和核心业务处理后再返回 success；如果验签失败或业务处理失败，不要返回 success。
签名防伪验证
为了防止恶意攻击者向您的 callback_url 伪造订单，Cregis 在推送该回调时会在请求体中附加 sign 凭证签名加密字段、13位 timestamp 时间戳以及 nonce 随机字符串。
【如何验证真伪】
- 由于验签是贵方内部逻辑，无需额外获取新的 API_SECRET，直接使用发起请求时该项目的同一个
API KEY。 - 对您接到的一整个回调报文做字典排序剥离：在英文字典中，排列字段 key 顺序先按照第一个字母以升序排列，并按
key1value1key2value2...进行拼接。 - 将该拼接好的字符串作为后缀，挂在项目的 API_KEY 后面。
- 对合成的最终字符串做一次
MD5散列计算，转为小写即为本地生成的哈希戳。 - 本地计算的哈希戳与回调报文体中的
sign字段进行全等（===）匹配，若吻合即代表该通知系 Cregis 官方发送，不可篡改！