跳到正文

知识库 · 阅读约 6 分钟

白标 API:在您自己的网站上收款

创建一张已选定币种的账单,在您自己的结账页面上显示准确金额和地址,并通过 API 和 Webhook 跟踪付款。

白标 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
}