白标 API:在您自己的网站上收款
适用场景
通常,您会把客户引导到 invoice_url,即 ArionPay 支付页面。使用白标 API 时,则由您自己的页面显示付款信息:您的设计、您的语言、您的域名,客户始终不会离开您的网站。资金仍然直接进入您自己的钱包,ArionPay 仍然监控区块链,并在账单付清时通知您。手续费不变,每笔付款 0.5%。概览请参阅白标页面。
1. 创建账单并选定币种
先让客户在您的页面上选择币种。然后从您的服务器发送 POST /api/v1/invoices,并将 asset 设为该币种,例如 USDT_TRC20、USDC_POLYGON 或 BTC。您的店铺可用的代码列在 GET /api/v1/currencies。响应中已包含您的页面所需的一切:
data.amount_crypto:需要发送的准确金额。我们根据其末尾几位数字识别付款属于哪张账单。data.address:收款地址。在每个网络上,它都是您钱包的主地址。data.expires_at:账单的过期时间(默认 30 分钟;可将expiresMin设为 5 至 1440)。data.id:账单 ID,用于后续步骤。
如果因临时原因无法分配地址,您会收到 503 状态码。未发送 idempotencyKey 时,该账单会被取消,重试会创建一张新账单。发送了 idempotencyKey 时,账单会保留:使用相同的键重试即可完成该账单。
2. 在您的页面上显示
- 显示包含每一位数字的完整金额,并提供复制按钮。四舍五入后的金额无法自动匹配:它会进入 Payment Radar,等待您的决定。
- 显示地址、二维码和网络,例如“TRON(TRC-20)上的 USDT”。
- 显示距离
expires_at的倒计时。 - 添加一个指向
invoice_url的链接,例如“遇到问题?在 ArionPay 页面付款”。客户在那里可以找到钱包应用按钮、9 种语言以及报告交易 ID 的表单。
3. 跟踪付款
- Webhook:看到付款时发送
invoice.pending,网络确认后发送invoice.paid。请先检查签名,然后在收到invoice.paid时放行订单(如何校验 Webhook)。 - 客户停留在您的页面上时,您的服务器还可以向
GET /api/v1/invoices/:id查询status(例如 NEW、PENDING、PAID 或 EXPIRED)、amountReceived、confirmations和requiredConfirmations。查询也会让 ArionPay 知道有人在等待,因此会更频繁地检查这笔付款。
保障安全,遵守限制
- 只从您的服务器调用 API。API 密钥绝不能出现在浏览器中:您的页面向您自己的服务器查询,再由您的服务器向 ArionPay 查询。
- 每张未付账单大约每 10 秒查询一次,客户离开页面后即停止。每个签名请求只会被接受一次,一台服务器每分钟大约可以发送 120 个请求(每个店铺每分钟 300 个)。
- 先测试:使用
test: true时,地址为TEST-MODE-DO-NOT-SEND-FUNDS,POST /api/v1/invoices/:id/simulate会模拟一笔付款。详见测试模式。
// Node.js 18+, as an ES module (for example checkout.mjs), on your server only:
// the API secret must never reach the browser
import crypto from 'node:crypto';
async function arionpay(method, path, payload) {
const ts = Math.floor(Date.now() / 1000);
const body = payload ? JSON.stringify(payload) : '';
// POST is signed over "timestamp.body", GET over "timestamp.GET path"
const signed = method === 'GET' ? `${ts}.GET ${path}` : `${ts}.${body}`;
const signature = crypto.createHmac('sha256', process.env.ARIONPAY_API_SECRET).update(signed).digest('hex');
// ARIONPAY_BASE_URL: the API address from the docs
const res = await fetch(process.env.ARIONPAY_BASE_URL + path, {
method,
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ARIONPAY_API_KEY, // pk_...
'x-timestamp': String(ts),
'x-signature': signature,
},
body: payload ? body : undefined,
});
if (!res.ok) throw new Error(`ArionPay answered ${res.status}`);
return res.json();
}
// 1. The customer chose USDT on TRON on your page
const { data } = await arionpay('POST', '/api/v1/invoices', {
amount: '49.00', currency: 'USD', orderId: 'ORD-1042', asset: 'USDT_TRC20',
});
// show data.amount_crypto, data.address and data.expires_at; keep data.id
// 2. While the customer waits (about every 10 seconds), or wait for the invoice.paid webhook
const invoice = await arionpay('GET', `/api/v1/invoices/${data.id}`);
if (invoice.status === 'PAID') {
// release the order
}