// stack · schnittstelle
PayPal ist der Bezahlweg, nach dem im deutschen Checkout am ehesten gesucht wird — und technisch eine dokumentierte Schnittstelle wie jede andere. Für siteway heißt das: Die Zahlung läuft auf deiner Website, nicht auf einer fremden Plattform. Diese Seite beschreibt den Ablauf, die serverseitige Bestätigung und die Wahl zwischen PayPal direkt und PayPal über einen Zahlungsdienstleister.
// definition
PayPal ist ein Zahlungsdienst, über den Käufer online bezahlen, ohne dem Händler Karten- oder Kontodaten zu übergeben. Der Käufer bestätigt die Zahlung in seinem eigenen PayPal-Zugang; was dort hinterlegt ist — Bankkonto, Karte, Guthaben — bleibt zwischen ihm und PayPal. Im deutschen Markt ist das ein Verfahren mit hoher Verbreitung: Viele Käufer erwarten es im Checkout, und sein Fehlen fällt eher auf als seine Anwesenheit.
Für eine Website ist PayPal damit vor allem eines: eine Schnittstelle. Unter developer.paypal.com dokumentiert PayPal eine REST-Schnittstelle mit Endpunkten für Bestellungen, dazu ein JavaScript-SDK für den Bezahlbutton im Frontend, Webhooks für Ereignisse rund um Zahlung, Erstattung und Streitfall sowie eine Sandbox-Umgebung, in der sich alles durchspielen lässt, bevor echtes Geld fließt.
Und es gibt zwei Wege dorthin. Entweder direkt über die PayPal-eigene Schnittstelle mit eigenem PayPal-Zugang. Oder als eine Zahlungsart innerhalb eines Zahlungsdienstleisters, der Karte, Lastschrift und weitere Verfahren ohnehin schon abwickelt. Beide führen zum selben Ergebnis auf der Website — sie unterscheiden sich in Verträgen, Auszahlung und darin, an wie vielen Stellen der Betrieb später stattfindet.
// praxis
serverseitig · nicht im browser
Die wichtigste Entscheidung fällt vor der ersten Zeile Code: Der Preis wird nicht aus dem Browser übernommen. Was ein Kauf kostet, steht auf dem Server — aus Warenkorb, Produktdaten, Steuer- und Versandregeln. Der Browser sagt, was gekauft werden soll; wie viel das kostet, rechnet der Server. Alles andere lässt sich mit den Entwicklerwerkzeugen jedes Browsers umschreiben.
Dann steht die Kette. Im Frontend liegt die Bezahlstrecke — der Bezahlbutton oder ein eigener Schritt im Checkout. Dahinter liegen zwei schmale, serverseitige Endpunkte: einer legt die Bestellung bei PayPal an und gibt ihre Kennung zurück, der zweite schließt die Zahlung ab, nachdem der Käufer sie bestätigt hat. Ein dritter Endpunkt nimmt später die Webhooks entgegen. Mehr Bewegliches braucht es nicht — und je weniger es ist, desto weniger kann schiefgehen.
Zugangsdaten liegen ausschließlich serverseitig. Die Client-ID identifiziert das Konto und darf im Frontend auftauchen; das Secret nicht. PayPal formuliert das in der Dokumentation knapp — den Schlüssel sicher aufbewahren — und legt ihn in den eigenen Beispielen als Umgebungsvariable ab. Wir halten es genauso: Secret in der Umgebung, nie im Repository, getrennt für Test- und Produktivbetrieb.
Getestet wird in der Sandbox, bevor irgendetwas live geht: erfolgreiche Zahlung, Abbruch mitten im Vorgang, abgelehnte Zahlung, Erstattung. Dazu die Fälle, die im Alltag wirklich passieren — der Käufer schließt das Fenster, nachdem er bestätigt hat, oder das Netz bricht zwischen Bestätigung und Abschluss weg. Genau dafür sind Webhooks da, und genau deshalb testen wir sie mit.
Und schließlich das, was in Angeboten gern fehlt: der Zustand danach. Eine Bestellung ist mit dem Kauf nicht fertig. Sie kann erstattet werden, ganz oder teilweise, und sie kann zum Streitfall werden. Die Website muss das abbilden — Status ändern, Zugang oder Download wieder entziehen, Benachrichtigung auslösen, alles protokollieren. Die buchbare Leistung dahinter beschreibt siteway unter Schnittstellenentwicklung.
// technik · 6 details
belegt aus der doku
Was hier steht, stammt aus der öffentlichen Dokumentation von PayPal — Endpunkte, Parameter und Ereignisnamen im Original. Konditionen und Gebühren stehen bewusst nicht dabei: Sie ändern sich, hängen am Vertrag und gehören in ein Angebot, nicht auf eine Technikseite.
// d-01zugang
Die Client-ID identifiziert das PayPal-Konto, das Secret authentifiziert sie. Beide werden gegen ein OAuth-Token getauscht, mit dem die Aufrufe dann laufen. PayPal weist in der Dokumentation ausdrücklich darauf hin, das Secret sicher aufzubewahren — bei uns liegt es in der Umgebung des Servers.
zweck: authentifizierung
// d-02ablauf
Die Orders-Schnittstelle kennt beide Schritte: Die Bestellung entsteht per POST auf /v2/checkout/orders, abgeschlossen wird sie per POST auf /v2/checkout/orders/{id}/capture. Beim Anlegen wird festgelegt, ob sofort eingezogen oder zunächst nur reserviert wird. Der Status läuft von CREATED über APPROVED nach COMPLETED.
zweck: zahlungsvorgang
// d-03frontend
Das PayPal-eigene JavaScript-SDK wird von www.paypal.com/sdk/js geladen, konfiguriert über Parameter wie client-id, currency, components und intent. Der Button ruft beim Klick den eigenen Server auf, um die Bestellung anzulegen, und meldet nach der Bestätigung zurück, damit der Server abschließt.
zweck: bezahlstrecke
// d-04test
PayPal beschreibt die Sandbox als in sich geschlossene Testumgebung, die die Produktivumgebung nachbildet, ohne echte Konten zu berühren. Mit dem Entwicklerzugang entstehen ein Geschäfts- und ein Privatkonto, weitere lassen sich anlegen. Eigene Zugangsdaten, eigene Basis-Adresse unter api-m.sandbox.paypal.com.
zweck: vor dem go-live
// d-05status
HTTPS-Aufrufe von PayPal an eine Adresse auf dem eigenen Server, sobald ein Ereignis eintritt — dokumentiert sind unter anderem CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED und PAYMENT.CAPTURE.PENDING. Die Echtheit wird geprüft, bevor irgendetwas verarbeitet wird; die Doku nennt dafür zwei Wege.
zweck: verlässlicher status
// d-06betrieb
Auch danach meldet PayPal weiter: PAYMENT.CAPTURE.REFUNDED, PAYMENT.REFUND.PENDING und PAYMENT.REFUND.FAILED für Erstattungen, CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED und CUSTOMER.DISPUTE.RESOLVED für Streitfälle. Die Website führt den Bestellstatus nach, statt eine Bestellung dauerhaft als bezahlt zu zeigen.
zweck: zustand nach dem kauf
Aus der Schnittstelle wird eine Bezahlstrecke: der Bezahlschritt im Checkout, eine Bestätigungsseite, die aus dem serverseitigen Ergebnis kommt und nicht aus einer Rückmeldung des Browsers, eine Bestellbestätigung per E-Mail und ein Bestelldatensatz im Backend, an dem die Redaktion oder der Vertrieb sieht, was Sache ist. Bei digitalen Gütern hängt die Freischaltung am selben Ergebnis — Zugang oder Download entstehen erst, wenn der Server die Zahlung bestätigt hat. Wie das als buchbarer Baustein aussieht, steht in der Expertise unter Shop & E-Commerce und Digitale Produkte, Abo & Payment.
Dazu kommen die unbequemen Zustände, die den Unterschied zwischen einer Demo und einem Produktivsystem ausmachen. Ein Käufer bestätigt und schließt das Fenster: Der Webhook trägt den Status nach. Ein Abschluss wird doppelt gemeldet: Die Verarbeitung ist so gebaut, dass dieselbe Meldung zweimal nichts Zusätzliches auslöst. Eine Zahlung bleibt in der Schwebe: Die Bestellung steht auf wartend, statt fälschlich als bezahlt zu gelten. Und jeder Vorgang wird protokolliert, damit im Zweifel nachvollziehbar ist, was wann passiert ist.
Beim Datenschutz ist der Punkt schnell benannt: Der Bezahlbutton lädt Fremdcode. Das SDK kommt von PayPal-Servern, es entsteht eine Verbindung zu einem Dritten, und das gehört in die Consent-Betrachtung und in die Datenschutzerklärung. Technisch heißt das meist: Der Button wird dort geladen, wo bezahlt wird, und nicht auf jeder Seite. Dazu kommen die üblichen Punkte — nur die nötigen Felder übertragen, Zugangsdaten serverseitig, Übertragung über TLS. Die rechtliche Bewertung gehört zu deinem Datenschutzbeauftragten oder deiner Kanzlei; wie wir die technische Seite behandeln, steht im Stack unter Sicherheit & Datenschutz.
// integration
drei systeme · ein muster
Der Weg ist in jedem System derselbe, und er ist überraschend kurz. Im Frontend liegt der Bezahlbutton beziehungsweise die Bezahlstrecke — dort, wo bezahlt wird, und nur dort. Dahinter liegt ein serverseitiger Endpunkt, der die Bestellung bei PayPal anlegt und sie nach der Bestätigung durch den Käufer wieder serverseitig abschließt. Die Zugangsdaten bleiben dabei auf dem Server, sie tauchen im ausgelieferten Markup nicht auf. Ein weiterer Endpunkt nimmt die Webhooks entgegen — sie sind die verlässliche Statusquelle, weil sie auch dann ankommen, wenn der Käufer sein Browserfenster längst geschlossen hat.
Daraus folgt die Regel, die über allem steht: Der Zahlungsstatus wird nie im Browser entschieden. Was im Browser läuft, kann verändert werden — der Betrag, die Rückmeldung, der Aufruf selbst. Eine Bestellung gilt deshalb erst dann als bezahlt, wenn der Server sie bei PayPal abgeschlossen und die Antwort geprüft hat, und der Webhook trägt diesen Stand anschließend unabhängig nach. Was das CMS darunter ändert, ist nicht die Mechanik, sondern nur die Frage, wie die Route heißt, wo die Zugangsdaten liegen und in welcher Template-Sprache die Bezahlseite entsteht.
// cms-01typo3
Wir bauen die Anbindung als eigene Extension. Darin liegen Controller-Routen für das Anlegen und das Bestätigen der Bestellung sowie eine eigene Route für den Webhook. Die Zugangsdaten kommen aus der Extension-Konfiguration oder einer Umgebungsvariablen und bleiben damit serverseitig. Die Bestellung liegt als Record im System, der Status wird bei jedem Ereignis nachgeführt. Bezahlseite, Bestätigung und Fehlerfall entstehen als Fluid-Templates; der Bezahlbutton wird nur auf der Bezahlseite eingebunden. Die Redaktion pflegt Texte rund um den Checkout wie gewohnt im Backend, ohne die Zahlungslogik zu berühren.
// cms-02wordpress
In WordPress entsteht die Anbindung als eigenes Plugin und nicht als Theme-Code — so bleibt sie beim Theme-Wechsel bestehen. Das Plugin registriert eigene REST-Routen: eine zum Anlegen der Bestellung, eine zum Abschließen, eine für den Webhook. Client-ID und Secret liegen in der wp-config.php oder in einer Umgebungsvariablen, nie im Theme und nie im Frontend. Die Bestellung wird als eigener Datensatz geführt und bei jedem Ereignis aktualisiert. Fürs Frontend kommen Template-Dateien und Blocks für den Editor dazu, damit die Redaktion die Bezahlseite dort platziert, wo sie hingehört.
// cms-03statamic
Statamic läuft auf Laravel, und das passt zu dieser Aufgabe besonders gut: Route plus Controller für das Anlegen und Abschließen der Bestellung, eine weitere Route für den Webhook, die Prüfung der Echtheit sauber davorgeschaltet. Client-ID und Secret liegen in der .env und werden über die Konfiguration gelesen. Für nachgelagerte Schritte — Bestätigungsmail, Freischaltung, Protokoll — stehen Queues bereit, sodass der Webhook schnell antwortet. Bezahlseite und Bestätigung rendern Antlers oder Blade; im Control Panel pflegt die Redaktion die Texte drumherum.
// entscheidung
zuordnung statt rangliste
Auf der Website sieht der Käufer in beiden Fällen dasselbe: einen PayPal-Button im Checkout. Der Unterschied liegt dahinter — in der Zahl der Verträge, der Auszahlungswege und der Stellen, an denen Erstattungen und Streitfälle bearbeitet werden. Stripe etwa dokumentiert PayPal als Zahlungsmethode für Konten in einer Reihe europäischer Länder, Deutschland eingeschlossen, und beschreibt daneben eine Variante mit dem eigenen PayPal-Konto. An drei Mustern lässt sich das zuordnen.
// e-01direkt
Wenige Zahlungsarten, PayPal als das eine Verfahren, das die Zielgruppe wirklich nutzt, und ein bestehender PayPal-Zugang: Dann ist der direkte Weg der kürzeste. Eigene Schnittstelle, eigene Sandbox, eigene Webhooks — und keine weitere Partei zwischen Website und Zahlung.
ein anbieter · ein zugang
// e-02dienstleister
Karte, Lastschrift, Rechnung, dazu PayPal: Läuft ohnehin ein Zahlungsdienstleister, ist PayPal dort eine Methode mehr. Ein Vertrag, ein Dashboard, ein Auszahlungsrhythmus, eine Abstimmung in der Buchhaltung — und im Code eine Schnittstelle statt zweier.
eine schnittstelle · viele zahlarten
// e-03nebeneinander
Kommt vor, und zwar aus guten Gründen — etwa wenn ein gewachsener PayPal-Zugang bleiben soll, während ein Dienstleister die übrigen Zahlarten übernimmt. Dann gilt: zwei Verträge, zwei Auszahlungswege, zwei Stellen für Erstattungen und Streitfälle. Auf der Website bleibt es ein Checkout — der Aufwand entsteht in der Buchhaltung.
zwei verträge · ein checkout
Fünf Fragen entscheiden die Richtung, und sie lassen sich in einem Gespräch beantworten. Welche Zahlarten braucht die Zielgruppe wirklich — und welche davon nur gefühlt? Gibt es bereits einen PayPal-Zugang oder einen Zahlungsdienstleister im Haus? Geht es um Einmalkäufe oder um wiederkehrende Zahlungen? Wer bearbeitet Erstattungen und Streitfälle, und in welchem System soll das passieren? Und was muss die Buchhaltung am Ende abstimmen können?
Erst danach fällt die Entscheidung, und sie fällt mit Begründung. Dieselbe Logik greift bei den anderen Verfahren: Stripe bündelt viele Zahlarten hinter einer Schnittstelle, Klarna deckt Rechnung und Ratenkauf ab. Welche Kombination ein Projekt bekommt, klären wir im Konzept — vor dem Bauen.
// faq
PayPal ist ein Zahlungsdienst, über den Käufer online bezahlen, ohne dem Händler Karten- oder Kontodaten zu übergeben — im deutschen Markt ein Verfahren, nach dem im Checkout regelmäßig gefragt wird. Für die Website zählt die technische Seite: PayPal dokumentiert unter developer.paypal.com eine REST-Schnittstelle, ein JavaScript-SDK für den Bezahlbutton im Frontend, Webhooks für Zahlungs- und Erstattungsereignisse sowie eine Sandbox-Umgebung zum Testen. Damit lässt sich die Zahlung in die eigene Website einbauen, statt Käufer auf eine fremde Verkaufsplattform zu schicken.
In drei Schritten, so beschreibt es die PayPal-Dokumentation. Erstens legt die Anwendung die Bestellung serverseitig an — über die Orders-Schnittstelle unter /v2/checkout/orders, mit der Absicht, den Betrag sofort einzuziehen oder ihn zunächst nur zu reservieren. Zweitens bestätigt der Käufer die Zahlung bei PayPal; die Bestellung wechselt dabei von CREATED auf APPROVED. Drittens schließt die Anwendung die Zahlung wieder serverseitig ab, über /v2/checkout/orders/{id}/capture, und die Bestellung erreicht COMPLETED. Authentifiziert wird mit Client-ID und Secret, die gegen ein OAuth-Token getauscht werden. Das Secret gehört dabei ausschließlich auf den Server: PayPal schreibt in der Dokumentation ausdrücklich, es sicher aufzubewahren, und die Beispiele legen es als Umgebungsvariable ab.
Beides ist möglich, und der Unterschied liegt weniger im Code als in Vertrag und Buchhaltung. Direkt heißt: eigener PayPal-Zugang, PayPals eigene Schnittstelle, Auszahlung und Streitfälle laufen bei PayPal. Über einen Zahlungsdienstleister heißt: PayPal ist eine Zahlungsart neben Karte und anderen Verfahren, angesprochen über eine Schnittstelle. Stripe dokumentiert PayPal als Zahlungsmethode für Konten in einer Reihe europäischer Länder, darunter Deutschland, und beschreibt daneben eine Variante mit dem eigenen PayPal-Konto. Praktisch bedeutet das: ein Vertrag, ein Dashboard, ein Auszahlungsrhythmus, eine Abstimmung in der Buchhaltung — gegenüber zwei getrennten Verträgen, zwei Auszahlungswegen und zwei Stellen, an denen Erstattungen und Streitfälle bearbeitet werden. Welcher Weg trägt, entscheidet siteway im Konzept.
Über die Sandbox. PayPal beschreibt sie als in sich geschlossene Testumgebung, die die Produktivumgebung nachbildet, ohne echte Konten zu berühren. Beim Anlegen des Entwicklerzugangs entstehen dort ein Geschäfts- und ein Privatkonto; weitere lassen sich im Developer-Dashboard ergänzen. Die Sandbox hat eigene Zugangsdaten und eine eigene Basis-Adresse unter api-m.sandbox.paypal.com. Wir fahren damit den kompletten Weg durch, bevor irgendetwas live geht: erfolgreiche Zahlung, abgebrochene Zahlung, abgelehnte Zahlung, Erstattung — und dazu die Webhooks, damit nicht nur der Kauf funktioniert, sondern auch das, was danach kommt.
Weil der Browser nicht die verlässliche Quelle ist. Der Käufer kann das Fenster schließen, die Verbindung kann abreißen, und ein Endpunkt, der einer Rückmeldung aus dem Browser blind glaubt, lässt sich manipulieren. PayPal beschreibt Webhooks als HTTPS-Aufrufe an eine Adresse auf dem eigenen Server, sobald ein Ereignis eintritt — dokumentiert sind unter anderem CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED und PAYMENT.CAPTURE.PENDING. Die Echtheit einer solchen Meldung wird geprüft, bevor irgendetwas verarbeitet wird; die Dokumentation nennt dafür zwei Wege, entweder eine Prüfsumme mit Signaturprüfung oder das Zurücksenden von Nachricht, Webhook-ID und Kopfzeilen an den Prüf-Endpunkt von PayPal.
Als Zustand, nicht als Ausnahme. Eine Bestellung endet nicht mit dem Kauf: Sie kann erstattet werden, teilweise erstattet werden, oder der Käufer eröffnet einen Streitfall. PayPal meldet diese Ereignisse ebenfalls per Webhook — dokumentiert sind unter anderem PAYMENT.CAPTURE.REFUNDED, PAYMENT.REFUND.PENDING, PAYMENT.REFUND.FAILED sowie CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED und CUSTOMER.DISPUTE.RESOLVED. Auf der Website wird daraus eine klare Regel: Der Bestellstatus ändert sich, ein freigeschalteter Download oder Zugang wird wieder entzogen, die Benachrichtigung geht raus, und im Backend sieht man, was passiert ist. Sonst zeigt die Seite eine bezahlte Bestellung, während das Geld längst zurück ist.
Der Bezahlbutton ist kein Bild, sondern Fremdcode: Das JavaScript-SDK wird von PayPal-Servern geladen, dabei entsteht eine Verbindung zu einem Dritten. Das gehört in die Consent-Betrachtung und in die Datenschutzerklärung, und technisch heißt es meist: Der Button wird dort geladen, wo bezahlt wird, und nicht auf jeder Seite der Website. Dazu kommen die üblichen Punkte einer Zahlungsanbindung — nur die Felder übertragen, die für die Zahlung nötig sind, Zugangsdaten serverseitig halten, Übertragung ausschließlich über TLS, und die vertraglichen Grundlagen für die Verarbeitung klären. Das ist eine Beschreibung der Technik und keine Rechtsberatung; die rechtliche Bewertung gehört zu deinem Datenschutzbeauftragten oder deiner Kanzlei. Wie siteway die technische Seite behandelt, steht im Stack unter Sicherheit und Datenschutz.
Ja, in allen dreien — und wir bauen die Anbindung jeweils selbst, mit den Bordmitteln des Systems. Die Kette ist überall dieselbe: Bezahlstrecke im Frontend, ein serverseitiger Endpunkt legt die Bestellung an und bestätigt sie, ein zweiter nimmt den Webhook entgegen. In TYPO3 entsteht dafür eine eigene Extension mit Controller-Routen für Anlegen, Bestätigen und Webhook, den Zugangsdaten in der Extension-Konfiguration oder einer Umgebungsvariablen und Fluid im Frontend. In WordPress entsteht ein eigenes Plugin statt Theme-Code, mit eigenen REST-Routen, den Zugangsdaten in der wp-config.php oder einer Umgebungsvariablen und Template beziehungsweise Blocks im Frontend. In Statamic liegt Laravel darunter: Route plus Controller, Zugangsdaten in der .env, Antlers oder Blade im Frontend. Der Zahlungsstatus wird in jedem der drei Systeme serverseitig entschieden, nie im Browser.
// womit das zusammenhängt
zahlarten, bausteine & leistung
// stack · schnittstelle
Der Zahlungsdienstleister, hinter dessen Schnittstelle mehrere Zahlarten liegen — PayPal für europäische Konten inklusive.
zur technik →
// stack · schnittstelle
Rechnung und Ratenkauf im Checkout: anderes Modell, dieselbe Frage nach Status, Rückkanal und sauberem Betrieb.
zur technik →
// stack · grundlage
Wo Zahlungen laufen, wird es ernst: Zugangsdaten serverseitig, TLS, Datensparsamkeit, Fremdcode bewusst eingebunden.
zur technik →
// leistung · baustein
Der Baustein, in dem die Zahlung steckt: Produktkatalog, Warenkorb und Kasse als Teil deiner Website.
zur leistung →
// leistung · baustein
Downloads, Zugänge und wiederkehrende Zahlungen — dort hängt die Freischaltung direkt am Zahlungsstatus.
zur leistung →
// leistung · buchen
Die Technik hier, das Angebot dort: Analyse, Umsetzung, Test in der Sandbox, Monitoring und Betrieb der Anbindung.
zur leistung →
// Zahlung per PayPal auf deiner Website?
Projekt anfragen