Crypto POS API-Integration: Checkout, Kassenterminals und Auszahlungen

Onlineshops und Checkout-Widgets decken die meisten Verkäufer ab. Wenn Sie aber ein eigenes SaaS-Backend betreiben, einen Spiele-Launcher, einen Discord-Bot oder die Kassensoftware eines Ladengeschäfts, wollen Sie Krypto-Zahlungen direkt in Ihre eigenen Systeme einbinden. Dafür ist eine Crypto POS API da.

Dieser Leitfaden führt durch eine vollständige Crypto POS API-Integration: Rechnungen auf Ihrem Server erstellen, auf Webhooks reagieren, ohne eine Bestellung doppelt auszuliefern, Krypto am Kassenterminal annehmen sowie Erstattungen und Auszahlungen abgleichen. Die Muster gelten für jeden Anbieter. Wo es hilft, zeigen wir, wie sie sich auf PapelShip abbilden.

Wann brauchen Sie eine Crypto POS API?

Eine API ist die flexibelste Art, Krypto-Zahlungen anzunehmen, und zugleich die aufwendigste. Prüfen Sie vor dem Schreiben von Code, ob eine fertige Lösung bereits abdeckt, was Sie brauchen.

Greifen Sie zur API, wenn die Bestellung in Ihrem System liegt und nicht in einem Shop: ein Abo in Ihrem SaaS, ein Kauf innerhalb einer Desktop-App, ein Bot, der Zugänge verkauft, oder eine Kassenanwendung an der Theke. Brauchen Sie nur einen Zahlungsbutton auf einer bestehenden Website, ist das Checkout-Widget schneller einsatzbereit und einfacher zu pflegen.

So funktioniert eine Crypto POS API-Integration

Jede Integration hat dieselbe Struktur. Ihr Server erstellt die Zahlung, der Kunde zahlt auf einer Seite oder einem Bildschirm, den Sie ihm zeigen, und die Zahlungsplattform meldet Ihrem Server, was passiert ist. Eine Regel hält das sicher: Der Client entscheidet nie, ob eine Bestellung bezahlt ist.

Die Zahlung selbst findet zwischen der Wallet des Kunden und der Blockchain statt. Die Plattform beobachtet die Chain, zählt Bestätigungen und bewegt die Rechnung durch ihre Zustände, wie in Krypto-Zahlungsabwicklung vom Checkout bis zum Settlement beschrieben. Ihre Integration braucht nie einen Knoten oder einen Block-Explorer.

Schritt 1: Krypto-Rechnungen auf Ihrem Server erstellen

Wenn ein Kunde kauft, fragt Ihr Backend die API nach einer Rechnung mit Betrag, Ihrer Währung und Ihrer eigenen Bestellreferenz an. Die Antwort liefert eine Rechnungs-ID, die Sie an der Bestellung speichern, und einen Ort, an dem der Kunde bezahlen kann.

// Illustrative: runs on your server, never in the browser or app
const res = await fetch(`${API_BASE}/invoices`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPELSHIP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.00",      // a string, never a float
    currency: "USD",
    reference: order.id,  // your own order ID
  }),
});

const invoice = await res.json();
await db.orders.update(order.id, { invoiceId: invoice.id, status: "pending" });
// Then send the customer to the payment page, or render it in your checkout

• –Halten Sie den API-Schlüssel auf dem Server. Alles, was in einem Browser-Bundle, einer mobilen App oder einem Desktop-Client ausgeliefert wird, lässt sich extrahieren. PapelShip zeigt einen neuen API-Schlüssel nur einmal an, wenn Sie ihn erstellen. Legen Sie ihn sofort in Ihrem Secrets-Manager ab und geben Sie ihn nie an Dritte weiter.
• –Übergeben Sie Beträge als Strings oder als ganzzahlige Minimaleinheiten. Rundungsfehler bei Fließkommazahlen sind der Grund, warum aus einer Bestellung über 49,00 $ still eine über 48,99 $ wird.
• –Speichern Sie die Rechnungs-ID, bevor Sie die Zahlungsseite anzeigen. Zahlt der Kunde und Ihr Server startet neu, wissen Sie trotzdem, zu welcher Bestellung die Zahlung gehört.
• –Lassen Sie die Plattform umrechnen. Legen Sie den Preis in Ihrer eigenen Währung fest. Die Rechnung bestimmt den Krypto-Betrag und dessen Ablauf.

Legen Sie fest, was passiert, wenn eine Rechnung unbezahlt abläuft. Die einfachste Regel: Der Kunde beginnt für dieselbe Bestellung eine neue Rechnung zum aktuellen Kurs, statt die alte wiederzubeleben. Behalten Sie die abgelaufene Rechnungs-ID in der Historie der Bestellung, damit eine verspätete Zahlung darauf weiterhin nachvollzogen und geprüft werden kann.

Schritt 2: Webhooks und Zahlungsstatus verarbeiten

Webhooks teilen Ihrem Backend mit, wenn sich der Status einer Rechnung ändert. Sie sind das schnellste Signal, das Sie bekommen, und zugleich das Signal, das am häufigsten falsch behandelt wird. Gehen Sie davon aus, dass ein Webhook zu spät, doppelt oder in falscher Reihenfolge ankommen kann, denn bei genügend Zahlungen passiert das irgendwann.

• –Antworten Sie schnell. Speichern Sie das Ereignis, geben Sie eine Erfolgsmeldung zurück und erledigen Sie die eigentliche Arbeit in einem Hintergrundjob.
• –Seien Sie idempotent. Nutzen Sie die Rechnungs-ID als Schlüssel, damit ein wiederholtes Ereignis keine Bestellung doppelt ausliefern kann.
• –Prüfen Sie vor der Auslieferung. Rufen Sie die Rechnung über die API ab und handeln Sie auf Grundlage dessen, was sie sagt, nicht allein auf Basis des Webhook-Inhalts. Signiert der Anbieter seine Webhooks, prüfen Sie auch die Signatur.
• –Behandeln Sie jeden Status. Teilweise bezahlte, zu prüfende und abgelaufene Zustände verdienen eine Reaktion in Ihrem System, nicht nur „abgeschlossen“.

// Illustrative
app.post("/webhooks/payments", async (req, res) => {
  await queue.add("payment-event", { invoiceId: req.body.invoiceId });
  res.sendStatus(200); // acknowledge quickly; the job does the work
});

queue.process("payment-event", async ({ invoiceId }) => {
  const invoice = await api.getInvoice(invoiceId); // the source of truth
  if (invoice.status !== "completed") return orders.setState(invoiceId, invoice.status);

  // Atomic: only one job can move the order from pending to fulfilling
  const claimed = await orders.claim(invoiceId, { from: "pending", to: "fulfilling" });
  if (!claimed) return; // duplicate event, already handled

  await deliver(invoiceId); // license key, file, role or account access
  await orders.markFulfilled(invoiceId, invoice.txHash);
});

Webhooks sind der schnelle Weg, nicht der einzige. Betreiben Sie einen kleinen geplanten Job, der alle Rechnungen abruft, die nach ihrem Ablauf noch offen sind, und ihren Status anhand der API festschreibt. Er fängt das seltene Ereignis auf, das Ihr Endpunkt während eines Deployments verpasst hat, und sorgt dafür, dass ein Webhook-Ausfall Bestellungen verzögert, statt sie verloren gehen zu lassen.

Krypto an der Kasse: Kassenterminals und POS-Software

Eine Crypto POS API ist nicht nur für Websites da. Im Ladengeschäft läuft derselbe Rechnungsablauf über die Kasse: Der Kassierer erfasst den Verkauf, die POS-Software fragt Ihr Backend nach einer Rechnung, und ein kundenseitiger Bildschirm oder ein Tablet zeigt den QR-Code. Der Kunde scannt ihn mit seiner Wallet, und der Bildschirm aktualisiert sich, sobald die Zahlung erkannt und bestätigt wurde.

1. 01

   Verkauf erfassen

   Die POS-Software sendet die Warenkorbsumme und eine Kassenreferenz an Ihr Backend, das die Rechnung erstellt. Die Kasse spricht nie direkt mit der Zahlungs-API.

2. 02

   QR-Code anzeigen

   Ein Kundendisplay zeigt Betrag, Münze, Netzwerk und QR-Code. Machen Sie das Netzwerk genauso auffällig wie den Betrag. Der Beitrag So akzeptieren Sie USDT-Zahlungen erklärt, warum.

3. 03

   Status verfolgen

   Die Kasse fragt Ihr Backend ab oder empfängt von ihm einen Push, bis die Rechnung von erkannt zu abgeschlossen wechselt.

4. 04

   Beleg drucken oder senden

   Speichern Sie den Transaktions-Hash mit dem Verkauf, damit sich eine Erstattung oder Rückfrage Monate später in Sekunden nachverfolgen lässt.

Zwei Entscheidungen machen Krypto im Laden alltäglich. Lenken Sie Kunden zu Netzwerken mit schnellen Blöcken, damit niemand an der Kasse auf eine langsame Chain warten muss. Und legen Sie im Voraus fest, was das Personal tun soll, wenn eine Zahlung erkannt, aber noch nicht bestätigt ist. Bei kleinen Käufen akzeptieren manche Händler dieses kurze Risiko. Bei allem Wertvollen warten sie auf die Bestätigung.

Planen Sie außerdem für Verbindungsabbrüche. Verliert die Kasse mitten in der Zahlung die Verbindung, erreicht die Überweisung des Kunden trotzdem die Chain. Verbindet sich die Kasse wieder, sollte sie den aktuellen Status der Rechnung bei Ihrem Backend abfragen, statt von einem fehlgeschlagenen Verkauf auszugehen. Und das Personal sollte einen Kunden erst dann bitten, ein zweites Mal zu zahlen, wenn es nachgesehen hat.

Kartenterminals bleiben daneben bestehen und werden davon nicht ersetzt. Das POS-API-Routing von PapelShip ist darauf ausgelegt, bestehende Terminals, eigene POS-Endpunkte und lokale Virtual-POS-Gateways anzubinden. So landen Karten- und Krypto-Verkäufe von der Theke im selben Arbeitsbereich wie Ihre Onlinebestellungen.

Auszahlungen, Erstattungen und Abgleich

Bei einem verwahrenden Dienstleister bedeutet „Auszahlung“, dass Sie Ihr Guthaben nach dem Zeitplan des Dienstleisters abheben. Beim direkten Settlement entfällt für Krypto der Auszahlungsschritt ganz: PapelShip Crypto POS sendet jede Zahlung direkt an Ihre eigene Wallet, ohne dass eine Zwischenstelle die Gelder hält. Übrig bleibt der Abgleich. Sie stellen sicher, dass jede Münze in der Wallet einer Bestellung zugeordnet ist und jede Bestellung einer Münze. Speichern Sie folgende Felder bei jeder Krypto-Bestellung:

• –Die Rechnungs-ID der Plattform, neben Ihrer eigenen Bestellnummer
• –Münze und Netzwerk, zum Beispiel USDT auf Tron
• –Der empfangene Krypto-Betrag und der Fiat-Betrag, zu dem er angeboten wurde
• –Der Transaktions-Hash, damit jeder die Zahlung in einem Block-Explorer prüfen kann
• –Ein Erstattungsstatus: nicht erstattet, teilweise erstattet oder vollständig erstattet

Krypto-Erstattungen sind neue Überweisungen aus Ihrer Wallet an den Kunden. Sie sollten dennoch auf der ursprünglichen Bestellung erfasst werden, damit Ihre Umsatzberichte korrekt bleiben. Fragen Sie den Kunden nach einer Erstattungsadresse im Netzwerk, in dem er bezahlt hat, und senden Sie nicht an die Adresse, von der die Zahlung kam. Diese gehört oft einer Börse.

Kartenzahlungen werden über Ihr verbundenes Gateway nach dessen eigenen Bedingungen abgewickelt. Umsätze aus dem Reseller-Geschäft sind wieder anders: Mit dem Reseller-System von PapelShip lassen sich Forderungen automatisch Resellern zuordnen und über Ihr PapelShip-E-Commerce-Konto einziehen. Die Reseller-Umsätze fließen auf Ihr PapelShip-Guthaben. Das Dashboard erfasst jede Transaktion, Auszahlung und Erstattung in einer Ansicht. Genau diese Übersicht wird Ihr Steuerberater verlangen.

Checkliste für die Crypto POS API-Integration

• –API-Schlüssel nur serverseitig gespeichert, in einem Secrets-Manager
• –Preise und Rechnungen werden vom Backend erstellt, nie vom Client
• –Rechnungs-ID an der Bestellung gespeichert, bevor der Kunde zahlt
• –Webhook-Endpunkt, der schnell bestätigt und im Hintergrund verarbeitet
• –Idempotente Auslieferung mit der Rechnungs-ID als Schlüssel
• –Status vor jeder Auslieferung über die API bestätigt
• –Jeder Zustand behandelt, auch teilweise bezahlt, zu prüfen und abgelaufen
• –Transaktions-Hash und Netzwerk bei jeder Zahlung erfasst
• –Erstattungen auf der ursprünglichen Bestellung erfasst
• –Ein vollständiger Testlauf, einschließlich eines doppelten Webhooks und einer abgelaufenen Rechnung

Verkaufen Sie Zugänge über einen Bot? Sobald eine Rechnung abgeschlossen ist, kann derselbe Ablauf Discord-Rollen für digitale Produkte vergeben. In einem PapelShip-Onlineshop lassen sich Rollen je Produktvariante festlegen, ohne dass Sie diesen Teil selbst schreiben. Und wenn Sie noch entscheiden, ob Krypto überhaupt in Ihren Checkout gehört, beginnen Sie mit Was ein Crypto POS System ist.

Krypto-Zahlungen in Ihr Produkt integrieren

Eine saubere Crypto POS API-Integration ist vor allem Disziplin. Erstellen Sie Rechnungen auf dem Server, behandeln Sie Webhooks als Signale, prüfen Sie vor der Auslieferung und halten Sie jede Erstattung an ihre ursprüngliche Zahlung gebunden.

Wenn Sie diese vier Punkte richtig umsetzen, wird Krypto nur eine weitere Zahlungsmethode in Ihrem System, die direkt in Ihre eigene Wallet abgerechnet wird.