Zum Inhalt springen
ArionPay

Wissensdatenbank · 6 Min. Lesezeit

White-Label-API: Zahlung auf Ihrer eigenen Website

Erstellen Sie eine Rechnung mit bereits gewähltem Coin, zeigen Sie den exakten Betrag und die Adresse auf Ihrer eigenen Bezahlseite und verfolgen Sie die Zahlung über die API und Webhooks.

White-Label-API: Zahlung auf Ihrer eigenen Website

Wann sie sich eignet

Normalerweise leiten Sie den Kunden zu invoice_url weiter, der ArionPay-Bezahlseite. Mit der White-Label-API zeigt stattdessen Ihre eigene Seite die Zahlung: Ihr Design, Ihre Sprache, Ihre Domain, und der Kunde verlässt Ihre Website nie. Das Geld geht weiterhin direkt an Ihre eigene Wallet, und ArionPay beobachtet weiterhin die Blockchain und meldet Ihnen, wenn die Rechnung bezahlt ist. Die Gebühr ist dieselbe: 0,5 % pro Zahlung. Einen Überblick gibt die White-Label-Seite.

1. Die Rechnung mit gewähltem Coin erstellen

Lassen Sie den Kunden zuerst auf Ihrer Seite einen Coin wählen. Senden Sie dann von Ihrem Server POST /api/v1/invoices mit asset auf diesen Coin gesetzt, zum Beispiel USDT_TRC20, USDC_POLYGON oder BTC. Die Codes, die Ihr Shop nutzen kann, finden Sie unter GET /api/v1/currencies. Die Antwort enthält bereits alles, was Ihre Seite braucht:

  • data.amount_crypto: der exakte zu sendende Betrag. An seinen letzten Ziffern erkennen wir, zu welcher Rechnung eine Zahlung gehört.
  • data.address: die Zahlungsadresse. In jedem Netzwerk ist das die Hauptadresse Ihrer Wallet.
  • data.expires_at: wann die Rechnung abläuft (standardmäßig nach 30 Minuten; expiresMin lässt sich von 5 bis 1440 einstellen).
  • data.id: die Rechnungs-ID für die nächsten Schritte.

Kann die Adresse aus einem vorübergehenden Grund nicht zugewiesen werden, erhalten Sie Status 503. Ohne idempotencyKey wird diese Rechnung storniert, und eine Wiederholung erstellt eine neue. Mit idempotencyKey bleibt die Rechnung erhalten: Wiederholen Sie die Anfrage mit demselben Schlüssel, dann wird sie abgeschlossen.

2. Auf Ihrer Seite anzeigen

  • Zeigen Sie den vollständigen Betrag mit allen Ziffern und einen Kopier-Button. Ein gerundeter Betrag kann nicht automatisch zugeordnet werden: Er geht an Payment Radar und wartet auf Ihre Entscheidung.
  • Zeigen Sie die Adresse, einen QR-Code und das Netzwerk, zum Beispiel „USDT auf TRON (TRC-20)“.
  • Zeigen Sie einen Countdown bis expires_at.
  • Fügen Sie einen Link zu invoice_url hinzu, etwa „Probleme? Auf der ArionPay-Seite bezahlen“. Dort findet der Kunde Buttons für Wallet-Apps, 9 Sprachen und das Formular zum Melden einer Transaktions-ID.

3. Die Zahlung verfolgen

  • Webhooks: invoice.pending, wenn die Zahlung gesehen wird, invoice.paid, wenn das Netzwerk sie bestätigt hat. Prüfen Sie die Signatur und geben Sie die Bestellung dann bei invoice.paid frei (Webhooks prüfen).
  • Solange der Kunde auf Ihrer Seite ist, kann Ihr Server außerdem bei GET /api/v1/invoices/:id folgende Werte abfragen: status (zum Beispiel NEW, PENDING, PAID oder EXPIRED), amountReceived, confirmations und requiredConfirmations. Die Abfrage teilt ArionPay auch mit, dass jemand wartet, sodass die Zahlung häufiger geprüft wird.

Sicher und innerhalb der Limits bleiben

  • Rufen Sie die API nur von Ihrem Server aus auf. Das API-Secret darf nie in den Browser gelangen: Ihre Seite fragt Ihren eigenen Server, und Ihr Server fragt ArionPay.
  • Fragen Sie jede offene Rechnung etwa alle 10 Sekunden ab, und hören Sie auf, wenn der Kunde die Seite verlässt. Jede signierte Anfrage wird nur einmal akzeptiert, und ein Server kann etwa 120 Anfragen pro Minute senden (300 pro Minute und Shop).
  • Zuerst testen: Mit test: true lautet die Adresse TEST-MODE-DO-NOT-SEND-FUNDS, und POST /api/v1/invoices/:id/simulate simuliert eine Zahlung. Siehe Testmodus.
// 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
}