Auf Recurly installieren

Recurly ist eine Abo-Abrechnung, die auf deinem eigenen Zahlungsanbieter aufsetzt, und Rekomi ist direkt damit integriert. Du wählst deine Datenregion (US oder EU), fügst einen privaten Read-Only-API-Schlüssel in Rekomi ein und legst dann in Recurly einen Webhook-Endpunkt an, der auf die Rekomi-URL deines Workspaces zeigt. Ab dann fließen bezahlte Rechnungen, 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 Recurly →.

Eine Sache vorweg: XML-Webhooks von Recurly sind nicht signiert (Recurly prüft Signaturen nur bei JSON-Payloads), 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 Einstellungen des Webhook-Endpunkts in Recurly ein.

Was du brauchst

• Deine Datenregion. Recurly betreibt zwei Regionen: US (v3.recurly.com) und EU (v3.eu.recurly.com). Wähle die, in der deine Site gehostet ist. Du bist nicht sicher? Wähle US: Gehört der Schlüssel zur anderen Region, erkennt Rekomi das beim Verbinden und schlägt den Wechsel vor.
• Einen privaten Read-Only-API-Schlüssel. Öffne in Recurly Integrations > API Credentials, klicke auf Add Private API Key, hake Read-only an und nenne ihn Rekomi. Rekomi prüft damit die Verbindung, führt regelmäßige Gesundheitschecks durch und liest bei der ersten Zahlung jedes Abonnements das benutzerdefinierte Feld rekomi_ref; der Schlüssel wird nie genutzt, um etwas in deiner Site zu ändern. Eine API-Version musst du nicht einrichten: Webhooks konfigurierst du komplett in der Admin-Oberfläche von Recurly.
• Einen Recurly-Plan mit benutzerdefinierten Feldern. Die Attribution von Neukunden läuft über ein benutzerdefiniertes Feld, und benutzerdefinierte Felder gibt es nur mit Recurly Pro (bis zu 5) oder Elite (bis zu 10). Der Starter-Plan von Recurly kennt keine benutzerdefinierten Felder, deshalb ist die Attribution von Neukunden über Links dort nicht verfügbar (die Ausnahme ist der Abgleich über die Lead-E-Mail im Abschnitt zur Attribution). Verlängerungen von Kunden, die Rekomi schon zugeordnet hat, werden in jedem Plan weiter erfasst.

In Rekomi verbinden

Schritt 1. Öffne /dashboard/setup/recurly. 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 Endpunkt in Recurly mit dem neuen Wert aktualisieren).

Schritt 3. Wähle deine Region, füge den Read-Only-API-Schlüssel ein (und optional die Subdomain deiner Site, also acme aus acme.recurly.com, die nur für Support-Links genutzt wird) und klicke auf Recurly verbinden. Rekomi prüft den Schlüssel live gegen deine Region, bevor er angenommen wird. Scheitert der Schlüssel eindeutig an der gewählten Region, funktioniert aber mit der anderen, antwortet Rekomi mit einem Vorschlag für die Region, statt zu verbinden; ändere die Auswahl und verbinde erneut.

Den Webhook in Recurly anlegen

Öffne in Recurly Integrations > Webhooks (in älteren Konten Developers > Webhook), klicke auf Configure und dann auf New Endpoint:

1. Füge die Webhook-URL von der Rekomi-Einrichtungsseite ein.
2. Wähle XML als Format. Rekomi verarbeitet XML-Payloads, und die unten beschriebene Authentifizierung setzt darauf auf.
3. Trag Benutzername und Passwort für Basic Authentication von der Einrichtungsseite in die HTTP-Auth-Felder des Endpunkts ein.
4. Wähle diese Notifications:

• paid_charge_invoice_notification
• new_charge_invoice_notification
• failed_charge_invoice_notification
• successful_refund_notification
• void_payment_notification
• successful_payment_notification
• failed_payment_notification
• new_subscription_notification
• updated_subscription_notification
• renewed_subscription_notification
• canceled_subscription_notification
• expired_subscription_notification
• reactivated_account_notification

Eine Konfiguration mit „select all“ funktioniert auch (Rekomi bestätigt Notification-Typen, die es nicht nutzt, und ignoriert sie), aber mit der expliziten Liste bleibt der Datenverkehr schlank.

Attribution: rekomi_ref auf dem Abonnement mitgeben (Pflicht)

Recurly hostet seine Checkout-Seiten auf der eigenen Domain, deshalb muss die Affiliate-Empfehlung vom Browser des Besuchers in den Abo-Datensatz gelangen. Dieser Schritt ist für die Attribution von Neukunden Pflicht: Ohne ihn kommen bezahlte Rechnungen 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 Recurly brauchst du nicht: Die native Verbindung, die du oben eingerichtet hast, erfasst den Verkauf.

Lege dann das benutzerdefinierte Feld in Recurly an: Öffne Configuration > Custom Fields > Create Custom Field, setze den API-Namen auf rekomi_ref und das Recurly Object auf Subscription. Optional legst du als Fallback ein zweites Feld rekomi_ref auf dem Objekt Account an (Rekomi prüft zuerst das Abonnement, dann das Konto).

Setze das Feld schließlich, wenn du das Abonnement oder den Kauf über die Recurly-API anlegst. Lies die Empfehlung in deinem Frontend mit window.Rekomi.getReferral() aus und schick sie mit der Checkout-Anfrage an dein Backend:

{
  "custom_fields": [
    { "name": "rekomi_ref", "value": "REFERRAL_FROM_YOUR_FRONTEND" }
  ]
}

Dasselbe Array custom_fields funktioniert beim Anlegen von Abonnements, beim Anlegen von Käufen und beim Anlegen oder Aktualisieren von Konten. Recurly unterscheidet bei Feldnamen nicht zwischen Groß- und Kleinschreibung; halte dich trotzdem genau an die Schreibweise rekomi_ref.

Abhängigkeit vom Plan, klar gesagt: Benutzerdefinierte Felder gibt es nur mit Recurly Pro oder Elite. Im Starter-Plan gibt es kein benutzerdefiniertes Feld, das du setzen könntest, deshalb kann Rekomi Neukunden dort nicht über einen Link zuordnen; Verlängerungen von schon zugeordneten Kunden werden weiter anhand deines Kundenverlaufs erfasst.

Abgleich über die Lead-E-Mail (Fallback). Erreicht eine bezahlte Rechnung Rekomi ohne rekomi_ref auf dem Abonnement oder dem Konto und enthält die Notification die E-Mail-Adresse des Kontos, 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. Das ist auch der einzige Weg, wie eine Starter-Site ohne benutzerdefinierte Felder einen Neukunden einem Affiliate zuordnen kann. Das benutzerdefinierte Feld hat immer Vorrang, wenn es vorhanden ist, genauso wie der bisherige Verlauf des Kunden, und ein Affiliate, der mit seiner eigenen E-Mail-Adresse kauft, bekommt keine Gutschrift.

So funktionieren Erstzahlungen und Verlängerungen

Webhooks von Recurly enthalten bei Notifications zu Abonnements, Konten, Zahlungen und Rechnungen nie benutzerdefinierte Felder (die Ausnahme sind Item-Notifications, und die spielen hier keine Rolle). Bei der ersten Zahlung jedes Abonnements macht Rekomi deshalb mit deinem Schlüssel genau einen begrenzten Lesezugriff auf die API, liest rekomi_ref vom Abonnement (ersatzweise vom Konto) und erfasst dann die Conversion. Ist die erste Zahlung eines Abonnements erfasst, lösen seine Verlängerungen nie einen API-Aufruf aus: Sie werden anhand deines Kundenverlaufs zugeordnet. Ist die erste bezahlte Rechnung, die Rekomi zu einem Abonnement überhaupt sieht, zufällig eine Verlängerung, macht auch dieses eine Ereignis die einmalige Abfrage.

Ist die API von Recurly in diesem Moment kurz nicht erreichbar, antwortet Rekomi absichtlich mit einem Fehler auf den Webhook, damit Recurly die Zustellung wiederholt: Recurly stellt mit exponentiell wachsenden Abständen bis zu 10-mal innerhalb von etwa drei Tagen erneut zu, und die Conversion wird bei dem Versuch erfasst, bei dem die API wieder läuft. Für alles Ältere hat jede Notification in deiner Recurly-Konsole einen Button Retry (Aufbewahrung 15 Tage). Auch einen längeren Ausfall kannst du also beheben, indem du die Zustellungen in Recurly erneut abspielst.

Erstattungen und Stornierungen

Erstattungen, die du in Recurly auslöst, kommen pro Erstattungstransaktion als successful_refund_notification an und holen die Provision anteilig zurück: Eine Erstattung von 40% holt 40% der Provision zurück, und mehrere Teilerstattungen holen so lange zurück, bis der ursprüngliche Betrag aufgebraucht ist. Eine stornierte Zahlung (void_payment_notification) holt den vollen Transaktionsbetrag zurück. Credit Notes, die eine Rechnung anpassen, ohne dass Geld fließt, werden registriert, aber nie als Geldbetrag erfasst.

Rückbuchungen

Recurly hat keine Webhooks für Streitfälle. Rückbuchungen bei Kartenzahlungen erreichen Rekomi nur, wenn deine Site die Funktion Chargeback Management von Recurly aus dem Early Access nutzt. Dann kommen sie als Ereignisse in der Form einer Erstattung an und holen die Provision wie eine Erstattung zurück. Späte Fehlschläge bei SEPA-Bankeinzügen kommen mit der Standardbehandlung von Recurly ebenfalls als Erstattungen an. Alles andere (Streitfälle, die direkt bei deinem Zahlungsanbieter geklärt werden) sieht Rekomi nicht; passe diese Fälle manuell an, wenn sie für eine Auszahlung wichtig sind.

Sicherheit

• Jede Webhook-Zustellung wird mit den Zugangsdaten für Basic Authentication authentifiziert, bevor irgendetwas verarbeitet wird. Zustellungen, die die Prüfung nicht bestehen, werden abgelehnt.
• Recurly signiert keine XML-Webhooks. Deshalb erzeugt Rekomi die Zugangsdaten, statt den 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, und alles läuft durchgehend über HTTPS.
• Gib die Webhook-URL und die Zugangsdaten nicht weiter: Behandle sie wie ein Passwort.
• Dein Read-Only-API-Schlüssel und das Webhook-Passwort werden verschlüsselt gespeichert und nie von der API zurückgegeben. Beim Trennen werden beide gelöscht, und die Webhook-URL wird stillgelegt.

Gut zu wissen

• Eine Conversion-Quelle pro Workspace. Recurly Connect schließt Stripe (über die Rekomi-App für Stripe), Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, 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.
• API-Schlüssel von Recurly laufen nicht ab. Meldet der Gesundheitscheck die Verbindung als unterbrochen, wurde der Schlüssel gelöscht oder widerrufen (wird ein Recurly-Nutzer entfernt, werden auch die API-Schlüssel gelöscht, die er erstellt hat), der Webhook-Endpunkt oder seine Zugangsdaten wurden geändert, oder die Region ist falsch eingestellt; ein routinemäßiger Ablauf ist es nie.
• Verspätete Zustellungen sind kein Problem. Recurly wiederholt fehlgeschlagene Webhooks etwa drei Tage lang. Rekomi entfernt doppelte Zustellungen, Wiederholungen und erneut abgespielte Zustellungen aus der Konsole werden also nie doppelt gezählt.
• Sandbox-Sites stellen langsam zu. Webhook-Zustellungen aus einer Recurly-Sandbox können bis zu 48 Stunden verzögert sein, und Recurly kann jeden Endpunkt, auch in der Produktion, nach mehreren aufeinanderfolgenden Tagen mit fehlgeschlagenen Zustellungen automatisch pausieren. Mit dem Button Retry All in der Konsole nimmst du pausierte Endpunkte wieder in Betrieb und stellst das Verpasste erneut zu.
• Sehr alte Sites. Recurly-Sites, die vor Mai 2018 angelegt wurden und die Funktion Credit Invoices nie aktiviert haben, nutzen eine ältere Familie von Rechnungs-Notifications, die Rekomi nicht unterstützt.

Auf einer Sandbox-Site üben

1. Lege eine Recurly-Sandbox-Site an (Region US), aktiviere das Recurly Test Gateway und erstelle einen privaten Read-Only-API-Schlüssel.
2. Lege die benutzerdefinierten Felder rekomi_ref auf Subscription an (und optional auf Account).
3. Verbinde die Sandbox-Site in Rekomi (Region US) und lege in Recurly den XML-Webhook-Endpunkt mit den Zugangsdaten für Basic Authentication und der Notification-Liste oben an.
4. Lege über die API ein Abonnement an, bei dem custom_fields auf den Link-Slug eines freigegebenen Affiliates gesetzt ist, und bezahle mit einer Testkarte. Die Conversion sollte innerhalb einer Minute nach der Webhook-Zustellung im Tab Performance der Kampagne erscheinen.
5. Nutze einen Plan mit täglichem Abrechnungszeitraum, um eine Verlängerung zu beobachten (Recurly hat kein Werkzeug zum Vorspulen der Zeit), und prüfe, ob die Verlängerung demselben Affiliate gutgeschrieben wird.
6. Erstatte die Rechnung (erst teilweise, dann vollständig) und storniere eine Zahlung. Prüfe dabei, ob die Provision erst anteilig und dann vollständig zurückgeholt wird.
7. Nutze in der Konsole den Button Retry bei einem schon zugestellten Ereignis und prüfe, dass nichts doppelt gezählt wird.

Fehlerbehebung

Banner „Deine Recurly-Verbindung ist unterbrochen.“ oder E-Mail zum Neuverbinden. Der gespeicherte API-Schlüssel wird nicht mehr akzeptiert: Er wurde in Recurly gelöscht oder widerrufen (auch durch das Entfernen eines Nutzers), oder die Region passt nicht mehr. Erstelle einen neuen Read-Only-Schlüssel und verbinde unter /dashboard/setup/recurly neu; dein Tracking-Verlauf bleibt erhalten.

„That key works against the other region.“ (der Schlüssel funktioniert mit der anderen Region) Deine Site liegt in der anderen Recurly-Region. Das Verbindungsformular stellt die Region für dich um; prüfe die Auswahl und verbinde erneut. Der gescheiterte Versuch hat nichts verändert.

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 Endpunkt in Recurly noch existiert, auf die richtige URL zeigt, das XML-Format nutzt und Basic Authentication mit den aktuellen Zugangsdaten eingestellt hat (ein neu erzeugtes Passwort musst du auch in Recurly aktualisieren). Die Webhook-Konsole von Recurly zeigt die Zustellversuche und ihre Antworten.

Zustellungen werden als nicht autorisiert abgelehnt. Die Zugangsdaten für Basic Authentication am Endpunkt in Recurly stimmen nicht. Erzeuge das Passwort auf der Einrichtungsseite neu und füge den neuen Wert in die Einstellungen des Endpunkts in Recurly ein.

Zahlungen kommen an, aber kein Affiliate bekommt eine Gutschrift. Die erste Zahlung hat Rekomi erreicht, aber auf dem Abonnement (und dem Konto) stand kein rekomi_ref. Prüfe, ob das benutzerdefinierte Feld mit genau diesem API-Namen auf dem Objekt Subscription existiert, ob deine API-Aufrufe beim Anlegen custom_fields setzen und ob das Tracking-Skript gelaufen ist, bevor der Käufer weitergeklickt hat (damit window.Rekomi.getReferral() einen Wert hatte). Prüfe auch deinen Recurly-Plan: Starter hat keine benutzerdefinierten Felder, für die Attribution von Neukunden brauchst du also Pro oder höher.

Nach einem Ausfall der Recurly-API fehlt eine Conversion. Rekomi lässt den Webhook absichtlich scheitern, damit Recurly ihn erneut zustellt (10 Versuche innerhalb von etwa drei Tagen). Hat der Ausfall länger gedauert als die Wiederholungsstaffel, öffne die Notification in deiner Recurly-Konsole und klicke auf Retry (Aufbewahrung 15 Tage); Rekomi erfasst sie sicher, ohne doppelt zu zählen.

Verwandte Seiten

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