Aller au contenu
ArionPay

Base de connaissances · 6 min de lecture

API marque blanche : le paiement sur votre propre site

Créez une facture avec la crypto déjà choisie, affichez le montant exact et l’adresse sur votre propre page de paiement, et suivez le paiement avec l’API et les webhooks.

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églez expiresMin entre 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.pending quand le paiement est vu, invoice.paid quand le réseau l’a confirmé. Vérifiez la signature, puis libérez la commande à réception de invoice.paid (comment vérifier les webhooks).
  • Pendant que le client est sur votre page, votre serveur peut aussi demander à GET /api/v1/invoices/:id les valeurs status (par exemple NEW, PENDING, PAID ou EXPIRED), amountReceived, confirmations et requiredConfirmations. 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 est TEST-MODE-DO-NOT-SEND-FUNDS, et POST /api/v1/invoices/:id/simulate simule 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
}