--- title: "Wir stellen vor: Tapaya Checkout" description: "Karten, Apple Pay und Google Pay über eine API. Leiten Sie Kunden auf eine gehostete Zahlungsseite weiter oder betten Sie sichere Kartenfelder in Ihren eigenen Checkout ein. So funktionieren beide Varianten und so wählen Sie die richtige." url: "https://tapaya.com/de/blog/introducing-tapaya-checkout-de" lang: "de" last_updated: "2026-11-13" --- # Wir stellen vor: Tapaya Checkout > Karten, Apple Pay und Google Pay über eine API. Leiten Sie Kunden auf eine gehostete Zahlungsseite weiter oder betten Sie sichere Kartenfelder in Ihren eigenen Checkout ein. So funktionieren beide Varianten und so wählen Sie die richtige. Mit Tapaya Checkout kommen Online-Zahlungen zu Tapaya. Ihre Händler können auf jeder Website Karten, Apple Pay und Google Pay akzeptieren, und Sie entscheiden, wie viel des Checkouts Sie selbst gestalten. - **Hosted Checkout.** Ihr Server erstellt eine Session und leitet den Kunden auf eine sichere Zahlungsseite weiter, die Tapaya hostet. Im Frontend ist dafür kaum Arbeit nötig. - **Embedded Checkout.** Sichere Kartenfelder und Wallet-Buttons sitzen direkt in Ihrer eigenen Checkout-Seite, neben Ihrem eigenen Bezahlen-Button. Beide nutzen dasselbe serverseitige Modell: erstellen, weiterleiten oder einbetten, und vor der Auftragsabwicklung auf Ihrem Server prüfen. Sie können noch heute in der Sandbox unter [docs.tapaya.com](https://docs.tapaya.com) starten. {% youtube #PejafWaMx24 title="Introducing Tapaya Checkout: New way to payments online" poster="/images/posts/introducing-tapaya-checkout-video-poster.jpg" /%} ## Was Tapaya Checkout ist Tapaya Checkout ist der Online-Teil von Tapaya. Es nimmt für Ihre Händler Zahlungen per Karte, Apple Pay und Google Pay entgegen, über eine API und ein Node.js SDK. Die Idee ist dieselbe wie bei Zahlungen vor Ort: Sie integrieren einmal, das Händlererlebnis bleibt in Ihrem Produkt, und Tapaya übernimmt die Komplexität der Zahlungen im Hintergrund. ![Tapaya Checkout auf einen Blick: Karten, Apple Pay und Google Pay, integriertes 3-D Secure, keine doppelten Zahlungen, automatische Wiederholungen, Kartendaten erreichen nie Ihre Seite, eine API und ein SDK für Hosted und Embedded Checkout](/images/posts/introducing-tapaya-checkout-at-a-glance.jpg) - **Hosted Checkout** bietet Ihnen eine fertige Zahlungsseite auf der Domain von Tapaya, für Desktop und Mobilgeräte. - **Embedded Checkout** bietet Ihnen sichere Felder, die Sie in Ihre eigene Seite einbinden. Kartendaten bleiben im Frame von Tapaya und erreichen Ihre Seite nie. Beide basieren auf denselben Bausteinen: ein serverseitiger Schlüssel, Beträge in der kleinsten Währungseinheit (`1880` bedeutet also 18,80 EUR), idempotente Anfragen und serverseitige Prüfung. Wer eine Variante gebaut hat, kennt den Großteil der anderen schon. ## Hosted oder Embedded: welche Variante passt ![Embedded Checkout hält Kunden auf Ihrer eigenen Checkout-Seite. Hosted Checkout schickt sie auf eine sichere, von Tapaya gehostete Seite.](/images/posts/introducing-tapaya-checkout-embedded-vs-hosted.jpg) {% table %} -   - Hosted Checkout - Embedded Checkout --- - **Wo der Kunde bezahlt** - Auf einer von Tapaya gehosteten Seite, danach zurück in Ihren Shop - Direkt auf Ihrer eigenen Checkout-Seite --- - **Aufwand im Frontend** - Eine Weiterleitung - Felder einbinden, `submit()` und Status behandeln --- - **Bezahlen-Button** - Auf der Seite von Tapaya - Ihr eigener Button --- - **Apple Pay und Google Pay** - Auf der gehosteten Seite - Im Frame von Tapaya neben den Kartenfeldern --- - **3-D Secure** - Auf der gehosteten Seite - Innerhalb von `submit()`, im Frame von Tapaya --- - **Am besten für** - Schnellen Go-live, einfache Shops, Plattformen mit vielen Händlern - Teams, die den Checkout vollständig selbst gestalten wollen {% /table %} Wenn Sie unsicher sind, beginnen Sie mit Hosted Checkout. Ein späterer Wechsel zu Embedded nutzt dieselben Schlüssel, dasselbe Bestellmodell und dieselbe Prüflogik. ## Hosted Checkout in fünf Schritten 1. **Session auf Ihrem Server erstellen.** Rufen Sie `POST /merchant/checkout-sessions` mit `merchantOrderId`, `amount` (in der kleinsten Einheit), `currency`, `customer`, `successUrl` und `cancelUrl` auf. Senden Sie einen `Idempotency-Key`-Header mit. 1. **Session-ID an der Bestellung speichern.** 1. **Browser weiterleiten** auf `session.url` mit HTTP 303. Verwenden Sie die URL genau so, wie sie zurückkommt. 1. **Der Kunde bezahlt auf der gehosteten Seite.** Eine abgelehnte Karte kann auf derselben Seite erneut versucht werden. Sessions nehmen 30 Minuten lang Zahlungen an. 1. **Auf Ihrem Server prüfen.** Wenn der Kunde auf eine der beiden Rücksprung-URLs zurückkehrt, rufen Sie `GET /merchant/checkout-sessions/{id}` auf. Prüfen Sie, ob ID, Bestell-ID, Betrag und Währung zu Ihrer Bestellung passen, und wickeln Sie nur ab, wenn `paymentStatus` den Wert `successful` hat. Mit dem Node.js SDK (`npm install @tapayadot/checkout`, Node.js 22.13.0 oder neuer) sieht der Kern so aus: ```typescript import { Tapaya } from '@tapayadot/checkout' // Reads TAPAYA_SECRET_KEY from the server environment. const tapaya = new Tapaya() // 1–3. Create the session and redirect the customer const session = await tapaya.checkout.sessions.create(params, { idempotencyKey }) return Response.redirect(session.url, 303) // 5. Later, on the return URL: verify before you fulfil const current = await tapaya.checkout.sessions.get(sessionId) ``` Alle Parameter finden Sie im Typ `CreateHostedCheckoutSessionParams` und im Hosted-Checkout-Leitfaden. ## Embedded Checkout: sichere Felder in Ihrer eigenen Seite Embedded Checkout teilt die Arbeit zwischen Ihrer Seite und einem kleinen `prepare`-Endpoint auf Ihrem Server auf. Im Browser laden Sie Tapaya aus `@tapayadot/checkout/client` und binden die Felder ein: ```typescript import { loadTapaya } from '@tapayadot/checkout/client' const tapaya = await loadTapaya(publishableKey, { apiOrigin }) const payment = tapaya.createPayment({ prepare: '/api/payments', // your server endpoint wallets: { amount: 1880, currency: 'EUR' }, onChange: (snapshot) => { /* enable Pay when snapshot.canSubmit */ }, }) payment.mount('#card-fields') // In your form handler: await payment.submit() // validates, runs 3-D Secure, confirms ``` Auf Ihrem Server lädt der `prepare`-Endpoint die Bestellung und verwendet eine bestehende Zahlung wieder, falls es eine gibt. Andernfalls erstellt er eine mit `POST /merchant/payments` und einem Idempotenzschlüssel. Anschließend gibt er `{ clientSecret, status }` zurück. React-Apps können `usePayment()` aus `@tapayadot/checkout/react` verwenden. Ein paar Dinge, die Sie wissen sollten: - Fügen Sie `https://js.tapaya.com` zu `script-src` und `frame-src` in Ihrer Content Security Policy hinzu. - Importieren Sie `@tapayadot/checkout` nur auf dem Server. Der Browser nutzt den Einstiegspunkt `/client`. - `snapshot.outcome` sagt Ihnen, was Sie anzeigen sollen: `open`, `pending`, `completed` oder `ended`. - Wallet-Buttons erscheinen nur dort, wo sie unterstützt und aktiviert sind. Apple Pay braucht eine aktive Shop-Domain, und Google Pay im Live-Betrieb braucht eine Merchant-ID. Den vollständigen Ablauf finden Sie im Embedded-Checkout-Leitfaden. ## Gebaut für zuverlässige Integrationen Zahlungen scheitern auf unschöne Weise: ein Timeout, ein Kunde, der den Tab schließt, eine Wiederholung, die doppelt ankommt. Tapaya Checkout ist so gebaut, dass Sie jeden dieser Fälle abfangen können. - **Idempotenzschlüssel bei jedem Erstellen.** Wiederholen Sie die Anfrage mit demselben Schlüssel und demselben Body, erhalten Sie die ursprüngliche Session oder Zahlung zurück. Ein geänderter Body liefert HTTP 409. - **Integrierte Wiederholungen im Node.js SDK.** Standardmäßig wiederholt es Anfragen zweimal bei Verbindungsfehlern, Timeouts und HTTP 429, 502, 503 und 504, mit zufällig gestreutem Backoff. - **Eine Zahlung pro Bestellung.** Eine neue Session für dieselbe Bestellung lässt die vorherige ablaufen. Eine bezahlte Bestellung oder eine mit laufender Zahlung wird abgelehnt. - **Webhooks plus Polling.** Abonnieren Sie Checkout-Session-Events und prüfen Sie offene Sessions zusätzlich weiter als Rückfallebene. - **Erst prüfen, dann abwickeln, und zwar einmal.** Ein Besuch Ihrer Erfolgs-URL beweist für sich allein nichts. Bestätigen Sie den Status immer auf Ihrem Server und erfassen Sie die Abwicklung atomar. Bevor Sie live gehen, spielen Sie jedes Ergebnis mit den Testkarten der Sandbox durch und arbeiten Sie die QA-Checkliste ab. ## Schneller bauen mit dem MCP-Server der Tapaya-Dokumentation Die Dokumentation von Tapaya hat einen eigenen MCP-Server. Ihre KI-Coding-Tools können damit während der Entwicklung die Leitfäden durchsuchen und API-Endpoints nachschlagen, ohne den Editor zu verlassen. Er funktioniert mit Claude Code, Claude Desktop, Cursor, VS Code, Codex und jedem anderen MCP-Client. Er ist öffentlich und braucht keinen API-Schlüssel. ```bash claude mcp add --transport http tapaya-docs https://docs.tapaya.com/mcp ``` Er ruft nie die Live-API von Tapaya auf und fragt nie nach Schlüsseln. Die Einrichtung für jeden Client steht unter [MCP Setup](https://docs.tapaya.com/mcp-server). ## Von der Sandbox in den Live-Betrieb 1. **Händler onboarden** mit der Funktion für Online-Zahlungen, und warten, bis er in der Tapaya Platform unter Checkout als Ready angezeigt wird. 1. **Shop hinzufügen** unter Allowed websites und Standard-URLs für Erfolg und Abbruch festlegen. 1. **In der Sandbox entwickeln** mit einem `tapaya_test_`-Schlüssel, der nur auf Ihrem Server liegt. 1. **Auf Produktion umstellen:** ein Produktionsschlüssel, `TAPAYA_ENVIRONMENT=production` und Rücksprung-URLs für die Produktion. 1. **Wallets für den Live-Betrieb einrichten:** die Shop-Domain für Apple Pay und die Merchant-ID für Google Pay. Der Quick-Start-Leitfaden bringt Sie mit wenigen Serveraufrufen von null zur ersten Sandbox-Zahlung. ## Häufige Fragen ### Welche Zahlungsmethoden unterstützt Tapaya Checkout? Karten, Apple Pay und Google Pay, sowohl in Hosted als auch in Embedded Checkout. ### Laufen Kartendaten über meinen Server oder meine Seite? Nein. Bei Hosted Checkout bezahlt der Kunde auf der Seite von Tapaya. Bei Embedded Checkout laufen die Kartenfelder und 3-D Secure im Frame von Tapaya, und Kartendaten erreichen Ihre Seite nie. ### Wie lange ist eine Hosted-Checkout-Session gültig? 30 Minuten ab Erstellung. Eine Zahlung, die vorher abgeschickt wurde, wird noch abgeschlossen. Ist die Bestellung danach weiterhin unbezahlt, erstellen Sie eine neue Session. ### Gibt es ein SDK? Ja, `@tapayadot/checkout` für Node.js 22.13.0 oder neuer. Es deckt Hosted Checkout auf dem Server ab, dazu Einstiegspunkte für Browser und React für Embedded Checkout. Andere Stacks können die REST-API direkt aufrufen. ### Können Plattformen Zahlungen für viele Händler annehmen? Ja. Verwenden Sie den Secret Key der Organisation und senden Sie mit jeder Anfrage ein Händler-Token. ## Jetzt starten Lesen Sie die Übersicht zu Online Payments unter [docs.tapaya.com](https://docs.tapaya.com), erstellen Sie einen Sandbox-Schlüssel und nehmen Sie noch heute Ihre erste Testzahlung entgegen. Fragen zu Ihrer Integration? Schreiben Sie an [developers@tapaya.com](mailto:developers@tapaya.com). ## Sitemap - [Sitemap](https://tapaya.com/sitemap.md): every page on tapaya.com, as markdown links