API Reference

Create Inline Order

Create or retrieve an inline payment order. This endpoint returns full payment details for merchants to build custom payment flows and user interfaces.

Endpoint

Method: POST
Path: /api/merchant/pay
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_10001
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	100.12
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

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	Inline 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	123456
`data.orderId`	string	Merchant-side order ID, same as the request.	yes	ORDER_10001
`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`	object	Payment address info.	conditional	`{"address":"0xabc..."}`
`data.address.address`	string	Payment address.	conditional	0xabc...
`data.address.chain`	string	Blockchain code.	conditional	ETH
`data.address.coin`	string	Token symbol.	conditional	USDT
`data.address.contract`	string	Token contract address.	conditional	0x630E...
`data.address.name`	string	Blockchain name.	conditional	Ethereum(ERC20)
`data.address.url`	string	Reserved field.	conditional	https://...
`data.qty`	string	Order amount as string.	yes	100.12
`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	Payment page expiration timestamp in milliseconds.	yes	1760000300000
`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": 123456,
    "orderId": "ORDER_10001",
    "merchantId": 20001,
    "userId": "U_90001",
    "coin": "USDT",
    "chain": "ETH",
    "address": {
      "address": "0xabc...",
      "chain": "ETH",
      "coin": "USDT",
      "contract": "0x...",
      "name": "Ethereum(ERC20)",
      "url": ""
    },
    "qty": "100.12",
    "status": "INIT",
    "expired": 1760000600000,
    "payExpired": 1760000300000,
    "created": 1760000000000,
    "updated": 1760000000000
  },
  "msg": "ok"
}

Notes

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