← Zurück zum Blog
TutorialVeröffentlicht 2026-11-08· 9 Min. Lesezeit

Waffo-Zahlung einrichten: Next.js-Checkout Schritt für Schritt

WangNan, author at Uncorne
Veröffentlicht von Uncorne · Aktualisiert 2026-11-12

Waffo gibt es in zwei verschiedenen Varianten, und die Einrichtung unterscheidet sich zwischen ihnen. Dieses Tutorial behandelt beide, denn die Uncorne-Integration unterstützt beide über denselben Checkout- und Webhook-Vertrag. Am Ende haben Sie einen Sandbox-Kauf, der eine Lizenz ausstellt.

Schritt 0: Wissen, welches Waffo Sie verdrahten

Waffo ist kein einzelnes Produkt. Pancake ist ein globaler Merchant-of-Record-Checkout — siehe die Waffo-Pancake-Dokumentation. Acquiring ist ein südostasiatisches Acquiring-Gateway mit RSA-signierten Webhooks — siehe die Waffo-Acquiring-Dokumentation. Ein Merchant of Record übernimmt für Sie Umsatzsteuer und MwSt.; das Konzept wird im Merchant-of-Record-Überblick erklärt. Wählen Sie Pancake, es sei denn, Sie haben bereits einen regionalen Acquiring-Vertrag.

Waffo-Dashboard mit den Produktauswahlen Pancake und Acquiring
Waffo-Dashboard mit den Produktauswahlen Pancake und Acquiring

Schritt 1: Variante und Umgebung festlegen

Setzen Sie WAFFO_FLAVOR auf pancake oder acquiring. Der Standard ist pancake; der Adapter wechselt Endpunkte und Signatur entsprechend. Setzen Sie WAFFO_ENVIRONMENT=test für jeden Entwicklungsschritt. Mit der Testumgebung live zu gehen ist der häufigste Weg, eine erste Zahlung zu verlieren — der Checkout sieht gut aus, aber es bewegt sich kein echtes Geld und es wird keine Lizenz ausgestellt.

Schritt 2: Zugangsdaten sammeln

Für Pancake brauchen Sie einen WAFFO_STORE_SLUG (oder WAFFO_STORE_ID / WAFFO_MERCHANT_ID) und einen WAFFO_PRIVATE_KEY. Für Acquiring brauchen Sie die Händlervertragsfelder — WAFFO_ACQUIRING_MERCHANT_INFO, WAFFO_ACQUIRING_USER_INFO, WAFFO_ACQUIRING_PAYMENT_INFO, WAFFO_ACQUIRING_ORDER_CURRENCY und WAFFO_ACQUIRING_ORDER_DESCRIPTION — plus den umgebungsspezifischen Webhook-öffentlichen Schlüssel. Bewahren Sie sie in .env.local auf, niemals im Repository.

PAYMENT_PROVIDER=waffo
WAFFO_FLAVOR=pancake
WAFFO_ENVIRONMENT=test
WAFFO_STORE_SLUG=your-store
WAFFO_PRIVATE_KEY=sk_test_xxx
WAFFO_PRICE_ID_BUYOUT=price_buyout_test
WAFFO_PRICE_ID_CARE=price_care_test
Der Waffo-API-Schlüssel-Bildschirm mit hervorgehobenem Test-Privatschlüssel
Der Waffo-API-Schlüssel-Bildschirm mit hervorgehobenem Test-Privatschlüssel

Schritt 3: Produkte und Preise anlegen

Erstellen Sie im Waffo-Dashboard ein einmaliges Produkt für Buyout und ein wiederkehrendes für Care, und kopieren Sie deren Price-IDs in WAFFO_PRICE_ID_BUYOUT und WAFFO_PRICE_ID_CARE. Für eine Black-Friday-Aktion erstellen Sie separate Price-IDs und setzen WAFFO_PRICE_ID_BUYOUT_BF und WAFFO_PRICE_ID_CARE_BF. Die Webhook-Planerkennung erkennt die BF-IDs automatisch, die Aktion braucht also keine Code-Änderung.

Waffo-Produktbildschirm mit den Price-IDs für Buyout und Care
Waffo-Produktbildschirm mit den Price-IDs für Buyout und Care

Schritt 4: Den Webhook konfigurieren

Richten Sie Waffo auf Ihren Endpunkt /api/payments/webhook/waffo. Pancake verifiziert mit dem öffentlichen RSA-Schlüssel der Plattform (WAFFO_WEBHOOK_PUBLIC_KEY, mit Test- und Produktionsvarianten). Acquiring signiert die Anfrage mit RSA und benötigt denselben öffentlichen Schlüssel. Verifizieren Sie die Signatur immer serverseitig, bevor Sie der Nutzlast vertrauen — überspringen Sie das niemals. Ein Webhook-Endpunkt, der unverifizierte Ereignisse akzeptiert, erlaubt jedem, mit einer einzigen curl-Anfrage eine bezahlte Bestellung zu fälschen.

Der Handler sollte drei Dinge tun: die Signatur prüfen, den Plan aus der Price-ID ableiten und die Lizenzerteilung idempotent aufrufen, damit ein wiederholtes Ereignis keine zwei Lizenzen ausstellt. Protokollieren Sie die Ereignis-ID und die Price-ID; dieses Protokoll ist die erste Anlaufstelle, wenn eine Zahlung keinen Zugriff gewährt.

export async function POST(req: Request) {
  const raw = await req.text();
  if (!verifyWaffoSignature(raw, req.headers)) {
    return new Response("bad signature", { status: 400 });
  }
  const event = JSON.parse(raw);
  const plan = inferPlanFromPriceId(event.price_id);
  await grantLicence(event.customer, plan, event.id);
  return new Response("ok");
}
Ein Webhook-Protokoll mit einem verifizierten Zahlungsereignis und dem abgeleiteten Plan
Ein Webhook-Protokoll mit einem verifizierten Zahlungsereignis und dem abgeleiteten Plan

Der obenstehende Next.js-App-Router-Route-Handler läuft auf dem Server — genau dort, wohin die Signaturprüfung gehört, niemals in einer Client-Komponente.

Schritt 5: Den Anbieter festlegen

Setzen Sie PAYMENT_PROVIDER=waffo plus die oben genannten Variablen. Ein Checkout-Aufruf löst die passende Price-ID für den aktiven Plan auf, und der Webhook gewährt die Lizenz, indem er den Plan aus der Price-ID ableitet. Ist keine Price-ID konfiguriert, fällt der Checkout in den Anzeigemodus zurück — für eine Vorschau nützlich, für Umsätze nutzlos.

Schritt 6: Einen Sandbox-Test durchführen

Nutzen Sie die Testumgebung und einen Testkauf. Bestätigen Sie, dass der Webhook auslöst, der Plan korrekt abgeleitet und der Lizenzschlüssel ausgestellt wird. Testen Sie dann den Fehlerpfad: eine unverifizierte Signatur muss mit 400 abgelehnt werden. Gehen Sie erst live, wenn ein echter Sandbox-Durchlauf grün ist.

Die gehostete Checkout-Seite während eines Waffo-Sandbox-Testkaufs
Die gehostete Checkout-Seite während eines Waffo-Sandbox-Testkaufs

Fehlerbehebung bei drei häufigen Problemen

Öffnet der Checkout, erscheint aber keine Lizenz, ist die Price-ID fast sicher falsch — vergleichen Sie sie mit dem Webhook-Protokoll. Schlägt die Signaturprüfung im Test fehl, verwenden Sie den Produktions- statt des Test-öffentlichen Schlüssels. Ist der Plan immer Buyout, wurde die Care-Price-ID nie in die Umgebung kopiert.

Später das Gateway wechseln

Bei Uncorne teilen sich die fünf Anbieter-Adapter diesen Vertrag, sodass derselbe Codepfad für Creem, Stripe, PayPal und Lemon Squeezy funktioniert — nur die Umgebungsvariablen ändern sich. Lesen Sie das Creem-Zahlungs-Setup-Tutorial für die analogen Schritte oder den Gateway-Vergleich, um sich vor der Entscheidung zu informieren.

Was der Checkout-Aufruf tatsächlich tut

Klickt ein Besucher auf Buyout oder Care, liest eine Server Action den aktiven Plan, löst die passende Price-ID auf und öffnet eine von Waffo gehostete Checkout-Session. Die Price-ID kommt vom Server, ein Kunde kann also keinen URL-Parameter manipulieren, um Care zum Buyout-Preis zu kaufen. Die Session trägt eine Referenz auf Ihre interne Benutzer-ID in den Metadaten; daran weiß der Webhook nach Zahlungseingang, welches Konto gutgeschrieben wird.

Pancake und Acquiring: Was sich wirklich ändert

Beide Varianten teilen den Checkout- und Webhook-Vertrag, aber der Signaturpfad unterscheidet sich. Pancake verifiziert die Nutzlast mit dem öffentlichen RSA-Schlüssel der Plattform; Acquiring signiert jede Anfrage mit RSA und erwartet auf Ihrer Seite denselben öffentlichen Schlüssel. Ihre Verifizierungsfunktion sollte daher die Variante als Parameter nehmen, statt eine Algorithmus-Verzweigung hart zu codieren. Halten Sie für Test und Produktion getrennte öffentliche Schlüssel und versehen Sie jede Webhook-Protokollzeile mit der Umgebung — ein Eintrag ohne Umgebungskennzeichnung ist im Störungsfall fast nutzlos.

Welche Webhook-Ereignisse man protokollieren sollte

Waffo sendet Ereignisse für erfolgreiche Zahlungen, Rückerstattungen und Disputes. Protokollieren Sie jedes mit drei Feldern: Ereignis-ID, Price-ID und Kundenreferenz. Weil die Price-ID im Protokoll steht, können Sie Monate später beantworten, welchen Plan der Kunde tatsächlich gekauft hat, ohne zu raten. Ein Dispute-Ereignis sollte die Lizenz zur Prüfung markieren statt sie still zu entziehen — Sie wollen, dass ein Mensch die Beweise liest, bevor Sie einem zahlenden Kunden den Zugriff nehmen.

Idempotenz ist keine Option

Waffo wiederholt Webhook-Zustellungen, wenn Ihr Endpunkt nicht schnell genug antwortet. Wenn Ihr Handler eine Lizenz ausstellt, bevor er das Ereignis bestätigt, kann ein langsamer Datenbankaufruf zwei Lizenzen für einen Kauf erzeugen. Speichern Sie die Ereignis-ID in einer eindeutigen Spalte und behandeln Sie Duplikate als erfolgreichen No-Op. Das ist die häufigste Ursache für Tickets à la „Warum hat dieser Kunde zwei Plätze?" — und im Happy-Path-Test unsichtbar.

Eine Sandbox-Matrix, kein einzelner Erfolgsfall

Ein erfolgreicher Kauf ist eine Demo, kein Test. Führen Sie vor dem Go-Live diese kurze Matrix im Testmodus aus:

  1. Buyout mit Standard-Price-ID — Lizenz ausgestellt, Plan korrekt abgeleitet.
  2. Care mit Standard-Price-ID — wiederkehrender Plan aktiv, Verlängerungsdatum gespeichert.
  3. BF-Price-ID bei aktivierter Aktion — BF-Plan abgeleitet, keine Code-Änderung.
  4. Ein erneut zugestellter Webhook mit derselben Ereignis-ID — keine zweite Lizenz, keine doppelte Abbuchung.
  5. Eine Anfrage mit manipulierter Signatur — mit 400 abgelehnt und protokolliert.

Zeile 5 fängt einen falsch konfigurierten öffentlichen Schlüssel. Ein grüner Happy Path mit kaputter Signaturprüfung ist ein Sicherheitsloch, das Sie gerade ausgeliefert haben.

Go-Live-Checkliste

Stellen Sie WAFFO_ENVIRONMENT auf production, tauschen Sie den Live-Privatschlüssel und den Live-Webhook-öffentlichen Schlüssel ein und richten Sie die Webhook-URL auf Ihre Produktionsdomain über HTTPS. Machen Sie dann einen kleinen echten Kauf und verfolgen Sie die ganze Kette: Zahlung, Webhook, Planableitung, Lizenz. Halten Sie Test-Price-IDs aus der Produktion fern — sie sind die häufigste Ursache für „Im Staging lief es ja".

Weiterlesen

Der Fünf-Adapter-Vertrag bedeutet, dass sich diese betrieblichen Gewohnheiten direkt übertragen. Der Gateway-Vergleich erklärt, wann ein Merchant of Record seine Gebühr wert ist, der Leitfaden zu Abrechnungs-Gateways deckt die größere Entscheidung ab.

FAQ

Welche Waffo-Variante sollte ich verwenden?+

Verwenden Sie pancake für einen globalen Merchant-of-Record-Checkout. Acquiring nur, wenn Sie bereits einen regionalen Acquiring-Vertrag haben, der dessen spezifische Felder und RSA-Signatur erfordert.

Muss ich die Waffo-Webhook-Signatur prüfen?+

Ja. Die Integration prüft sie serverseitig mit dem öffentlichen Schlüssel der Plattform – für beide Varianten. Das Auslassen würde jedem erlauben, mit einer unsignierten Anfrage ein bezahltes Ereignis zu fälschen.

Wie wird die Lizenz ausgestellt?+

Der Webhook leitet den Plan aus der Price-ID ab (einschließlich BF-IDs) und ruft die Lizenzerteilung idempotent auf. Ohne konfigurierte Price-ID fällt der Checkout in den Anzeigemodus zurück.

Was prüfe ich, wenn eine Zahlung keinen Zugriff gewährt?+

Vergleichen Sie die Price-ID im Webhook-Protokoll mit Ihren Umgebungsvariablen. Eine falsche Price-ID, ein Produktions-öffentlicher Schlüssel im Test und eine fehlende Care-Price-ID sind die drei häufigsten Ursachen.

Alle häufigen Fragen · Markdown-Version (für KI-Agenten)