API 参考

创建收银台订单

用于创建收银台订单，商户不需要自定义收银流程和界面，客户使用 AinePay 提供的收银台页面完成支付。

端点

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

请求参数

参数	类型	描述	是否必需	示例
orderId	string	商户订单 ID，长度 5~256，每个商户必须唯一。AinePay 使用它来标识唯一订单并防止为同一商户订单重复创建可支付订单。如果商户用同样的订单号创建订单，则返回之前相同订单号的订单信息。	是	ORDER_10002
userId	string	商户在 AinePay 系统中定义的用户 ID，长度 5~256。对于同一商户用户必须保持稳定，因为它也用于生成该用户的支付地址。商户应在自己的系统中维护此 ID 与用户的映射关系。	是	U_90001
coin	string(enum)	代币符号	是	USDT
chain	string(enum)	区块链代码	是	ETH
qty	decimal(string)	支付金额，> 0，最多 2 位小数	是	88.00
collectAddress	string	此地址需要在商户管理后台注册且是 ACTIVE 状态，如果提供则使用此归集地址，否则使用同一链上最新的活跃归集地址。	否	0xabc...
confirmationType	string(enum)	确认数层级：`LOW` / `MEDIUM` / `HIGH`。在 ETH 链上，当前规则为 1 / 3 / 64 次确认。如果省略则根据金额计算：`qty > 1000U` 使用 `HIGH`，`qty > 100U` 使用 `MEDIUM`，否则使用 `LOW`。	否	LOW
confirmUrl	string	支付成功后的重定向 URL，长度 10~2048	是	https://merchant.example.com/pay/success
cancelUrl	string	取消后的重定向 URL，长度 10~2048	是	https://merchant.example.com/pay/cancel

响应字段

顶层响应结构：

字段	类型	描述
`success`	boolean	请求成功时为 `true`。
`code`	integer	业务结果代码。成功响应返回 `0`。
`data`	object	收银台订单业务数据。
`msg`	string	成功时通常为 `ok`，其他为错误信息。

订单数据：

参数	类型	描述	是否必需	示例
`data.id`	string	AinePay 内部订单 ID。	是	123457
`data.orderId`	string	商户侧订单 ID，与请求同。	是	ORDER_10002
`data.merchantId`	integer	商户 ID。	是	20001
`data.userId`	string	商户给用户分配的在 AinePay 系统中的 ID，与请求同。	是	U_90001
`data.coin`	string(enum)	币种，与请求同。	是	USDT
`data.chain`	string(enum)	区块链代码，与请求同。	是	ETH
`data.address`	string	支付地址。	是	0xabc...
`data.qty`	string	订单金额字符串。	是	88
`data.status`	string(enum)	订单状态：`INIT`、`PENDING`、`PAID` 或 `EXPIRED`。	是	INIT
`data.expired`	integer	订单过期时间戳（毫秒）。	是	1760000600000
`data.payExpired`	integer	收银台支付过期时间（毫秒）。	是	1760000300000
`data.payUrl`	string	收银台 URL，仅在状态为 `INIT` 时返回。	条件性	https://checkout.ainepay.com?token=xxxx
`data.created`	integer	创建时间戳（毫秒）。	是	1760000000000
`data.updated`	integer	最后更新时间戳（毫秒）。	是	1760000000000

示例响应

{
  "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"
}

注意事项

使用相同 orderId 的重复请求会返回现有订单，而不是创建第二个可支付订单。