Schnellstart

Onboarding des Händlers

Schließen Sie das Händler-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. 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.

Schlüssel auf dem Server speichern

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.

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

Checkout-Session erstellen

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 install @tapayadot/checkout

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();

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

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.

// 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

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.

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();

Vergleichen Sie bei beiden Integrationen das Ergebnis mit der gespeicherten Bestellung, bevor Sie diese abwickeln:

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.