### Onboarding des Händlers [#onboard-your-merchant] Schließen Sie das [Händler-Onboarding](/merchants/onboarding) mit der Funktion für Online-Zahlungen ab, oder für Online-Zahlungen und Zahlungen vor Ort. Ein Händler, der nur Checkout nutzt, benötigt kein Terminal. Geben Sie die Website des Shops und die Angaben zum Online-Geschäft an und warten Sie auf die Freigabe durch den Zahlungsabwickler. Das Anlegen eines Händlerdatensatzes oder eines API-Schlüssels allein schaltet keine Zahlungen frei. Öffnen Sie **Checkout** in der [Tapaya Platform](https://platform.tapaya.com/checkout-settings). Händler, die Online-Zahlungen beantragen, erscheinen automatisch, auch solche, die noch auf die Freigabe warten. Fahren Sie fort, sobald der Händler **Ready** ist. Öffnen Sie die **Settings** des Händlers. Fügen Sie unter **Merchant API key redirects** Ihren Shop zu **Allowed websites** hinzu und legen Sie die Standard-URLs für Erfolg und Abbruch fest. Eine Plattform, die den Secret key der Organisation verwendet, legt diese stattdessen unter **Organization defaults** fest. Die Beispiele verwenden `https://shop.example`. Wallets und Branding beschreiben die [Checkout-Einstellungen](/online/integration/checkout_settings). ### Schlüssel auf dem Server speichern [#store-your-key-on-the-server] Wählen Sie in den **Settings** des Händlers **Create merchant key** und kopieren Sie den Schlüssel `tapaya_test_…`. Er wird nur einmal angezeigt. Bewahren Sie ihn ausschließlich in der serverseitigen Konfiguration auf. Er gehört niemals in Browser-Code oder in die Versionsverwaltung. ```bash title=".env" TAPAYA_ENVIRONMENT=sandbox TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com TAPAYA_SECRET_KEY=tapaya_test_... ``` Das SDK liest `TAPAYA_SECRET_KEY` und `TAPAYA_ENVIRONMENT` automatisch. Die HTTP-Beispiele unten verwenden `TAPAYA_CHECKOUT_API_URL`. Laden Sie die Variablen in Ihren Serverprozess; das SDK lädt keine `.env`-Dateien. Senden Sie den Schlüssel als `Authorization: Bearer `. Ein Händlerschlüssel bestimmt seinen Händler, daher ist kein weiterer Header nötig. Eine Plattform, die viele Händler bedient, verwendet stattdessen den Secret key der Organisation und sendet bei jeder Anfrage `X-Tapaya-Merchant-Token`. Siehe [Checkout-Authentifizierung](/online/integration/api_integration#authentication). ### Checkout-Session erstellen [#create-a-checkout-session] Wenn der Kunde in Ihrem Shop auf **Checkout** klickt, berechnen Sie den endgültigen Gesamtbetrag auf Ihrem Server, speichern Sie die Bestellung mit einem eindeutigen Versuchsschlüssel und erstellen Sie eine Session. `merchantOrderId` ist erforderlich, und eine Bestellung kann nur einmal bezahlt werden. Beträge werden in der kleinsten Währungseinheit angegeben, `12100` entspricht also 121,00 EUR. Installieren Sie für Node.js 22.13.0 oder neuer das ESM-SDK, bevor Sie das Beispiel **Node.js SDK** verwenden: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` HTTP (fetch) Node.js SDK cURL ```js title="server/checkout.js" const response = await fetch( new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL), { method: 'POST', headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': order.checkoutAttemptKey, }, body: JSON.stringify({ merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }), }, ); if (!response.ok) throw new Error(`Checkout failed (${response.status})`); const session = await response.json(); ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const session = await tapaya.checkout.sessions.create( { merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }, { idempotencyKey: order.checkoutAttemptKey }, ); ``` ```bash title="Terminal" curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Wenn die Anfrage in ein Timeout läuft, wiederholen Sie sie mit **demselben** Schlüssel und Body. Die API gibt die ursprüngliche Session erneut zurück, statt eine zweite zu erstellen. ### Kunden weiterleiten [#redirect-the-customer] Speichern Sie `session.id` mit Ihrer Bestellung und leiten Sie den Browser dann mit HTTP 303 auf `session.url` weiter. Verwenden Sie die URL genau so, wie sie zurückgegeben wurde. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Tapaya zeigt die Bestellübersicht und das sichere Zahlungsformular an und übernimmt Tokenisierung, 3-D Secure und Belastung. Nach einer Ablehnung kann der Kunde auf derselben Seite eine andere Karte versuchen. Sessions nehmen 30 Minuten lang neue Zahlungen an. ### Zahlung auf dem Server verifizieren [#verify-the-payment-on-your-server] Wenn der Kunde auf Ihrer Erfolgs- oder Abbruch-URL landet, rufen Sie die Session mit Ihrem Secret key ab und vergleichen Sie sie mit der gespeicherten Bestellung. Eine Weiterleitung allein beweist niemals eine Zahlung. HTTP (fetch) Node.js SDK ```js title="server/return.js" const response = await fetch( new URL( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, process.env.TAPAYA_CHECKOUT_API_URL, ), { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } }, ); if (!response.ok) throw new Error(`Status check failed (${response.status})`); const current = await response.json(); ``` ```ts title="server/return.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); ``` Vergleichen Sie bei beiden Integrationen das Ergebnis mit der gespeicherten Bestellung, bevor Sie diese abwickeln: ```ts const matches = current.id === order.checkoutSessionId && current.merchantOrderId === order.id && current.amount === order.totalInMinorUnits && current.currency === order.currency; if (matches && current.paymentStatus === 'successful') { await fulfillOnce(order); // idempotent, safe on repeated visits } ``` Wenn der Status noch `unpaid` ist oder der Abruf fehlschlägt, behalten Sie die Session-ID und prüfen Sie erneut. Webhooks gibt es noch nicht. Betreiben Sie daher einen Abgleichsjob für Kunden, die den Tab schließen, bevor sie zurückkehren.