Webhooks

支付通知

当订单最终状态确定时，AinePay 会给商户系统推送订单状态变化的通知以方便商户端及时处理。

端点

方法： POST
目标 URL： {notifyUrl}/ainepay/notify
认证： 需要签名验证
Content-Type： application/x-www-form-urlencoded
请求头： x-api-signature

投递行为

Webhook 在订单达到最终状态时创建。
在当前实现中，AinePay 为 PAID 和 EXPIRED 发送通知。
AinePay 将任何 HTTP 2xx 响应视为成功确认。
如果端点返回非 2xx 状态或请求失败，AinePay 会以指数退避方式重试。
当前重试基础延迟为 5 秒，每商户投递次数为 5，商户限流以 30 秒退避重新调度。

请求字段

字段	类型	描述	是否必需	示例
merchantId	string	商户 ID。	是	20001
orderId	string	商户订单 ID。	是	ORDER_10001
userId	string	商户定义的用户 ID。	是	U_90001
coin	string	代币符号。	是	USDT
chain	string	链代码。	是	ETH
qty	string	订单金额，格式化字符串。	是	88.00
status	string(enum)	最终订单状态。在当前实现中，Webhook 状态为 `PAID` 或 `EXPIRED`。	是	PAID
expired	integer	订单过期时间戳（毫秒）。	是	1760000600000
created	integer	订单创建时间戳（毫秒）。	是	1760000000000
updated	integer	订单最后更新时间戳（毫秒）。	是	1760000300000

签名验证

AinePay 使用商户的 Webhook 验证密钥签署 URL 编码的 Webhook 正文。
签名在 x-api-signature 中以小写十六进制发送。
签名输入是按字段名排序的规范 URL 编码表单字符串。
有关共享的 Java Webhook 验证示例，请参阅身份验证。

示例请求

POST /ainepay/notify HTTP/1.1
Host: merchant.example.com
Content-Type: application/x-www-form-urlencoded
x-api-signature: 08fbca6b485a773c764ee0b5933e7936d536cda67bb44c19667a41ae401d7036

chain=ETH&coin=USDT&created=1760000000000&expired=1760000600000&merchantId=20001&orderId=ORDER_10001&qty=88.00&status=PAID&updated=1760000300000&userId=U_90001

预期响应

字段	类型	描述
HTTP 状态	integer	返回任何 `2xx` 状态以确认成功接收。

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

ok

注意事项

按 orderId 幂等处理 Webhook。
将 Webhook 视为状态更新信号，然后使用查询订单确认最新订单状态后再执行最终业务操作。
如果签名无效，不要信任该数据。