发起支付（Alsopay）

准备工作

1. 在控制台「API 密钥」创建一对凭据：api_key_id 与 secret_key
2. 配置异步回调地址（callback_url）与 IP 白名单

接口

POST https://api.alsoluna.xyz/payments/v1/orders

完整地址（含你所在环境的 API 域）以控制台「支付设置 → 接入文档」展示的为准。

签名

1. 取出除 signature 外的全部参数
2. 按键名 ASCII 升序排序，拼接为 key1=value1&key2=value2...
3. signature = hex(HMAC-SHA256(拼接串, secret_key))，小写

const crypto = require('crypto')

function sign(params, secretKey) {
  const sorted = Object.keys(params)
    .filter((k) => k !== 'signature')
    .sort()
    .map((k) => k + '=' + params[k])
    .join('&')

  return crypto.createHmac('sha256', secretKey).update(sorted).digest('hex')
}

const order = await fetch('https://api.alsoluna.xyz/payments/v1/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key_id: '你的 api_key_id',
    reference: 'MERCHANT_ORDER_001',
    callback_url: 'https://merchant.example.com/notify',
    return_url: 'https://merchant.example.com/return',
    amount: '100.00',
    token: 'usdt',
    network: 'tron',
    signature: sign({ ... }, secretKey),
  }),
})

请求参数

参数	必填	说明
api_key_id	是	API 密钥 ID（API 密钥页创建）
reference	是	商户订单号（客户交易 id），需唯一
callback_url	是	异步回调地址
amount	是	订单金额（法币）
token	否	代币，如 usdt / trx / ton
network	否	网络，如 tron / ton
return_url	否	支付完成跳转地址
payment_channel	否	兼容标识，参与签名
signature	是	HMAC-SHA256 签名（小写 hex）

响应字段

字段	说明
transaction_id	平台交易号（查询状态与对账使用）
amount_due	应付数量 —— 必须按此数值精确等额转账（平台按「地址 + 金额」匹配入账，金额不符视为未到账）
receiving_address	收款地址
token	收款币种（status=4 的占位单为空）
network	收款网络（status=4 的占位单为空）
status	订单状态，见下方「查询支付状态」
expires_at	过期时间（秒级时间戳）
checkout_url	收银台地址（默认把付款人跳转到这里）

两种付款方式

方式一：跳转平台收银台（推荐）

把付款人打开到响应里的 checkout_url。二维码、倒计时、改链/改币、手动补单都由平台收银台提供，你不需要自己渲染付款界面。

方式二：自建付款页

用 receiving_address + amount_due 自行生成二维码，并轮询查单接口判断是否到账（该接口无需签名，服务端轮询即可）。

自建付款页的注意事项：

1. 付款人必须精确等额转账，金额不符不会被匹配入账
2. 下单时请显式传 token 与 network，否则会得到 status=4 的占位单，需先调用切换接口选链币
3. 若改由浏览器轮询，需把你的站点域加入平台跨域白名单

查询支付状态

GET https://api.alsoluna.xyz/gateway/check-status/{transaction_id}

无需签名。

值	说明
1	等待支付
2	支付成功（已入账，同时会发出回调）
3	已过期
4	等待选择支付网络/币种（占位单，字段未补全）

域名分工

• 单域部署（前后端同域）：上方接口地址与收银台同域，直接用即可
• 分离部署：商户服务端只访问 API 域；收银台页面在收银台域，其地址由下单响应里的 checkout_url 给出，请直接使用、不要自己拼接。付款页会跨域调用 API 域的状态接口，白名单由平台侧配置
• 收银台页面域不提供 /payments/* 商户接口，切勿把页面地址当作接口地址