API Reference

Create Checkout Order

Create a checkout order. Merchants do not need to build a custom checkout flow or UI — customers complete payment on the checkout page provided by AinePay.

Endpoint

Method: POST
Path: /api/merchant/checkout
Authentication: Required
Content-Type: application/x-www-form-urlencoded

Request Parameters

parameter	type	description	required	example
orderId	string	Merchant order ID, length 5~256, must be unique per merchant. AinePay uses it to identify the unique order and prevent duplicate payable orders for the same merchant order. If the merchant creates an order with the same order ID, the existing order information is returned.	yes	ORDER_10002
userId	string	Merchant-defined user ID in the AinePay system, length 5~256. It must stay stable for the same merchant user because it is also used to generate that user's payment address. The merchant should keep the mapping between this ID and the user in its own system.	yes	U_90001
coin	string(enum)	Token symbol	yes	USDT
chain	string(enum)	Blockchain code	yes	ETH
qty	decimal(string)	Payment amount, > 0, up to 2 decimal places	yes	88.00
collectAddress	string	This address must be registered in the merchant dashboard and in ACTIVE status. If provided, this collect address is used; otherwise the latest active collect address on the same chain is used.	no	0xabc...
confirmationType	string(enum)	Confirmation tier: `LOW` / `MEDIUM` / `HIGH`. On the ETH chain, the current rules are 1 / 3 / 64 confirmations. If omitted, it is calculated based on the amount: `qty > 1000U` uses `HIGH`, `qty > 100U` uses `MEDIUM`, otherwise `LOW`.	no	LOW
confirmUrl	string	Redirect URL after successful payment, length 10~2048	yes	https://merchant.example.com/pay/success
cancelUrl	string	Redirect URL after cancellation, length 10~2048	yes	https://merchant.example.com/pay/cancel

Response Fields

Top-level response structure:

field	type	description
`success`	boolean	`true` when the request succeeds.
`code`	integer	Business result code. Successful responses return `0`.
`data`	object	Checkout order business data.
`msg`	string	Typically `ok` on success; otherwise an error message.

Order data:

parameter	type	description	required	example
`data.id`	string	AinePay internal order ID.	yes	123457
`data.orderId`	string	Merchant-side order ID, same as the request.	yes	ORDER_10002
`data.merchantId`	integer	Merchant ID.	yes	20001
`data.userId`	string	The user ID assigned by the merchant in the AinePay system, same as the request.	yes	U_90001
`data.coin`	string(enum)	Coin, same as the request.	yes	USDT
`data.chain`	string(enum)	Blockchain code, same as the request.	yes	ETH
`data.address`	string	Payment address.	yes	0xabc...
`data.qty`	string	Order amount as string.	yes	88
`data.status`	string(enum)	Order status: `INIT`, `PENDING`, `PAID`, or `EXPIRED`.	yes	INIT
`data.expired`	integer	Order expiration timestamp in milliseconds.	yes	1760000600000
`data.payExpired`	integer	Checkout payment expiration timestamp in milliseconds.	yes	1760000300000
`data.payUrl`	string	Checkout URL, returned only when status is `INIT`.	conditional	https://checkout.ainepay.com?token=xxxx
`data.created`	integer	Creation timestamp in milliseconds.	yes	1760000000000
`data.updated`	integer	Last update timestamp in milliseconds.	yes	1760000000000

Example Response

{
  "success": true,
  "code": 0,
  "data": {
    "id": 123457,
    "orderId": "ORDER_10002",
    "merchantId": 20001,
    "userId": "U_90001",
    "coin": "USDT",
    "chain": "ETH",
    "address": "0xabc...",
    "qty": "88",
    "status": "INIT",
    "expired": 1760000600000,
    "payExpired": 1760000300000,
    "payUrl": "https://checkout.ainepay.com?token=xxxx",
    "created": 1760000000000,
    "updated": 1760000000000
  },
  "msg": "ok"
}

Notes

Repeated requests with the same orderId return the existing order instead of creating a second payable order.