Auf Dodo Payments installieren

Dodo Payments ist ein Merchant of Record für digitale Produkte und SaaS, und Rekomi ist direkt damit integriert. Für die Einrichtung fügst du nur einmal etwas ein: Du gibst Rekomi einen API-Schlüssel mit aktiviertem Schreibzugriff, und Rekomi prüft ihn live, legt den Webhook-Endpunkt selbst in deinem Dodo-Payments-Konto an und holt dir dessen Signing Secret. Du musst nichts zurück in Dodo kopieren und kein Webhook-Formular von Hand ausfüllen. Ab dann landen Zahlungen, Abo-Verlängerungen, Erstattungen und Streitfälle in Rekomi, ohne dass du Relay-Code schreiben oder pflegen musst. Du bist noch am Abwägen? Lies Warum Rekomi für Dodo Payments →.

Eine Sache vorab: Der Schlüssel braucht aktivierten Schreibzugriff. Die Nur-Lese-Schlüssel von Dodo bestehen zwar die normale Prüfung, können aber keine Webhooks anlegen. Ein Nur-Lese-Schlüssel scheitert deshalb mitten im Verbinden mit einer Fehlermeldung, die genau das sagt. Nach dem Verbinden dient der Schlüssel nur dazu, den Webhook-Endpunkt zu verwalten und regelmäßig einen Gesundheitscheck mit reinem Lesezugriff auszuführen. Deine Verkäufe kommen über den signierten Webhook an, nicht über den Schlüssel.

Was du brauchst

• Ein Dodo-Payments-Konto im Live-Modus. Der Testmodus ist eine komplett getrennte Welt auf einem eigenen Host (test.dodopayments.com) mit eigenen Schlüsseln und eigenen Webhooks. Rekomi lehnt Zugangsdaten aus dem Testmodus bei einer Produktivverbindung mit einer klaren Fehlermeldung ab, bevor irgendetwas gespeichert wird.
• Einen API-Schlüssel mit aktiviertem Schreibzugriff. Öffne in Dodo Payments Developer > API Keys und erstelle einen Schlüssel (nenne ihn „Rekomi“). Dodo-Schlüssel laufen nicht ab. Wird der Schlüssel irgendwann widerrufen, markieren die regelmäßigen Gesundheitschecks von Rekomi die Verbindung als unterbrochen und schicken dir eine E-Mail (du kannst das auch sofort mit dem Button „Verbindung prüfen“ auf der Einrichtungsseite bestätigen).
• Zwei Minuten. Kein OAuth-Hin-und-her, kein Webhook-Formular und kein Secret zum Kopieren: Im ganzen Ablauf fügst du nur einmal etwas ein.

In Rekomi verbinden

Schritt 1. Öffne /dashboard/setup/dodo.

Schritt 2. Füge deinen API-Schlüssel mit Schreibzugriff ein und klicke auf Dodo Payments verbinden. Rekomi prüft den Schlüssel live bei Dodo, legt einen Webhook-Endpunkt an, der auf die URL deines Workspaces zeigt und genau die benötigten Ereignisse abonniert, und holt sich selbst das Signing Secret des Endpunkts. Scheitert einer der beiden Schritte, wird ein Endpunkt, dessen Secret nicht gespeichert werden konnte, wieder gelöscht, statt weiter Ereignisse zu liefern, die Rekomi nicht prüfen kann. (Scheitert im seltenen Fall auch dieses Aufräumen, wird der verwaiste Endpunkt zum Entfernen markiert und zählt bis zum Löschen gegen das Endpunkt-Limit von Dodo.)

Das war's. Die Einrichtungsseite zeigt die Webhook-URL und die registrierten Ereignisse nur zur Information; Rekomi verwaltet den Endpunkt komplett selbst.

Attribution: rekomi_ref in den Checkout-Metadaten übergeben (Pflicht)

Dodo hostet seinen Checkout auf der eigenen Domain, deshalb muss die Affiliate-Empfehlung vom Browser des Besuchers in den Zahlungsdatensatz gelangen. Dieser Schritt ist für die Attribution von Neukunden Pflicht: Ohne ihn kommen Verkäufe ohne Empfehlung an, und es wird keine Provision gutgeschrieben, es sei denn, die E-Mail-Adresse des Käufers passt zu einem Lead, der auf deiner Website erfasst wurde (der Fallback am Ende dieses Abschnitts).

Sorge zuerst dafür, dass das Rekomi-Tracking-Skript auf deiner Marketing-Website installiert ist, damit der Affiliate-Klick erfasst wird und window.Rekomi.getReferral() einen Wert liefert, wenn ein Besucher über einen Affiliate-Link kommt. Das ist dasselbe Skript, das jede Rekomi-Installation nutzt; die Anleitung für deine Website-Plattform im Installations-Hub deckt es ab. Ein eigenes Skript für Dodo brauchst du nicht: Die native Verbindung, die du oben eingerichtet hast, erfasst den Verkauf. Wähle dann die Anleitung, die zu deiner Verkaufsweise passt:

Checkouts über die API von Dodo erstellen. Lies die Empfehlung im Frontend mit window.Rekomi.getReferral() aus, schicke sie mit der Checkout-Anfrage an dein Backend und setze sie in metadata bei POST /checkouts, /subscriptions oder /payments:

{
  "product_cart": [{ "product_id": "prod_your_product", "quantity": 1 }],
  "metadata": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
}

Statische Zahlungslinks. Ergänze den Link um den flachen Metadaten-Parameter. Dodo übernimmt Query-Parameter der Form metadata_key=value in die Metadaten der Zahlung (achte auf die flache Form mit Unterstrich, nicht auf die Klammerform metadata[rekomi_ref], die manche anderen Plattformen nutzen):

const ref = window.Rekomi?.getReferral?.();
const url = new URL("https://checkout.dodopayments.com/buy/prod_your_product");
if (ref) url.searchParams.set("metadata_rekomi_ref", ref);
// use url.toString() as the href on your Buy button

Abo-Metadaten bleiben über die gesamte Laufzeit des Abonnements erhalten, und Rekomi greift zusätzlich auf die Attributionshistorie des Kunden zurück, sodass Verlängerungen demselben Affiliate gutgeschrieben werden. Der Wert wird ohne Rücksicht auf Groß- und Kleinschreibung mit dem Slug des Affiliates abgeglichen. Ein Code, den du als SERKAN speicherst, wird also dem Affiliate mit dem Slug serkan gutgeschrieben.

Abgleich über die Lead-E-Mail (Fallback). Erreicht eine Zahlung Rekomi ohne rekomi_ref in den Metadaten und enthält das Ereignis die E-Mail-Adresse des Kunden, gleicht Rekomi diese Adresse zusätzlich mit den Leads ab, die das Rekomi-Skript in den letzten 90 Tagen auf deiner eigenen Website erfasst hat (das Tag, das Rekomi dir gibt, enthält data-rkmi-email-capture="auto" und erfasst damit die E-Mail-Adresse aus deinem Anmeldeformular als Lead; siehe Lead-Tracking), und schreibt dem Affiliate gut, der diesen Lead gebracht hat. Die Empfehlung in den Metadaten hat immer Vorrang, wenn sie vorhanden ist, genauso wie der bisherige Verlauf des Kunden, und ein Affiliate, der mit seiner eigenen E-Mail-Adresse kauft, bekommt keine Gutschrift.

So werden Verkäufe und Verlängerungen erfasst

• Jede Belastung kommt als ein Zahlungsereignis an. Einmalkäufe, die erste Abo-Zahlung, jede Verlängerung, Zahlungen bei Planwechseln und Nachzahlungen nach einer Sperre („on hold“) werden alle über das Ereignis payment.succeeded von Dodo erfasst, mit dem belasteten Betrag.
• Ob Erstzahlung oder Verlängerung, leitet Rekomi ab. Das Zahlungsereignis von Dodo kennzeichnet nicht, ob es die erste Zahlung oder eine Verlängerung ist, also leitet Rekomi es ab: Eine Zahlung zu einem Abonnement, das Rekomi schon kennt, wird als wiederkehrend erfasst, eine zu einem unbekannten als erste Zahlung. Kommen Zustellungen einmal in falscher Reihenfolge an, können die beiden Kennzeichnungen vertauscht sein. Die Beträge stimmen immer, und die Provision folgt der vergebenen Kennzeichnung (wiederkehrende Regeln wie Verzögerungen und Obergrenzen richten sich danach).
• Provisionen werden auf den Verkaufsbetrag vor Steuern berechnet. Dodo Payments ist ein Merchant of Record und meldet die Zahlung mit ausgewiesener Steuer, deshalb erfasst Rekomi den Verkauf abzüglich der Steuerzeile: Deine Affiliates verdienen am Verkauf, nicht an der Steuer, die das Land des Käufers gerade aufschlägt. Erstattungen und Streitfälle werden inklusive Steuer gemeldet, und jede Rückforderung ist auf den gutgeschriebenen Betrag begrenzt. Eine volle Erstattung oder ein Streitfall holt also genau den provisionsfähigen Betrag zurück. Eine ehrliche Randnotiz: Eine Teilerstattung enthält keine Steueraufteilung, also wird ihr angegebener Betrag (inklusive Steuer) gegen die Gutschrift vor Steuern zurückgefordert. Das ist etwas vorsichtig gerechnet, geht nie über die ursprüngliche Gutschrift hinaus, und eine Folge von Teilerstattungen läuft genau auf eine vollständige Rückforderung hinaus.
• Testphasen lösen bis zu ihrem Ende kein Zahlungsereignis aus, also entsteht erst mit der ersten echten Zahlung eine Provision. Ereignisse im Lebenszyklus eines Abonnements (aktiv, gesperrt, gekündigt, abgelaufen) kommen als Kündigungssignale an, für Provisionsregeln, die bei Kündigung stoppen.
• Alles wird anhand der zugrunde liegenden IDs von Zahlung, Abonnement, Erstattung und Streitfall dedupliziert, sodass Wiederholungen und manuelle Neuzustellungen von Dodo nie doppelt zählen.

Erstattungen und Streitfälle

Erstattungen machen die Provision automatisch rückgängig: Eine Teilerstattung holt den erstatteten Anteil zurück, und mehrere Teilerstattungen holen so lange zurück, bis die ursprüngliche Provision aufgebraucht ist, nie darüber hinaus. Dodo erlaubt Erstattungen innerhalb von 30 Tagen nach der Transaktion; jede Teilerstattung kommt als eigenes Erstattungsereignis an. Ein ehrlicher Hinweis: Dodo meldet eine volle Erstattung manchmal ohne Betrag im Ereignis. Rekomi behandelt das als Erstattung des gesamten Restbetrags der Conversion, und das ist die sichere Lesart (die Rückforderung ist so oder so auf die ursprüngliche Provision begrenzt). Ein Ereignis ohne Betrag, das sich als Teilerstattung ausgibt, wird zur Prüfung markiert, statt geraten zu werden.

Streitfälle (Rückbuchungen) holen das strittige Geld schon bei Eröffnung des Streitfalls zurück. Gewinnst du den Streitfall später, wird die Provision in dieser Version nicht automatisch wiederhergestellt; der Gewinn wird protokolliert, damit du bei Bedarf manuell nachbessern kannst. Ein verlorener Streitfall ändert nichts weiter (das Geld wurde schon bei Eröffnung zurückgeholt).

Vorbehalt bei eigenem Zahlungsdienstleister (BYOP). Dodo erlaubt manchen Händlern, über ihr eigenes Stripe- oder Adyen-Konto hinter dem Dodo-Checkout abzuwickeln (Bring Your Own Provider). Zahlungen werden so oder so normal erfasst, aber BYOP-Zahlungen lösen unter Umständen nie Webhooks für Erstattungen oder Streitfälle aus (der Händler wickelt diese bei seinem eigenen Anbieter ab). Rückforderungen bei BYOP-Erstattungen erledigst du deshalb manuell.

Währungen

Mit der Funktion Adaptive Currency kann Dodo im Checkout mehr als 80 lokale Währungen anzeigen, und die Liste von Rekomi mit über 135 erlaubten Währungen deckt sie alle ab: VND, NGN, CLP und die Währungen mit drei Nachkommastellen KWD, BHD und OMR werden normal erfasst, und auch mit drei Nachkommastellen wird korrekt gerechnet. Kommt im seltenen Fall ein Betrag in einer Währung außerhalb der Liste an, wird das Ereignis übersprungen und markiert, statt geraten zu werden, damit nie eine Provision auf einen verfälschten Betrag berechnet wird.

Sicherheit

• Jede Webhook-Zustellung wird per Signatur geprüft (nach dem Standard-Webhooks-Schema: HMAC über Zustellungs-ID, Zeitstempel und Body, mit einem Aktualitätsfenster von 300 Sekunden), bevor irgendetwas verarbeitet wird. Bei allem Fehlerhaften bleibt die Verarbeitung aus (Fail-closed).
• Der API-Schlüssel und das Webhook-Signing-Secret werden verschlüsselt gespeichert und nie von der API zurückgegeben. Das Signing Secret siehst und berührst du überhaupt nicht; Rekomi holt und speichert es direkt.
• Beim Trennen wird der Webhook-Endpunkt bei Dodo gelöscht, beide Secrets werden gelöscht, und die Webhook-URL wird stillgelegt.
• Live-Modus und Testmodus sind schon vom Aufbau her getrennt: Sie laufen auf getrennten Hosts mit getrennten Schlüsseln und getrennten Webhooks, und Ereignisse werden zusätzlich mit dem verbundenen Business abgeglichen, bevor etwas erfasst wird.

Gut zu wissen

• Eine Conversion-Quelle pro Workspace. Dodo Payments Connect schließt Stripe (über die Rekomi-App für Stripe), Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Mollie und die S2S-API aus, damit derselbe Verkauf nie doppelt gezählt wird. Trenne die eine Verbindung, bevor du eine andere herstellst. Und um einen Randfall genau zu benennen: Verkaufst du über Dodo mit BYOP über dein eigenes Stripe-Konto, verbindest du Dodo. Stripe Connect würde diese Zahlungen nicht so sehen, wie Dodo sie meldet.
• API-Schlüssel von Dodo laufen nicht ab. Markiert der Gesundheitscheck die Verbindung als unterbrochen, wurde der Schlüssel in Dodo widerrufen oder der Webhook-Endpunkt dort gelöscht oder deaktiviert; ein routinemäßiger Ablauf ist es nie. Es gibt keine API zum Rotieren des Secrets, also ist die Lösung immer dieselbe: Erstelle einen neuen Schlüssel mit aktiviertem Schreibzugriff und verbinde neu.
• Der Endpunkt lässt sich im Dashboard von Dodo deaktivieren. Passiert das, sagen die Einrichtungsseite und die E-Mail zum Neuverbinden genau das: Aktiviere ihn im Dashboard von Dodo wieder oder verbinde neu (dabei wird er neu angelegt).
• Bearbeite die Ereignisliste des Endpunkts nicht im Dashboard von Dodo. Rekomi registriert den Endpunkt mit genau den Ereignissen, die es braucht. Wählst du eines davon ab, hören diese Zustellungen stillschweigend auf (Dodo meldet nirgends einen Fehler). Der Gesundheitscheck vergleicht die Ereignisliste des Endpunkts mit der registrierten Liste und markiert die Verbindung als unterbrochen, wenn Ereignisse entfernt wurden; neu verbinden stellt die volle Liste wieder her.
• Dodo begrenzt die Zahl der Webhook-Endpunkte pro Konto. Ist dein Konto am Limit, scheitert das Verbinden mit einer Fehlermeldung, die genau das sagt. Entferne einen ungenutzten Endpunkt im Dashboard von Dodo und versuche es noch einmal.
• Ein Moduswechsel lässt den alten Endpunkt zurück. Live und Test sind getrennte Welten, deshalb kann ein Neuverbinden im anderen Modus den Endpunkt des bisherigen Modus nicht aufräumen. Wechselst du, lösche den alten Endpunkt im Dodo-Dashboard dieses Modus (er zählt ebenfalls gegen das Endpunkt-Limit).
• Die Wiederholungsstaffel läuft etwa 27.5 Stunden. Dodo stellt bis zu 8-mal innerhalb von etwa 27.5 Stunden zu (sofort, dann nach 5 Sekunden, 5 Minuten, 30 Minuten, 2 Stunden, 5 Stunden, 10 Stunden, 10 Stunden). Kann Rekomi ein Geldereignis kurz nicht verarbeiten, antwortet es absichtlich mit einem Fehler, damit Dodo erneut zustellt. Für alles, was länger dauert als die Staffel, hat das Dashboard von Dodo Zustellprotokolle mit manueller Neuzustellung, und Rekomi erfasst Neuzustellungen sicher, ohne doppelt zu zählen.
• Attribution per Gutscheincode ist für Dodo noch nicht angebunden. Die Attribution läuft über die Metadaten rekomi_ref. Rabattcodes pro Affiliate funktionieren weiterhin als normale Rabatte, ordnen den Verkauf über diese Anbindung aber nicht selbst zu.

Den Ablauf testen

Der Testmodus von Dodo läuft auf einem eigenen Host, und Produktivverbindungen von Rekomi lehnen Zugangsdaten aus dem Testmodus bewusst ab. Ein vollständiger Probelauf findet deshalb in einer Staging-Umgebung statt. Was du in der Produktion prüfen kannst, ohne Geld auszugeben:

1. Verbinde und klicke dann auf der Einrichtungsseite auf Verbindung prüfen: Das prüft live den Webhook-Endpunkt, den Rekomi angelegt hat (Gültigkeit des Schlüssels, Existenz des Endpunkts, die Deaktiviert-Markierung und die Ereignisliste des Endpunkts, alles in einer Prüfung).
2. Prüfe, dass der Endpunkt in deinem Dodo-Dashboard unter Developer > Webhooks erscheint und auf die URL deines Workspaces zeigt.
3. Tätige einen echten Kauf über einen Affiliate-Link, bei dem ?via= auf den Link-Slug eines freigegebenen Affiliates gesetzt ist, prüfe die Conversion innerhalb einer Minute im Tab Performance der Kampagne, erstatte den Kauf dann und prüfe, dass die Provision zurückgeholt wird.

Fehlerbehebung

„...has WRITE ACCESS enabled (read-only keys cannot create webhooks)...“ Der Schlüssel wurde akzeptiert, konnte aber den Webhook-Endpunkt nicht anlegen. Die Nur-Lese-Schlüssel von Dodo können dein Konto lesen, aber nicht darin schreiben. Erstelle unter Developer > API Keys einen Schlüssel mit aktiviertem Schreibzugriff und verbinde damit.

„reached its webhook endpoint limit.“ Dein Konto hat das Endpunkt-Limit von Dodo erreicht, deshalb wurde das Anlegen abgelehnt. Entferne einen ungenutzten Endpunkt im Dodo-Dashboard (Developer > Webhooks) und verbinde erneut.

„Test mode connections are not available here.“ Du hast bei einer Produktivverbindung den Testmodus von Dodo gewählt (oder dein Schlüssel gehört dazu). Der Testmodus ist eine getrennte Welt; verbinde mit einem Schlüssel aus dem Live-Modus.

Banner oder E-Mail „Deine Dodo-Payments-Verbindung ist unterbrochen.“ Entweder wird der gespeicherte API-Schlüssel nicht mehr akzeptiert (in Dodo widerrufen), der Webhook-Endpunkt fehlt oder wurde deaktiviert, oder die Ereignisliste des Endpunkts wurde so bearbeitet, dass er nicht mehr alles abonniert, was Rekomi braucht. Die Meldung sagt, welcher Fall vorliegt. Bei einem deaktivierten Endpunkt aktivierst du ihn im Dashboard von Dodo wieder oder verbindest neu. In allen anderen Fällen erstellst du einen neuen Schlüssel mit aktiviertem Schreibzugriff und verbindest unter /dashboard/setup/dodo neu; deine Tracking-Historie bleibt erhalten.

Verkäufe kommen an, aber kein Affiliate erhält eine Gutschrift. Die Zahlung hat Rekomi erreicht, aber ohne rekomi_ref. Prüfe, dass dein Aufruf zum Erstellen des Checkouts metadata.rekomi_ref setzt (oder deine statischen Zahlungslinks den flachen Parameter ?metadata_rekomi_ref= tragen) und dass das Tracking-Skript lief, bevor der Käufer weitergeklickt hat (damit window.Rekomi.getReferral() einen Wert hatte).

Ein Verkauf in einer exotischen Währung wurde nicht erfasst. Rekomi kann über 135 Währungen verarbeiten, das kommt also nur noch selten vor. Wenn doch, lag das Ereignis außerhalb der erlaubten Liste und wurde bewusst übersprungen und markiert (siehe Währungen oben), statt mit einem geratenen Wert erfasst zu werden.

Nach einem Ausfall fehlt eine Conversion. Die Wiederholungsstaffel von Dodo deckt etwa 27.5 Stunden ab. Für alles Ältere öffnest du die Zustellung in den Webhook-Protokollen im Dashboard von Dodo und stellst sie erneut zu; Rekomi erfasst sie sicher, ohne doppelt zu zählen.

Verwandte Seiten

• Rekomi in der offiziellen Dokumentation von Dodo Payments, die eigene Anleitung von Dodo zu dieser Integration
• Referenz der S2S-Tracking-API
• Checkout-Tracking ohne Code und ohne Stripe
• Umgang mit Erstattungen