API Reference

Authentication

All API requests must be signed with the request signing key and include an expiration window. AinePay signs webhook callbacks with the webhook verification key. This page covers the API request signing rules, webhook verification rules, and their corresponding examples.

Required headers

x-api-key - Merchant request signing key
x-api-signature - HMAC-SHA256 signature in lowercase hex
x-api-timestamp - client side current time in milliseconds
x-api-recv-window - allowed client time offset, usually 60000 milliseconds, maximum 180000 milliseconds

All requests only support form submission.

Signing rules

Collect query string parameters and form parameters.
Flatten all parameters into key-value pairs, including repeated keys.
Sort by key, then by value, both in ascending order.
URL-encode them using UTF-8.
Append timestamp and recvWindow.
Use the secret key and compute HMAC-SHA256.

Request Signing Example

A request can include query parameters, form parameters, indexed keys, and URL-encoded values together.

Query string: ?orderIds[1]=222&orderIds[0]=111
Form body: coin=USDT_ERC20&userId=1000000001&note=hello world
timestamp: 1761611071000
recvWindow: 60000
secretKey: sv_5n61GLATPVKKejONbmwQPg2LuXZwRlibgDuoDLUQzV4

Payload:

coin=USDT_ERC20&note=hello+world&orderIds%5B0%5D=111&orderIds%5B1%5D=222&userId=1000000001&timestamp=1761611071000&recvWindow=60000

Signature:

f10590f4f0f8fb2c63382276edf128061eb51b36ae5522d09d28376f03ee2d92

Webhook Verification Example

Callback fields are verified after parsing, sorting, and rebuilding the canonical string.

Raw callback body: userId=user_001&orderId=order123&status=PAID&merchantId=1001&coin=USDT&qty=1.11&expired=1767793122000&created=1767793122000&updated=1767793122000
notifySecret: sv_5n61GLATPVKKejONbmwQPg2LuXZwRlibgDuoDLUQzV4

Canonical string:

coin=USDT&created=1767793122000&expired=1767793122000&merchantId=1001&orderId=order123&qty=1.11&status=PAID&updated=1767793122000&userId=user_001

Signature:

08fbca6b485a773c764ee0b5933e7936d536cda67bb44c19667a41ae401d7036

Verification result: true

Java example code

See the full Java signing and verification example at ainepay-java-example.

TypeScript example code

See the full TypeScript signing and verification example at ainepay-ts-example.

Common mistakes

Signing parameters in the wrong order
Server clock drift causing timestamp rejection
Only form submission is supported