Skip to content
ArionPay

Knowledge base · 6 min read

White-Label API: Payment on Your Own Site

Create an invoice with the coin already chosen, show the exact amount and the address on your own checkout page, and follow the payment with the API and webhooks.

White-Label API: Payment on Your Own Site

When to use it

Usually you send the customer to invoice_url, the ArionPay checkout page. With the white-label API your own page shows the payment instead: your design, your language, your domain, and the customer never leaves your site. The money still goes straight to your own wallet, and ArionPay still watches the blockchain and tells you when the invoice is paid. The fee is the same, 0.5% per payment. See the white-label page for an overview.

1. Create the invoice with the coin chosen

Let the customer pick a coin on your page first. Then send POST /api/v1/invoices from your server with asset set to that coin, for example USDT_TRC20, USDC_POLYGON or BTC. The codes your store can use are listed at GET /api/v1/currencies. The response already has everything your page needs:

  • data.amount_crypto: the exact amount to send. Its last digits tell us which invoice a payment is for.
  • data.address: the address to pay. On every network it is your wallet's main address.
  • data.expires_at: when the invoice expires (30 minutes by default; set expiresMin from 5 to 1440).
  • data.id: the invoice id, for the next steps.

If the address cannot be assigned for a temporary reason, you get status 503. Without an idempotencyKey, that invoice is cancelled and a retry creates a new one. With an idempotencyKey, the invoice is kept: retry with the same key and it is finished.

2. Show it on your page

  • Show the full amount with every digit, and a copy button. A rounded amount cannot be matched automatically: it goes to Payment Radar and waits for your decision.
  • Show the address, a QR code and the network, for example "USDT on TRON (TRC-20)".
  • Show a countdown to expires_at.
  • Add a link to invoice_url, such as "Having trouble? Pay on the ArionPay page". There the customer finds buttons for wallet apps, 9 languages and the form for reporting a transaction ID.

3. Follow the payment

  • Webhooks: invoice.pending when the payment is seen, invoice.paid when the network has confirmed it. Check the signature, then release the order on invoice.paid (how to verify webhooks).
  • While the customer is on your page, your server can also ask GET /api/v1/invoices/:id for status (for example NEW, PENDING, PAID or EXPIRED), amountReceived, confirmations and requiredConfirmations. Asking also tells ArionPay that someone is waiting, so the payment is checked more often.

Keep it safe and within the limits

  • Call the API only from your server. The API secret must never reach the browser: your page asks your own server, and your server asks ArionPay.
  • Ask about each open invoice about every 10 seconds, and stop when the customer leaves the page. Each signed request is accepted once, and one server can send about 120 requests a minute (300 a minute per store).
  • Test first: with test: true the address is TEST-MODE-DO-NOT-SEND-FUNDS, and POST /api/v1/invoices/:id/simulate pretends a payment. See test mode.
// 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
}