Lightbox

Durch die Lightbox-Integration wird das PostFinance Checkout-Zahlungsformular als Overlay auf Ihrer Checkout-Seite geöffnet. Die Kunden bleiben ohne vollständige Weiterleitung auf Ihrer Website, während das Zahlungsformular selbst von PostFinance Checkout bereitgestellt wird – wodurch die Integration PCI DSS-konform bleibt.

Genau wie unsere anderen Checkout-Integrationen – Zahlungsseite und iFrame – minimiert sie Ihren PCI-Geltungsbereich. Die Lightbox ist einfacher zu implementieren als die iFrame-Integration und bietet dennoch ein nahtloses Zahlungserlebnis.

So funktioniert es

1. Erstellen Sie eine Transaktion über die Transaction Service API mit so vielen Kunden- und Produktdaten wie möglich – je vollständiger die Daten sind, desto besser funktionieren die Validierung und die Auswahl der Zahlungsmethoden.

2. Rufen Sie die verfügbaren Zahlungsmethoden im Integrationsmodus lightbox ab. Dadurch werden die für die Transaktion geeigneten Optionen zurückgegeben.

3. Laden Sie das JavaScript – rufen Sie die URL des Lightbox-Skripts über buildJavaScriptUrl ab und binden Sie es mit einem <script>-Tag in Ihre Seite ein. Die URL ist transaktionsspezifisch.

4. Öffnen Sie die Lightbox, wenn der Kunde zur Zahlung übergeht:

   LightboxCheckoutHandler.startPayment(paymentMethodId, errorCallback)

   Beide Parameter sind optional: Geben Sie eine Konfigurations-ID für eine Zahlungsmethode an, um eine Methode vorab auszuwählen, oder lassen Sie diese weg, damit der Kunde im Overlay selbst eine Auswahl treffen kann. errorCallback wird aufgerufen, wenn die Initialisierung der Lightbox fehlschlägt – nutzen Sie dies, um eine Ausweichlösung anzuzeigen, beispielsweise eine Weiterleitung zur Zahlungsseite.

5. Ergebnis verarbeiten – Nach der Zahlung wird der Kunde zu successUrl oder failedUrl weitergeleitet, die in der Transaktion definiert sind.

6. Richten Sie einen Webhook-Listener ein, um den Bestellstatus zuverlässig zu aktualisieren, selbst wenn der Kunde die Lightbox vorzeitig schließt.

Unter Transaktionszustände erfahren Sie, was die einzelnen Transaktionszustände bedeuten und wie Sie damit umgehen sollten.

warnung

Wenn Ihre Website eine Content Security Policy verwendet, muss diese unseren Plattform-Host in den Anweisungen script-src, frame-src und connect-src zulassen und die Ausführung von Inline-Skripten erlauben – andernfalls kann die Lightbox nicht geöffnet werden.

Vorteile und zu beachtende Punkte

Vorteile:

• Die integrierte Lightbox sorgt für einen reibungslosen Bezahlvorgang unter Einhaltung der PCI-Vorschriften – siehe PCI DSS.
• Einfacher zu implementieren als die iFrame-Integration – ideal, wenn Sie Overlay-Zahlungen ohne großen Programmieraufwand nutzen möchten.
• Sie behalten die volle Kontrolle über die ursprüngliche Bestellübermittlung und rufen das Overlay nur für die Zahlungsdetails auf.

Zu beachtende Punkte:

• Behandeln Sie den Fall, in dem sich die Lightbox nicht öffnen lässt, mithilfe des Fehler-Callbacks.
• Nutzen Sie Webhooks, um den endgültigen Transaktionsstatus zu erfassen, insbesondere wenn der Kunde die Seite vor der Weiterleitung verlässt.
• Die Filterung und Validierung von Zahlungsmethoden wird durch das Vorladen der Transaktion mit Daten unterstützt.

Checkliste

• Erstellen Sie ein PostFinance Checkout-Konto und einen Anwendungsbenutzer und konfigurieren Sie den API-Zugriff
• Erstellen Sie eine ausstehende Transaktion mit den verfügbaren Kundendaten
• Rufen Sie die Zahlungsmethoden im Integrationsmodus lightbox ab
• Binden Sie das Skript von buildJavaScriptUrl ein
• LightboxCheckoutHandler.startPayment(...) aufrufen, wenn der Kunde zur Zahlung übergeht
• Den Fehler-Callback als Fallback implementieren
• Die Weiterleitungen successUrl / failedUrl verarbeiten
• Unseren Host in Ihrer Content Security Policy zulassen
• Richten Sie einen Webhook-Listener für Aktualisierungen des Transaktionsstatus ein