API marque blanche : le paiement sur votre propre site
Quand l’utiliser
D’habitude, vous envoyez le client vers invoice_url, la page de paiement ArionPay. Avec l’API marque blanche, c’est votre propre page qui affiche le paiement : votre design, votre langue, votre domaine, et le client ne quitte jamais votre site. L’argent arrive toujours directement sur votre propre portefeuille, et ArionPay surveille toujours la blockchain et vous prévient quand la facture est payée. Les frais sont les mêmes : 0,5 % par paiement. Pour une vue d’ensemble, voir la page marque blanche.
1. Créer la facture avec la crypto choisie
Laissez d’abord le client choisir une crypto sur votre page. Envoyez ensuite POST /api/v1/invoices depuis votre serveur, avec asset réglé sur cette crypto, par exemple USDT_TRC20, USDC_POLYGON ou BTC. Les codes que votre boutique peut utiliser sont listés par GET /api/v1/currencies. La réponse contient déjà tout ce dont votre page a besoin :
data.amount_crypto: le montant exact à envoyer. Ses derniers chiffres nous indiquent à quelle facture correspond un paiement.data.address: l’adresse à payer. Sur chaque réseau, c’est l’adresse principale de votre portefeuille.data.expires_at: le moment où la facture expire (30 minutes par défaut ; réglezexpiresMinentre 5 et 1440).data.id: l’ID de la facture, pour les étapes suivantes.
Si l’adresse ne peut pas être attribuée pour une raison temporaire, vous recevez le statut 503. Sans idempotencyKey, cette facture est annulée et une nouvelle tentative crée une nouvelle facture. Avec un idempotencyKey, la facture est conservée : réessayez avec la même clé et elle est finalisée.
2. L’afficher sur votre page
- Affichez le montant complet avec tous ses chiffres, et un bouton de copie. Un montant arrondi ne peut pas être associé automatiquement : il passe par Payment Radar et attend votre décision.
- Affichez l’adresse, un code QR et le réseau, par exemple « USDT sur TRON (TRC-20) ».
- Affichez un compte à rebours jusqu’à
expires_at. - Ajoutez un lien vers
invoice_url, par exemple « Un problème ? Payer sur la page ArionPay ». Le client y trouve des boutons pour les applis de portefeuille, 9 langues et le formulaire pour signaler un ID de transaction.
3. Suivre le paiement
- Webhooks :
invoice.pendingquand le paiement est vu,invoice.paidquand le réseau l’a confirmé. Vérifiez la signature, puis libérez la commande à réception deinvoice.paid(comment vérifier les webhooks). - Pendant que le client est sur votre page, votre serveur peut aussi demander à
GET /api/v1/invoices/:idles valeursstatus(par exemple NEW, PENDING, PAID ou EXPIRED),amountReceived,confirmationsetrequiredConfirmations. Cette demande indique aussi à ArionPay que quelqu’un attend : le paiement est donc vérifié plus souvent.
Sécurité et limites à respecter
- N’appelez l’API que depuis votre serveur. Le secret API ne doit jamais atteindre le navigateur : votre page interroge votre propre serveur, et votre serveur interroge ArionPay.
- Interrogez chaque facture ouverte environ toutes les 10 secondes, et arrêtez quand le client quitte la page. Chaque requête signée n’est acceptée qu’une fois, et un serveur peut envoyer environ 120 requêtes par minute (300 par minute et par boutique).
- Testez d’abord : avec
test: true, l’adresse estTEST-MODE-DO-NOT-SEND-FUNDS, etPOST /api/v1/invoices/:id/simulatesimule un paiement. Voir mode test.
// 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
}