Wir stellen vor: Tapaya Checkout

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 starten.

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.

• 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

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.
2. Session-ID an der Bestellung speichern.
3. Browser weiterleiten auf session.url mit HTTP 303. Verwenden Sie die URL genau so, wie sie zurückkommt.
4. Der Kunde bezahlt auf der gehosteten Seite. Eine abgelehnte Karte kann auf derselben Seite erneut versucht werden. Sessions nehmen 30 Minuten lang Zahlungen an.
5. 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:

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:

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.

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.

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.
2. Shop hinzufügen unter Allowed websites und Standard-URLs für Erfolg und Abbruch festlegen.
3. In der Sandbox entwickeln mit einem tapaya_test_-Schlüssel, der nur auf Ihrem Server liegt.
4. Auf Produktion umstellen: ein Produktionsschlüssel, TAPAYA_ENVIRONMENT=production und Rücksprung-URLs für die Produktion.
5. 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, 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.