Webhooks

Payment Notification

When an order reaches its final status, AinePay pushes a notification of the order status change to the merchant's system so the merchant can process it in a timely manner.

Endpoint

Method: POST
Target URL: {notifyUrl}/ainepay/notify
Authentication: Signature verification required
Content-Type: application/x-www-form-urlencoded
Header: x-api-signature

Delivery Behavior

A webhook is created when the order reaches a final state.
In the current implementation, AinePay sends notifications for PAID and EXPIRED.
AinePay treats any HTTP 2xx response as a successful acknowledgement.
If the endpoint returns a non-2xx status or the request fails, AinePay retries with exponential backoff.
The current retry base delay is 5s, the per-merchant delivery count is 5, and merchant throttling is rescheduled with a 30s backoff.

Request Fields

field	type	description	required	example
merchantId	string	Merchant ID.	yes	20001
orderId	string	Merchant order ID.	yes	ORDER_10001
userId	string	Merchant-defined user ID.	yes	U_90001
coin	string	Token symbol.	yes	USDT
chain	string	Chain code.	yes	ETH
qty	string	Order amount as a formatted string.	yes	88.00
status	string(enum)	Final order status. In the current implementation, the webhook status is `PAID` or `EXPIRED`.	yes	PAID
expired	integer	Order expiration timestamp in milliseconds.	yes	1760000600000
created	integer	Order creation timestamp in milliseconds.	yes	1760000000000
updated	integer	Order last update timestamp in milliseconds.	yes	1760000300000

Signature Verification

AinePay signs the URL-encoded webhook body with the merchant's webhook verification key.
The signature is sent in x-api-signature as lowercase hex.
The signing input is the canonical URL-encoded form string sorted by field name.
For the shared Java webhook verification example, see Authentication.

Example Request

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

Expected Response

field	type	description
HTTP status	integer	Return any `2xx` status to acknowledge successful receipt.

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

ok

Notes

Handle the webhook idempotently by orderId.
Treat the webhook as a status update signal, then use Query Orders to confirm the latest order status before executing your final business action.
If the signature is invalid, do not trust the payload.