Back to guides INTEGRATIONS

Payment-Gateway-Integration: Vollstaendiger Leitfaden fuer Entwickler und Unternehmen

Die Integration eines Payment-Gateways ist eine der bedeutendsten technischen Entscheidungen, die ein E-Commerce-Unternehmen oder ein Software-Team trifft. Die gewahlte Methode bestimmt den PCI-DSS-Umfang, die Checkout-Konversionsrate, die Faehigkeit zur 3D-Secure-Authentifizierung und die Geschwindigkeit, mit der neue Zahlungsmethoden unterstuetzt werden koennen. Dieser Leitfaden deckt alle verfuegbaren Integrationswege ab, von einer codefreien Hosted Page bis hin zu einer vollstaendigen Server-to-Server-REST-API, und fuehrt durch die genauen Schritte, die fuer den Go-Live mit RoxPay erforderlich sind.

Was Payment-Gateway-Integration fuer Ihr Unternehmen bedeutet

Eine Payment-Gateway-Integration ist die technische Verbindung zwischen Ihrer Website oder Anwendung und dem Zahlungsabwicklungsnetzwerk, das Kartentransaktionen autorisiert, erfasst und abrechnet. Ohne sie koennen Ihre Kunden nicht bezahlen. Mit einer schlechten Integration verlieren Sie Umsatz durch fehlgeschlagene Transaktionen, reibungsintensive Checkout-Ablaeufe und mangelhaftes Mobilgeraete-Erlebnis.

Die Integration betrifft mehr als nur Entwickler. Unternehmer muessen verstehen, dass die gewahlte Methode ihre Haftung gemaess PCI DSS, ihre Faehigkeit zur Unterstuetzung lokaler Zahlungsmethoden und die Geschwindigkeit bestimmt, mit der neue Funktionen wie Apple Pay oder Open-Banking-Ueberweisungen aktiviert werden koennen. Eine Hosted-Page-Integration verlagert die gesamte Kartenverarbeitung von Ihren Servern weg und minimiert Ihren Compliance-Aufwand. Eine direkte API-Integration bietet maximale Kontrolle, stellt aber die Kartenverarbeitung auf Ihre Infrastruktur und erfordert ein hoeheres PCI-Zertifizierungsniveau.

Warum die Integrations-Qualitaet die Konversion beeinflusst: Checkout-Reibung ist eine der Hauptursachen fuer Warenkorbabbrueche. Ein Gateway, das mehrere Weiterleitungen und den Besuch eines separaten Bankportals erfordert, konvertiert schlechter als ein natives, eingebettetes Checkout-Erlebnis. Moderne REST-API-Integrationen ermoeglichten es, Karteneingabefelder direkt auf Ihrer Checkout-Seite anzuzeigen, ohne dass der Kunde Ihre Website verlassen muss, was die Abschlussrate messbar verbessert.

Fuer Haendler in Hochrisiko-Branchen, die auch ein High-Risk-Payment-Gateway benoetigen, ist die Integrationsschicht noch wichtiger, da zusaetzliche Pruefungen, 3D-Secure-Durchsetzung und Betrugsfilter alle damit interagieren, wie das Zahlungsformular aufgebaut ist und wie Ereignisse nachgelagert behandelt werden.

Integrationsmethoden: Hosted Page vs. API vs. SDK

Es gibt drei primaere Moeglichkeiten, ein Payment-Gateway zu integrieren, jede mit unterschiedlichen Abwaegungen zwischen Implementierungsgeschwindigkeit, PCI-DSS-Umfang und Anpassungsflexibilitaet.

Hosted Payment Page: Die einfachste Option. Sie leiten den Kunden von Ihrem Checkout zu einer Seite weiter, die vom Payment-Gateway gehostet und verwaltet wird. Der Kunde gibt Kartendaten auf der Domain des Gateways ein, nicht auf Ihrer. Dadurch entfallen fast alle PCI-DSS-Anforderungen auf Ihrer Seite, da Sie niemals Kartendaten verarbeiten. Der Nachteil ist begrenzte Anpassbarkeit und das Verlassen Ihrer Website mitten im Checkout. Am besten fuer Unternehmen, die schnell mit minimalem Entwicklungsaufwand mit der Zahlungsannahme beginnen moechten.

Eingebettetes Drop-in-UI (iFrame oder JS-Elemente): Ein praktischer Mittelweg. Das Gateway stellt ein JavaScript-Snippet bereit, das sichere Karteneingabefelder direkt in Ihre Checkout-Seite injiziert. Die Felder werden in iFrames auf der Domain des Gateways gerendert, sodass Kartendaten Ihren Server nie beruehren. Aus Kundensicht sieht der Checkout nativ fuer Ihre Website aus. PCI-Umfang ist minimal (SAQ A). Dies ist der empfohlene Ansatz fuer die meisten E-Commerce-Unternehmen. RoxPay unterstuetzt dies ueber seine REST-API und das Frontend-SDK.

Server-to-Server-API: Maximale Kontrolle. Ihr Frontend erfasst Kartendaten, Ihr Server sendet sie direkt an die Gateway-API. Dies erfordert PCI-DSS-SAQ-D-Konformitaet, die strenge Sicherheitspruefungen und laufende Kontrollen umfasst. Geeignet fuer Plattformen, die Zahlungsinfrastruktur-Produkte aufbauen, nicht fuer die meisten Haendler, die ihre eigenen Transaktionen verarbeiten.

Plattform-Plugins und -Module: Fuer Haendler, die E-Commerce-Plattformen wie Magento, PrestaShop oder WooCommerce verwenden, behandeln vorgefertigte Module die Integrationsdetails innerhalb der Plattformarchitektur. Die zugrundeliegende Methode ist in der Regel eine Hosted Page oder ein Drop-in-UI, sodass der PCI-Umfang minimal bleibt und die Implementierungszeit in Stunden statt Tagen gemessen wird.

Schritt fuer Schritt: RoxPay per REST API integrieren

RoxPay stellt eine REST-API mit JSON-Anfrage- und Antwortkoerper bereit. Die vollstaendige Dokumentation ist unter app.roxpay.eu/api/v4/docs verfuegbar. Die Integration folgt einem Standard-Payment-Intent-Muster, das jedem Entwickler, der mit modernen Gateway-APIs gearbeitet hat, vertraut ist.

Schritt 1: Sandbox-Konto erstellen. Um Ihren RoxPay-Antrag zu starten, navigieren Sie zur Onboarding-Seite. Sandbox-Zugangsdaten werden automatisch bei der Registrierung ausgegeben, ohne dass Zahlungsinformationen zum Starten von Tests erforderlich sind.

Schritt 2: Authentifizieren. Alle API-Aufrufe verwenden Ihren API-Schluessel im Authorization-Header. Schluessel sind auf Ihr Haendlerkonto beschraenkt und koennen ueber das Dashboard rotiert werden. Exponieren Sie Ihren API-Schluessel niemals in clientseitigem JavaScript oder committen Sie ihn in die Versionskontrolle.

Schritt 3: Payment Intent erstellen. POST an den Payment-Intent-Endpunkt mit dem Betrag, der Waehrung, akzeptierten Zahlungsmethoden und einer eindeutigen Bestellreferenz aus Ihrem System. Die API gibt eine Payment-Intent-ID und ein Client-Secret zur Verwendung im Frontend zurueck.

Schritt 4: Drop-in-UI einbinden. Uebergeben Sie das Client-Secret an die RoxPay.js-Bibliothek, die Karteneingabefelder auf Ihrer Seite rendert. Die Bibliothek behandelt Kartennummernformatierung, Validierung, 3D-Secure-Weiterleitungen sowie Apple Pay oder Google Pay Schaltflaechen basierend auf der Browser-Unterstuetzung.

Schritt 5: Ergebnis verarbeiten. Bei erfolgreicher Zahlung loest die Bibliothek einen Erfolgs-Callback aus. Ihr Frontend benachrichtigt Ihr Backend, das den Zahlungsstatus unabhaengig per Webhook verifiziert, bevor die Bestellung ausgefuehrt wird. Verlassen Sie sich niemals ausschliesslich auf die Frontend-Bestaetigung fuer die Bestellabwicklung.

Schritt 6: Abgleich ueber das Dashboard. Alle Transaktionen sind in Ihrem Haendler-Dashboard mit vollstaendigen Details zu Betrag, Gebuehren, Kartentyp und Abrechnungsstatus sichtbar. Exportieren Sie als CSV oder verwenden Sie die API fuer die Integration in Buchhaltungssysteme.

Webhooks, Fehlerbehandlung und Tests in der Sandbox

Webhooks sind das Rueckgrat einer zuverlaessigen Zahlungsintegration. Sie ermoeglichten es RoxPay, Ihren Server asynchron ueber Zahlungsereignisse zu benachrichtigen, ohne darauf angewiesen zu sein, dass der Browser des Kunden offen bleibt oder die Netzwerkverbindung waehrend der gesamten Transaktion stabil bleibt.

Webhooks einrichten: Registrieren Sie einen HTTPS-Endpunkt auf Ihrem Server im Dashboard. RoxPay sendet einen signierten JSON-Payload an diesen Endpunkt fuer jedes wesentliche Ereignis: payment.completed, payment.failed, payment.refunded, chargeback.created und andere. Verifizieren Sie die Signatur bei jedem eingehenden Webhook mit dem in Ihrem Dashboard angezeigten Secret-Key. Lehnen Sie jede Anfrage ab, die die Signaturvalidierung nicht besteht, um Replay-Angriffe zu verhindern.

Idempotenz: Webhooks koennen aufgrund von Netzwerkbedingungen mehr als einmal zugestellt werden. Ihr Endpunkt muss jedes Ereignis idempotent verarbeiten, d.h. die zweifache Verarbeitung desselben Ereignisses fuehrt zum gleichen Ergebnis. Speichern Sie die Ereignis-ID und ueberspringen Sie die Verarbeitung, wenn Sie sie bereits behandelt haben.

Fehlerbehandlung in der API: RoxPay gibt Standard-HTTP-Statuscodes zurueck. 200 fuer Erfolg, 400 fuer fehlerhafte Anfragen mit ungueltigen Parametern, 401 fuer Authentifizierungsfehler, 422 fuer Verarbeitungsfehler wie eine Kartenabweisung oder unzureichende Deckung. Untersuchen Sie immer den Fehlercode im Antwortkoerper, nicht nur den HTTP-Status, um zwischen einem technischen Fehler und einer Geschaeftslogikabweisung zu unterscheiden.

Sandbox-Tests: Die Sandbox-Umgebung spiegelt die Produktion genau wider. Verwenden Sie die bereitgestellten Test-Kartennummern, um genehmigten Transaktionen, Ablehnungen, 3DS-Herausforderungen, unzureichende Deckung, abgelaufene Karten und gestohlene Kartenantworten zu simulieren. Testen Sie Ihre Webhook-Behandlung, indem Sie jeden Ereignistyp in der Sandbox ausloesen, bevor Sie die Produktion beruehren.

Wiederholungslogik: Implementieren Sie exponentielles Backoff in Ihrem Webhook-Consumer. RoxPay wiederholt nicht zugestellte Webhooks ueber einen definierten Zeitraum. Ihr Endpunkt muss idempotent sein, bevor Sie sich auf das Wiederholungsverhalten verlassen.

Go-Live: Checkliste vor der Verarbeitung echter Transaktionen

Der Wechsel von der Sandbox zur Produktion erfordert die Durchfuehrung einer Reihe technischer, sicherheitsrelevanter und kommerzieller Schritte. Das Ueberspringen eines davon schafft Risiken fuer Ihr Unternehmen und Ihre Kunden.

Technische Checkliste:
Ersetzen Sie Sandbox-API-Schluessel durch Produktionsschluessel und speichern Sie sie in Umgebungsvariablen, niemals im Quellcode oder in der Versionskontrolle. Bestaetigen Sie, dass Ihr Webhook-Endpunkt aktiv, ueber HTTPS mit einem gueltigen Zertifikat erreichbar ist und konsistent 200-Antworten zurueckgibt. Testen Sie die Idempotenz-Behandlung mit Produktionszugangsdaten, bevor Sie den Kundenverkehr umschalten. Bestaetigen Sie, dass 3D Secure gemaess den Anforderungen Ihres Acquirers fuer Ihre Haendlerkategorie konfiguriert ist. Validieren Sie, dass Ihre Checkout-UI auf Mobilgeraeten korrekt gerendert wird, insbesondere fuer Apple-Pay- und Google-Pay-Schaltflaechen.

PCI-DSS-Checkliste:
Wenn Sie das Drop-in-UI verwenden, fuellen Sie einen SAQ-A-Selbstbewertungsfragebogen aus und reichen Sie ihn ein. Bestaetigen Sie, dass Sie nirgendwo in Ihrem System rohe Kartendaten protokollieren oder speichern, einschliesslich Anfrage-Logs, Fehler-Logs oder Analyse-Pipelines. Stellen Sie sicher, dass Ihre TLS-Konfiguration aktuellen Standards entspricht (mindestens TLS 1.2, bevorzugt TLS 1.3). Entfernen Sie alle alten Zahlungsintegrationen, die moeglicherweise noch in Ihrer Codebasis aktiv sind.

Geschaftliche Checkliste:
Legen Sie Ihren Abrechnungsdeskriptor im Dashboard fest. Dieser Text erscheint auf dem Kontoauszug des Karteninhabers. Ein klarer, erkennbarer Deskriptor reduziert Friendly-Fraud-Chargebacks erheblich, da Kunden die Transaktion erkennen koennen. Konfigurieren Sie Ihre Settlement-IBAN. RoxPay rechnet auf jedes SEPA-Bankkonto in 24-48 Stunden ab. Aktivieren Sie E-Mail-Benachrichtigungen fuer fehlgeschlagene Transaktionen und Chargebacks, damit Sie innerhalb der Widerspruchsfristen reagieren koennen.

Frequently Asked Questions

Wie lange dauert eine Payment-Gateway-Integration?

Mit dem Drop-in-UI-Ansatz von RoxPay und der REST-API kann ein erfahrener Entwickler eine produktionsreife Integration in ein bis zwei Tagen abschliessen. Eine Hosted-Page-Weiterleitung dauert weniger als einen Tag. Die vollstaendige Server-to-Server-API-Integration mit einem benutzerdefinierten Checkout-UI dauert in der Regel ein bis zwei Wochen und erfordert neben dem Entwicklungsaufwand auch eine hoehere PCI-DSS-Konformitaetsarbeit.

Muss ich PCI DSS zertifiziert sein, um ein Payment-Gateway zu integrieren?

Nicht zertifiziert im formalen Sinne, aber Sie muessen konform sein. Wenn Sie eine Hosted Page oder ein Drop-in-UI (iFrame-basiert) verwenden, ist Ihr Compliance-Aufwand minimal und Sie fuellen einen einfachen Selbstbewertungsfragebogen (SAQ A) aus. Wenn Sie rohe Kartendaten auf Ihren eigenen Servern ueber eine Server-to-Server-API verarbeiten, benoetigen Sie SAQ D, das eine strenge Pruefung umfasst.

Was ist ein Payment Intent und warum wird er verwendet?

Ein Payment Intent ist ein serverseitiges Objekt, das die Kaufabsicht eines Kunden fuer einen bestimmten Betrag repraesentiert. Er verfolgt den Zahlungsstatus durch Autorisierung, 3D-Secure-Challenge, Erfassung und Abrechnung. Die Verwendung eines Payment-Intent-Modells verhindert doppelte Abbuchungen, ermoeglicht zuverlaessiges Webhook-Tracking und erlaubt es der Zahlung, Browser-Aktualisierungen oder unterbrochene Verbindungen waehrend des Checkouts zu ueberstehen.

Kann ich die Integration ohne ein Live-Haendlerkonto testen?

Ja. RoxPay bietet eine kostenlose Sandbox-Umgebung, die unmittelbar nach der Registrierung zugaenglich ist. Die Sandbox spiegelt das Produktionsverhalten genau wider und enthaelt Testkarten fuer jedes Szenario: Genehmigungen, Ablehnungen, 3DS-Challenges, abgelaufene Karten und unzureichende Deckung. Fuer den Beginn von Tests sind keine Zahlungsinformationen oder Genehmigung eines Live-Kontos erforderlich.

Mehr erfahren

Optimize your payments today

RoxPay bietet eine REST-API mit kostenlosem Sandbox-Zugang, vollstaendiger Dokumentation und Settlement in 24-48 Stunden auf jede SEPA-Bank. PCI DSS Level 1 zertifiziert, IC++ Preise ab 0,45 Prozent.

Get started for free → Talk to an expert

✓ No monthly fixed costs · ✓ Activation in 24 hours · ✓ Dedicated technical support