Custom REST API Launch: FoxPay Checkout ohne Commerce-Plugin bauen
Nicht jeder Händler passt in ein Plugin. WooCommerce ist für viele Teams der schnellste Einstieg, aber Agenturen, Headless-Shops, B2B-Portale, Marktplätze und eigene ERP-nahe Backends brauchen oft einen direkteren Integrationspfad. Genau dafür ist die FoxPay REST API gedacht: Der Merchant-Server erstellt eine Payment Session, FoxPay übernimmt Hosted Checkout und Zahlungs-Handoff, und das Händlersystem verarbeitet den finalen Status über seine eigene Backend-Logik.
Wichtig ist dabei die Einordnung. Die API ist kein kleines Demo-Endpunktchen für Entwickler, die irgendwo einen Bezahlen-Button einbauen wollen. Sie ist ein Integrationspfad in eine vollständige Zahlungsinfrastruktur: Merchant-Prüfung, Payment-Method-Auswahl, Checkout-URL, Statusmodell, Webhook-Reconciliation, Dokumentation und OpenAPI-Vertrag gehören zusammen. Das ist für klassische Händler relevant, die einfach einen sauberen API-Checkout wollen. Es ist aber besonders wichtig für regulierte oder schwerer zu platzierende Geschäftsmodelle, bei denen Payment nicht nur Frontend-UX, sondern operativer Risikoprozess ist.
Der Integrationsgedanke: Backend zuerst, Checkout gehostet
Der Kernflow ist bewusst vertraut. Das Händlersystem besitzt die Order. Es berechnet Betrag, Währung, Warenkorb, Steuern, Rabatte und interne Referenzen. Danach ruft der Server POST /payments/initialize auf. FoxPay erstellt daraus eine Payment Session und gibt eine paymentUrl zurück. Der Käufer wird anschließend aus dem Shop, Portal oder der App in den gehosteten FoxPay Checkout weitergeleitet.
Diese Trennung ist wichtig. Der Händler muss keine sensible Zahlungslogik in Browser-Code verlagern und muss auch keine Bank- oder Provider-Flows selbst zusammensetzen. Gleichzeitig bleibt die technische Kontrolle dort, wo sie hingehört: im Backend. Der Shop entscheidet, wann eine Order zahlbar ist; FoxPay stellt die Payment Session und den Checkout-Handoff bereit; die finale Reconciliation läuft wieder im Backend des Händlers zusammen.
POST /payments/initialize: Was wirklich zählt
Die Initialisierung ist der Einstieg in den Zahlungsprozess, nicht der Zahlungsabschluss. Ein typischer, sanitisierter Request nutzt die etablierten Konzepte aus der FoxPay-Dokumentation:
POST https://app.foxpay.it/api/payments/initialize
Authorization: Bearer <server-side-api-key>
Content-Type: application/json
{
"merchantId": "merch_B2P18X",
"orderId": "ord_A7K39Q",
"amountCents": 123456,
"currency": "EUR",
"paymentMethod": "qr_pay"
}
Die Antwort enthält unter anderem die erzeugte Payment-Referenz, den Checkout-Link und den initialen Status:
{
"success": true,
"paymentId": "pay_A7K39Q",
"paymentUrl": "https://app.foxpay.it/p/pay_A7K39Q",
"status": "initialized"
}
Für Entwickler sind drei Punkte entscheidend. Erstens: amountCents ist ein Integer in Cent, kein Dezimalbetrag. Das reduziert Rundungsfehler und macht Reconciliation sauberer. Zweitens: API-Keys gehören ausschließlich auf den Server. Sie dürfen nicht in Browser-Bundles, Mobile Clients, öffentlichen Repositories oder Analytics-Logs auftauchen. Drittens: initialized bedeutet, dass der Checkout vorbereitet wurde. Es bedeutet nicht, dass die Zahlung erfolgreich war.
paymentUrl und Redirect-Handoff sauber behandeln
Nach der Initialisierung kann das Backend die paymentUrl an das Frontend zurückgeben. Der Browser navigiert dann in den gehosteten Checkout. Für Käufer fühlt sich das wie ein klarer Checkout-Schritt an. Für Entwickler bleibt der Flow kontrollierbar, weil die eigene Anwendung nicht erraten muss, welcher Zahlungsweg im Detail folgt.
Das Redirect-Ergebnis darf trotzdem nicht als alleinige Wahrheit behandelt werden. Ein Käufer kann den Tab schließen, eine Bank-Autorisierung später abschließen, zurückkehren, nicht zurückkehren oder mehrfach aktualisieren. Deshalb sollte der Return in den Shop vor allem UX leisten: Danke-Seite anzeigen, Status laden, Kundenservice-Hinweis geben, offene Zahlung erklären. Die Order im Backend sollte erst dann endgültig umgestellt werden, wenn die serverseitige Statuslogik belastbar ist.
Polling ist UX, Webhook ist Backend-Wahrheit
Polling ist nützlich. Nach dem Redirect kann ein Shop für einige Sekunden den Zahlungsstatus abrufen, damit Käufer nicht auf einer statischen Warteseite landen. Auch Support-Teams profitieren, wenn eine Oberfläche den aktuellen Stand einer Payment Session anzeigen kann.
Für Order-Fulfillment, Versandfreigabe, Rechnung, Lizenzaktivierung oder Buchhaltung sollte Polling aber nicht die Hauptquelle sein. Die belastbare Backend-Wahrheit ist der signierte Webhook. FoxPay unterstützt signierte Webhook-Semantik für Payment Status und Order Reconciliation. Das Händlersystem sollte die Signatur gegen den rohen Request Body prüfen, Events dauerhaft verarbeiten und erst danach interne Order-Zustände ändern.
Gerade regulierte Händler brauchen diese Disziplin. Ein falscher Status erzeugt nicht nur einen unschönen Checkout. Er erzeugt Supportaufwand, manuelle Prüfung, Auslieferungsrisiko und potenziell falsche Buchhaltungsdaten.
Idempotenz: Doppelte Events sind kein Fehlerfall, sondern Normalbetrieb
Robuste Payment-Systeme planen doppelte oder verzögerte Verarbeitung ein. Ein Webhook kann wiederholt zugestellt werden. Ein Käufer kann dieselbe Rückkehrseite mehrfach öffnen. Ein Backend kann nach einem Timeout erneut anfragen. Das sollte eine Integration nicht durcheinanderbringen.
Deshalb gehört Idempotenz früh ins Design. Praktisch heißt das: Eine Order darf nicht doppelt erfüllt werden, nur weil ein Event zweimal ankommt. Ein Payment darf nicht doppelt in internen Tabellen als bezahlt markiert werden. Retry- und Redelivery-Szenarien müssen nachvollziehbar bleiben. Entwickler sollten eigene Transaktionsgrenzen setzen, Payment- und Order-Referenzen speichern und Statuswechsel nur dann durchführen, wenn der neue Zustand fachlich erlaubt ist.
Das ist kein akademisches Thema. Für Agenturen und CTOs ist Idempotenz der Unterschied zwischen einem Checkout, der in der Demo funktioniert, und einer Integration, die nach Deployments, Netzwerkproblemen und Supportfällen stabil bleibt.
OpenAPI als Vertrag, nicht nur als Dokumentation
Die FoxPay API ist über öffentliche Developer-Dokumentation und ein OpenAPI-Artefakt nachvollziehbar. Für Integrationspartner ist das mehr als eine schöne Referenzseite. OpenAPI hilft, Request- und Response-Strukturen zu prüfen, interne Tickets präzise zu schreiben, Clients zu typisieren und QA-Szenarien aufzubauen.
Agenturen können damit sauberer zwischen Backend, Frontend und Projektleitung arbeiten. CTOs sehen, welche Teile des Zahlungsflusses vertraglich beschrieben sind. Entwickler können Beispiele übernehmen, ohne aus Marketingtexten zu raten. Besonders bei regulierten Händlern zählt diese Nachvollziehbarkeit, weil technische Entscheidungen später in Onboarding, Compliance, Support und Reconciliation wieder auftauchen.
Test, Live und sichere Umgebungen
Eine gute REST-Integration trennt Test und Live konsequent. Test-Credentials gehören in Staging- oder Sandbox-nahe Umgebungen, Live-Credentials nur in die Produktionsumgebung. Rücksprung-URLs, Webhook-Endpunkte und Logging sollten pro Umgebung geprüft werden. Wer mit mehreren Shops, Mandanten oder Merchant-Konten arbeitet, sollte außerdem klar dokumentieren, welcher API-Key zu welchem Merchant-Kontext gehört.
Secrets gehören in Server-Umgebungsvariablen oder ein Secret-Management-System. Sie gehören nicht in Beispielcode, Screenshots, Issue-Tickets oder Frontend-Konfiguration. Auch in Agenturprojekten sollte klar sein, wer Zugriff auf Live-Credentials hat und wie Schlüssel rotiert werden, falls ein Repository, ein Laptop oder ein externer Dienst kompromittiert wird.
Für wen der REST-Pfad passt
Der Custom-API-Pfad ist besonders sinnvoll, wenn eine Plugin-Integration zu eng wäre:
- Headless-Commerce mit eigenem Checkout
- B2B-Portale mit individuellen Zahlungsfreigaben
- Marktplätze oder Multi-Merchant-Architekturen
- ERP- oder Warenwirtschafts-nahe Order-Prozesse
- Agenturen, die mehrere regulierte Händler betreuen
- Teams, die WooCommerce nutzen, aber langfristig komplexere Logik brauchen
Für einfache WooCommerce-Shops bleibt das Plugin oft der schnellere Start. Für technische Teams mit eigener Backend-Verantwortung ist die REST API der kontrollierte Weg in dieselbe Zahlungsinfrastruktur.
Fazit: API-Checkout als Infrastrukturentscheidung
Der Custom REST API Launch macht FoxPay nicht nur flexibler, sondern strategisch relevanter. Händler müssen nicht zwischen Plugin-Komfort und komplett selbst gebauter Zahlungslogik wählen. Sie können Payment Sessions serverseitig erstellen, Käufer in einen gehosteten Checkout schicken, Status für UX abfragen und finale Wahrheit über signierte Webhooks verarbeiten.
Das ist der richtige Integrationspfad für Teams, die Payment ernst nehmen: nicht als Button, sondern als Betriebsprozess. Wer einen normalen oder regulierten Merchant-Stack ohne Commerce-Plugin anbinden will, sollte FoxPay daher früh im Backend-Design einplanen und die OpenAPI-Dokumentation als technischen Vertrag nutzen.
