API-Integration

Ihr Backend erstellt für jede Bestellung eine Checkout-Session und ruft sie ab, um die Zahlung zu verifizieren.

Für Node.js bietet das SDK @tapayadot/checkout typisierte Methoden create() und get() für diese Endpoints. Es liest standardmäßig TAPAYA_SECRET_KEY. Die HTTP-Beispiele auf dieser Seite übergeben TAPAYA_CHECKOUT_API_KEY explizit.

Authentifizierung

Jeder Checkout-Aufruf erfolgt von Server zu Server und sendet einen Schlüssel als Bearer-Token:

Authorization: Bearer <key>

Wählen Sie den Modus, der dazu passt, wer das Backend betreibt. Bewahren Sie jeden der beiden Schlüssel auf Ihrem Server auf; siehe Checkout-Sicherheit.

Händlermodus

Verwenden Sie diesen Modus, wenn das Backend einen einzigen Shop bedient. Erstellen Sie einen Checkout-Händlerschlüssel in den Checkout-Einstellungen: Öffnen Sie den Händler und wählen Sie Create merchant key. Der Schlüssel beginnt in der Sandbox mit tapaya_test_ bzw. in der Produktion mit tapaya_live_ und verweist genau auf diesen Händler.

Authorization: Bearer <merchant-checkout-key>

X-Tapaya-Merchant-Token ist in diesem Modus optional. Wenn Sie ihn senden, muss er denselben Händler bezeichnen.

Die Platform zeigt den Schlüssel einmal an und speichert nur einen Hash. Um ihn zu rotieren, erstellen Sie einen Ersatz, bevor Sie den alten Schlüssel widerrufen. Das Widerrufen eines Schlüssels wirkt sich nicht auf andere Händlerschlüssel, Schlüssel der Organisation oder bereits an Browser ausgegebene client secrets aus.

Plattformmodus

Verwenden Sie diesen Modus, wenn ein Backend für viele Händler handelt, etwa ein Marktplatz oder eine Plattform für Essenslieferungen. Senden Sie bei jeder Anfrage den Secret key der Organisation von der Seite API Keys und das Token des Händlers:

Authorization: Bearer <secret-key>
X-Tapaya-Merchant-Token: <merchant-token>

Es gibt keinen Standardhändler. Eine Anfrage ohne den Header gibt HTTP 401 zurück. Der Händler muss zur Organisation des Schlüssels gehören. Kopieren Sie Händler-Tokens aus der Händlertabelle in den Checkout-Einstellungen. Das Token identifiziert den Händler; es ist kein Geheimnis.

Der Secret key der Organisation ist dieselbe Zugangsberechtigung, die in der Dokumentation der Platform API Server Secret Token heißt. Checkout erfordert das Präfix Bearer. Andere Endpoints der Platform API nehmen das Token direkt entgegen. Händler-Onboarding und Verwaltung der Organisation verwenden die Platform API.

Request-Bodys akzeptieren keine merchantId.

Umgebungen

Setzen Sie TAPAYA_CHECKOUT_API_URL auf den API-Origin Ihrer Umgebung. Sowohl gehostete als auch eingebettete Zahlungen sind in der Produktion verfügbar. Jeder Händler muss das Onboarding abschließen, die Freigabe des Zahlungsabwicklers für Online-Zahlungen erhalten und ein konfiguriertes Payment-Gateway haben. Prüfen Sie die Bereitschaft der Händler in den Checkout-Einstellungen. Verwenden Sie die zurückgegebene URL der gehosteten Session unverändert.

Checkout-Sessions

curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \
-H 'Idempotency-Key: order-1001-checkout-1' \
-d '{
        "merchantOrderId": "order-1001",
        "amount": 12100,
        "currency": "EUR",
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

{
    "id": "cs_7Hq2x9LmR4",
    "merchantOrderId": "order-1001",
    "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4",
    "status": "open",
    "paymentStatus": "unpaid",
    "amount": 12100,
    "currency": "EUR",
    "tax": 2100,
    "shipping": 605,
    "taxRate": 21,
    "taxBreakdown": [],
    "items": [],
    "expiresAt": "2026-07-15T12:30:00Z",
    "createdAt": "2026-07-15T12:00:00Z"
}

curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"

Zuständigkeit für Bestellung und Zahlung

Eine Checkout-Session-ID identifiziert einen Hosted Checkout. Ihre merchantOrderId verknüpft sie mit Ihrer Bestellung, während paymentReference den letzten Bestätigungsversuch identifiziert. Speichern Sie die Session-ID mit der Bestellung, damit Sie das Ergebnis auch dann abrufen können, wenn der Kunde den Browser schließt.

Die gehostete Seite verwendet separate öffentliche Endpoints, um die Session zu laden und zu bestätigen. Ihre Session-ID ist eine Zugangsberechtigung für diese Endpoints. Eine Händlerintegration verifiziert die Zahlung über den authentifizierten Händler-Endpoint.

Eine Zahlung pro Bestellung

Hosted Checkout und Embedded Checkout teilen sich eine Payment-Engine. Ein Händler kann höchstens eine erfolgreiche Zahlung pro merchantOrderId haben. Bestell-IDs gelten pro Händler, sodass verschiedene Händler, auch innerhalb einer Organisation, dieselben IDs verwenden können.

• Das Erstellen einer Session für eine unbezahlte Bestellung ersetzt die vorherige unbezahlte Session. Die alte URL meldet expired und kann keine Zahlung mehr annehmen.
• Das Erstellen einer Session für eine Bestellung, die bereits bezahlt ist oder eine laufende Zahlung hat, gibt HTTP 409 zurück.
• Nach einer Ablehnung kann der Kunde in derselben Session eine andere Karte oder Wallet versuchen. Ein erneutes Absenden desselben Karten-Tokens führt nie zu einer doppelten Belastung.
• Tapaya legt die Richtlinie für 3-D Secure fest und versucht immer eine Authentifizierung.

Idempotenz und Fehler

Das Erstellen erfordert einen nicht leeren Idempotency-Key mit höchstens 250 Zeichen. Für denselben Händler gilt:

Eine Kartenablehnung ist ein Zahlungsergebnis, kein Beweis dafür, dass eine HTTP-Anfrage fehlgeschlagen ist.