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; setexpiresMinfrom 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.pendingwhen the payment is seen,invoice.paidwhen the network has confirmed it. Check the signature, then release the order oninvoice.paid(how to verify webhooks). - While the customer is on your page, your server can also ask
GET /api/v1/invoices/:idforstatus(for example NEW, PENDING, PAID or EXPIRED),amountReceived,confirmationsandrequiredConfirmations. 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: truethe address isTEST-MODE-DO-NOT-SEND-FUNDS, andPOST /api/v1/invoices/:id/simulatepretends 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
}