Einführung in Hosted Checkouts und Checkout SDK

Wenn du Zahlungen in deine Anwendung integrierst, gibt es grundsätzlich zwei zentrale Ansätze:

Hosted Checkout (Redirect) – schnell, minimaler Aufwand
Embedded Checkout (iFrame) – flexibel, vollständig in deine Seite integriert

Beide Varianten basieren auf dem Checkout SDK und werden von COPE vollständig gehostet. Der Unterschied liegt darin, wo der Nutzer die Zahlung abschließt.

📄 Die vollständige Dokumentation findest du hier:
[Checkout SDK overview - COPE] | [Embedded hosted checkout - COPE]

Das Checkout SDK - die gemeinsame Basis

Beide Varianten verwenden das COPE Checkout SDK. Es übernimmt Produktdaten, Cart-Verwaltung, Preisberechnung und die Erstellung der Checkout Session.

Installation:

npm install @copecart/sdk

import { CopeCart } from "@copecart/sdk"  const cope = new CopeCart({   publishableKey: "cope_pk_live_...", })

Der typische Flow ist immer gleich:

Produkt abrufen
Cart erstellen und Produkt hinzufügen
Buyer Identity setzen (E-Mail, Steuerstandort)
Preise neu berechnen (reprice)
Checkout Session erstellen
Nutzer zur Zahlung weiterleiten – per Redirect oder iFrame

Hosted Checkout (Redirect) - schnellster Weg zur Zahlungsabwicklung

Ideal wenn du schnell live gehen willst, ohne in das Checkout-Erlebnis eingreifen zu müssen. Beim Hosted Checkout wird der Nutzer auf eine von COPE gehostete Checkout-Seite weitergeleitet. Deine Anwendung erstellt die Session, COPE übernimmt den Rest.

Ablauf:
Dein System → Checkout-URL → COPE Checkout Seite → Ergebnis → Dein System (via Redirect / Webhook)

Typische Anwendungsfälle:

Schneller Go-Live von Payments
Einfache Produkte oder Services
Zahlungslinks (z. B. E-Mail, WhatsApp, CRM)
Systeme ohne eigene Checkout-UI

Integration:

const checkout = await cope.checkout(cart.id, {   success_url: "https://your-site.example/thank-you",   cancel_url: "https://your-site.example/cart",   consents: [{ type: "buyer_tos" }], })  cope.redirectToCheckout(checkout)

Nach erfolgreicher Zahlung leitet COPE zur success_url weiter – mit angehängter order_id:

https://your-site.example/thank-you?order_id=ord_...

Vorteile:

Sehr geringe Implementierungszeit
Kein Frontend-Development nötig
PCI-reduzierte Komplexität
Stabiler, vollständig verwalteter Payment Flow

Embedded Checkout (iFrame) - Zahlung direkt in deiner Seite

Die richtige Wahl, wenn du deine Produkte vollständig im eigenen Branding präsentieren und den Nutzer nie von deiner Seite verlieren möchtest. Mit Embedded Checkout bleibt der Nutzer auf deiner Seite – COPE rendert das Zahlungsformular in einem iFrame innerhalb deines Layouts.

Ablauf:
Deine Anwendung → Checkout SDK → COPE iFrame (in deiner Seite eingebettet)

Voraussetzungen:

Publishable Key für das COPE Business erstellen
Jede Parent-Page-Origin registrieren, die den iFrame hosten soll (z. B. https://shop.example.com)
Nur HTTPS in Produktion (http://localhost nur für Entwicklung)

Integration:

const checkout = await cope.checkout(cart.id, {   embed_origin: window.location.origin,   success_url: "https://shop.example.com/thank-you",   cancel_url: "https://shop.example.com/cart",   consents: [{ type: "buyer_tos" }], })  cope.mountCheckout("#cope-checkout-frame", checkout, {   fallback: "redirect",   onReady: () => showCheckoutFrame(),   onSuccess: () => showOrderConfirmation(),   onCancel: () => closeCheckoutFrame(),   onError: ({ code, retryable }) => reportCheckoutError(code, retryable), })

Wichtige technische Hinweise:

Der iFrame wird vom SDK automatisch erstellt – nicht manuell bauen
embed_origin muss exakt mit dem Browser-Origin der Seite übereinstimmen
https://shop.example.com und https://www.shop.example.com gelten als unterschiedliche Origins
Fallback auf Redirect empfehlenswert (fallback: "redirect") für den Fall, dass der iFrame nicht lädt

Event-basierte Steuerung – Embedded Checkout kommuniziert über Events:

onReady – iFrame geladen und bereit
onSuccess – Zahlung erfolgreich abgeschlossen
onCancel – Nutzer hat abgebrochen
onError – Fehler im Zahlungsprozess (inkl. retryable-Flag)
onResize – iFrame-Höhe hat sich geändert

Vorteile:

Nutzer verlässt deine Seite nicht
Höhere Conversion durch weniger Reibung
Volle Kontrolle über das umgebende Layout und Branding
Wallet-Support (Apple Pay, Google Pay) abhängig vom Setup

Hosted vs. Embedded Checkout - wann nutzt du was?

Ziel	Lösung
Schnell Zahlungen akzeptieren	Hosted Checkout (Redirect)
Kein eigenes UI bauen	Hosted Checkout (Redirect)
Minimale technische Komplexität	Hosted Checkout (Redirect)
Nutzer auf der eigenen Seite halten	Embedded Checkout (iFrame)
Checkout direkt in App integrieren	Embedded Checkout (iFrame)
High-Conversion Checkout Flow	Embedded Checkout (iFrame)

Wichtige Grundlagen für beide Varianten

Sichere serverseitige Session-Erstellung
Webhooks zur finalen Zahlungsvalidierung
Idempotenz (keine doppelten Payments)
Fehler- und Retry-Handling
Monitoring & Logging
HTTPS als Pflicht

Verwandte Artikel