Auf Chargebee installieren

Chargebee ist eine Abo-Abrechnung, die auf deinem eigenen Zahlungsanbieter aufsetzt, und Rekomi ist direkt damit integriert. Du fügst deinen Site-Namen und einen Read-Only-API-Schlüssel in Rekomi ein und legst dann in Chargebee einen Webhook an, der auf die Rekomi-URL deines Workspaces zeigt. Ab dann fließen Zahlungen, Abo-Verlängerungen und Erstattungen in Rekomi, ohne dass du Relay-Code schreiben oder pflegen musst. Du bist noch am Abwägen? Lies Warum Rekomi für Chargebee →.

Eine Sache vorweg: Chargebee-Webhooks sind nicht signiert (Chargebee bietet keine Signierung von Webhooks), deshalb authentifiziert Rekomi jede Zustellung mit Zugangsdaten für Basic Authentication, die Rekomi für dich erzeugt. Das Passwort wird genau einmal angezeigt; du fügst es zusammen mit der URL in die Webhook-Einstellungen von Chargebee ein.

Was du brauchst

• Deinen Site-Namen. Die Subdomain deiner Chargebee-URL: acme aus acme.chargebee.com. Test-Sites enden auf -test (zum Beispiel acme-test) und haben eigene Schlüssel und Webhooks.
• Einen Read-Only-API-Schlüssel. Öffne in Chargebee Settings > Configure Chargebee > API Keys and Webhooks > API Keys, klicke auf + Add API Key und wähle den Typ Read-Only mit Zugriff auf all resources (ein eingeschränkter Read-Only-Schlüssel funktioniert auch, solange er Kunden lesen kann). Rekomi prüft damit die Verbindung und führt regelmäßige Gesundheitschecks durch; der Schlüssel wird nie genutzt, um etwas in deiner Site zu ändern.

In Rekomi verbinden

Schritt 1. Öffne /dashboard/setup/chargebee. Die Seite zeigt die Webhook-URL deines Workspaces und die Zugangsdaten für Basic Authentication (Benutzername rekomi plus ein erzeugtes Passwort).

Schritt 2. Kopiere Webhook-URL, Benutzername und Passwort. Das Passwort wird nur einmal angezeigt. Es wird verschlüsselt gespeichert und kann nicht erneut angezeigt werden. Wenn du es verlierst, hat die Einrichtungsseite einen eigenen Button Neu erzeugen, der ein neues Passwort erstellt (das alte funktioniert dann sofort nicht mehr, du müsstest also den Chargebee-Webhook mit dem neuen Wert aktualisieren).

Schritt 3. Lege mit diesen Werten den Webhook in Chargebee an (der nächste Abschnitt zeigt die genauen Einstellungen).

Schritt 4. Trag zurück in Rekomi deinen Site-Namen und den Read-Only-API-Schlüssel ein und klicke auf Chargebee verbinden. Rekomi prüft das Paar live gegen deine Site, bevor es angenommen wird.

Den Webhook in Chargebee anlegen

Öffne in Chargebee Settings > Configure Chargebee > API Keys and Webhooks > Webhooks und klicke auf Add Webhook:

1. Füge die Webhook-URL von der Rekomi-Einrichtungsseite ein.
2. Schalte „Protect webhook URL with basic authentication“ ein und trag Benutzername und Passwort von der Einrichtungsseite ein.
3. Stelle die API version auf V2. Rekomi verarbeitet nur V2-Payloads; V1-Zustellungen werden abgelehnt, damit Chargebee sie erneut sendet, sobald du die Version korrigiert hast.
4. Hake „Exclude card information from the webhook call“ an. Rekomi braucht nie Kartendaten.
5. Wähle diese Ereignisse:

• payment_succeeded
• payment_refunded
• payment_failed
• subscription_created
• subscription_activated
• subscription_cancelled
• subscription_reactivated
• subscription_changed
• subscription_deleted
• credit_note_created

Eine Konfiguration mit „All Events“ funktioniert auch (Rekomi bestätigt Ereignistypen, die es nicht nutzt, und ignoriert sie), aber mit der expliziten Liste bleibt der Datenverkehr schlank.

Attribution: rekomi_ref auf dem Abonnement mitgeben (Pflicht)

Chargebee hostet den Checkout auf seiner eigenen Domain, deshalb muss die Affiliate-Empfehlung vom Browser des Besuchers in den Abo-Datensatz gelangen. Dieser Schritt ist Pflicht: Ohne ihn kommen Zahlungen ohne Empfehlung an, und es wird keine Provision gutgeschrieben, außer die E-Mail-Adresse des Käufers passt zu einem auf deiner Website erfassten Lead (der Fallback am Ende dieses Abschnitts).

Stelle zuerst sicher, dass das Rekomi-Head-Skript auf deiner Marketing-Website installiert ist, damit das Affiliate-Cookie gesetzt wird, wenn ein Besucher über einen Affiliate-Link kommt:

<script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="YOUR_PROGRAM_ID" data-rkmi-email-capture="auto"></script>

Die Programm-ID findest du im Rekomi-Dashboard unter Einstellungen, Tracking, Website-Snippet (der Installationsbereich). Rekomi erfasst eine E-Mail-Adresse, die ein vermittelter Besucher auf den Seiten, auf denen das Tag läuft, in ein beliebiges E-Mail- oder Textfeld tippt (Registrierung, Login, Checkout und andere Formulare), damit der Verkauf auch dann gutgeschrieben werden kann, wenn dein Checkout keine Empfehlung übergibt. Ohne Empfehlung wird nichts erfasst. Entferne das Attribut data-rkmi-email-capture, um das auszuschalten; explizite Aufrufe von Rekomi.convert() funktionieren weiterhin.

Wähle dann das Rezept, das dazu passt, wie du Abonnements anlegst. Rekomi liest die Empfehlung zuerst vom Abonnement, dann vom Kunden, jeweils sowohl aus meta_data als auch aus benutzerdefinierten Feldern.

Abonnements über die API anlegen. Setze meta_data beim Anlegen des Abonnements. Lies die Empfehlung in deinem Frontend mit window.Rekomi.getReferral() aus und schick sie mit der Checkout-Anfrage an dein Backend:

{
  "meta_data": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
}

Hosted Pages oder das Drop-in-Skript. Lege in Chargebee ein benutzerdefiniertes Feld für Abonnements an (Settings > Configure Chargebee > Custom Fields) mit dem API-Namen cf_rekomi_ref, als einzeiliger Text. Hänge es dann an deine Checkout-URLs an:

<script>
  document.addEventListener('DOMContentLoaded', function () {
    var ref = window.Rekomi && window.Rekomi.getReferral();
    if (!ref) return;
    document
      .querySelectorAll('a[href*=".chargebee.com/hosted_pages"]')
      .forEach(function (a) {
        var url = new URL(a.href);
        url.searchParams.set('subscription[cf_rekomi_ref]', ref);
        a.href = url.toString();
      });
  });
</script>

Du nutzt statt Links auf Hosted Pages das Drop-in-Skript von Chargebee? Übergib dasselbe Feld im Produktobjekt, bevor du den Checkout öffnest:

var ref = window.Rekomi && window.Rekomi.getReferral();
if (ref) product.data["cf_rekomi_ref"] = ref;

Benutzerdefinierte Felder, die auf einer Test-Site angelegt werden, veröffentlichst du in den Einstellungen für Custom Fields von Chargebee auf der Live-Site. Lege das Feld also einmal an und veröffentliche es.

Abgleich über die Lead-E-Mail (Fallback). Erreicht eine Zahlung Rekomi ohne rekomi_ref auf dem Abonnement oder dem Kunden 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 (schalte die E-Mail-Erfassung in deinem Registrierungsformular mit data-rkmi-email-capture="auto" am Loader-Tag ein; siehe Lead-Tracking), und schreibt dem Affiliate gut, der diesen Lead gebracht hat. Ist die Empfehlung auf dem Abonnement vorhanden, hat sie immer Vorrang, genauso wie der bisherige Verlauf des Kunden, und ein Affiliate, der mit seiner eigenen E-Mail-Adresse kauft, bekommt keine Gutschrift.

Was erfasst wird

• Zahlungen werden erfasst, wenn payment_succeeded ausgelöst wird: Die erste erfolgreiche Zahlung eines Abonnements ist die erste Conversion, und einmalige Zahlungen ohne Abonnement sind einmalige Conversions.
• Abo-Verlängerungen werden bei jeder erfolgreichen Verlängerungszahlung als wiederkehrende Conversions erfasst, Provisionen mit wiederkehrender Umsatzbeteiligung laufen also automatisch weiter. Die bei der Anmeldung gesetzte Empfehlung bleibt auf dem Abonnement, und Rekomi greift zusätzlich auf den Conversion-Verlauf des Kunden zurück, sodass Verlängerungen demselben Affiliate gutgeschrieben werden.
• Anmeldungen (subscription_created) werden als Ereignisse ohne Wert erfasst, damit der Kunde schon vor der ersten Zahlung mit dem Affiliate verknüpft ist.
• Erstattungen, ob vollständig oder teilweise, holen die Provision automatisch und anteilig zurück, wenn payment_refunded ausgelöst wird, im selben Prüfprotokoll wie die ursprüngliche Conversion.

Erstattungen und Rückbuchungen

Erstattungen, die du in Chargebee auslöst (erstattbare Credit Notes), kommen als payment_refunded an und machen die Provision anteilig rückgängig: Eine Erstattung von 40% holt 40% der Provision zurück. Rückbuchungen, die über die Funktion Chargeback Management von Chargebee laufen, erreichen Rekomi auf demselben Weg, als Erstattungen und Credit Notes, und werden ebenfalls zurückgeholt. Streitfälle, die außerhalb dieser Funktion gelöst werden (direkt bei deinem Zahlungsanbieter), erzeugen keine Chargebee-Ereignisse und sind für Rekomi unsichtbar; korrigiere sie von Hand, falls sie für eine Auszahlung wichtig sind.

Credit Notes zur Anpassung, die eine Rechnung verringern, ohne dass Geld fließt, werden registriert, aber nie als Geld erfasst.

Sicherheit

• Jede Webhook-Zustellung wird mit den Zugangsdaten für Basic Authentication geprüft, bevor irgendetwas verarbeitet wird; Zustellungen, die die Prüfung nicht bestehen, werden abgelehnt.
• Halte Webhook-URL und Zugangsdaten geheim und behandle sie wie ein Passwort. Alles läuft durchgehend über HTTPS.
• Chargebee bietet keine Signierung von Webhooks. Deshalb erzeugt Rekomi die Zugangsdaten, statt den üblicheren Weg mit einem Signing-Secret zu gehen, den du vielleicht von Stripe oder Paddle kennst. Die Zugangsdaten und deine nicht erratbare URL pro Workspace bilden zusammen die Authentifizierung.
• Dein Read-Only-API-Schlüssel und das Webhook-Passwort werden verschlüsselt gespeichert. Das Passwort wird nur einmal zurückgegeben, im Moment seiner Erzeugung, und lässt sich nie wieder abrufen. Beim Trennen werden beide gelöscht, und die Webhook-URL wird stillgelegt.

Gut zu wissen

• Eine Conversion-Quelle pro Workspace. Chargebee Connect schließt Stripe (über die Rekomi-App für Stripe), Paddle, Braintree, Shopify, Lemon Squeezy, Polar, Recurly, Gumroad, Creem, Dodo Payments, Mollie und die S2S-API aus, damit derselbe Verkauf nie doppelt gezählt wird. Trenne die eine Verbindung, bevor du eine andere herstellst.
• Chargebee-API-Schlüssel laufen nicht ab. Meldet der Gesundheitscheck die Verbindung als unterbrochen, wurde der Schlüssel gelöscht oder deaktiviert, die Site umbenannt oder die Webhook-Zugangsdaten geändert; ein routinemäßiger Ablauf ist es nie.
• Verspätete Zustellungen sind kein Problem. Chargebee wiederholt fehlgeschlagene Webhooks bis zu zwei Tage lang. Rekomi entfernt Duplikate anhand der Ereignis-ID, Wiederholungen und Replays werden also nie doppelt gezählt.
• Test-Sites sind eigene Sites. acme-test hat eigene API-Schlüssel und Webhooks. Verbinde die Test-Site zum Üben mit einem Sandbox-Workspace und die Live-Site für den echten Betrieb.
• Lösch den Webhook, wenn du trennst. Trennst du Rekomi, lösch auch den Rekomi-Webhook in Chargebee (Settings > Configure Chargebee > API Keys and Webhooks > Webhooks); Chargebee sendet sonst weiter an die stillgelegte URL, bis du ihn dort entfernst.

Auf deiner Test-Site üben

1. Aktiviere auf deiner Chargebee-Test-Site das Chargebee Test Gateway und lege einen Read-Only-API-Schlüssel an.
2. Lege das benutzerdefinierte Abo-Feld cf_rekomi_ref an (oder plane, meta_data über die API zu nutzen).
3. Verbinde die Test-Site in Rekomi und lege den Webhook in Chargebee mit den Zugangsdaten für Basic Authentication, API version V2 und der Ereignisliste oben an.
4. Öffne einen Hosted Checkout mit subscription[cf_rekomi_ref] auf dem Link-Slug eines freigegebenen Affiliates und bezahle mit einer Testkarte. Die Conversion sollte innerhalb einer Minute im Performance-Tab der Kampagne erscheinen.
5. Spule mit der Time Machine von Chargebee einen Abrechnungszeitraum vor und prüfe, ob die Verlängerungszahlung demselben Affiliate gutgeschrieben wird.
6. Erstatte die Rechnung (erst teilweise, dann vollständig) und prüfe, ob die Provision anteilig zurückgeholt wird.

Fehlerbehebung

Banner „Deine Chargebee-Verbindung ist unterbrochen.“ oder E-Mail zum Neuverbinden. Der gespeicherte API-Schlüssel wird nicht mehr akzeptiert: Er wurde in Chargebee gelöscht oder deaktiviert, oder der Site-Name hat sich geändert. Lege einen neuen Read-Only-Schlüssel an und verbinde unter /dashboard/setup/chargebee neu; dein Tracking-Verlauf bleibt erhalten.

Ereignisse kommen nicht mehr an, aber die Verbindung wirkt gesund. Der Gesundheitscheck prüft den API-Schlüssel, nicht den Webhook. Prüfe, ob der Webhook in Chargebee noch existiert, auf die richtige URL zeigt, API version V2 nutzt und Basic Authentication mit den aktuellen Zugangsdaten eingestellt hat (ein neu erzeugtes Passwort musst du auch in Chargebee aktualisieren). Das Webhook-Dashboard von Chargebee zeigt die Zustellversuche und ihre Antworten.

Zustellungen werden als nicht autorisiert abgelehnt. Die Zugangsdaten für Basic Authentication in Chargebee stimmen nicht. Erzeuge das Passwort auf der Einrichtungsseite neu und füge den neuen Wert in die Webhook-Einstellungen von Chargebee ein.

Zahlungen kommen an, aber kein Affiliate bekommt eine Gutschrift. Das Ereignis hat Rekomi ohne rekomi_ref auf dem Abonnement oder dem Kunden erreicht. Prüfe, ob das Snippet zum Anhängen auf jeder Seite läuft, die zum Checkout verlinkt, ob das Head-Skript gelaufen ist, bevor der Käufer weitergeklickt hat (damit window.Rekomi.getReferral() einen Wert hat), ob der API-Name des benutzerdefinierten Felds genau cf_rekomi_ref lautet (Groß- und Kleinschreibung zählt) und ob über die API angelegte Abonnements meta_data.rekomi_ref setzen.

V1-Ereignisse werden abgelehnt. Rekomi verarbeitet nur API version V2. Stell den Webhook in Chargebee auf V2 um; Chargebee stellt die fehlgeschlagenen Ereignisse erneut zu, und Rekomi erfasst sie.

Verwandte Seiten

• Referenz der S2S-Tracking-API
• Checkout-Tracking ohne Code und ohne Stripe
• Umgang mit Erstattungen