Warum Webhook‑gesteuerte Payout‑Integrationen wichtig sind
Händler, die Partnerprovisionen automatisch auszahlen, reduzieren manuellen Aufwand, vermeiden Fehler und beschleunigen Abrechnungen. Affilentra liefert Payout‑Exporte und Webhooks als Übergabepunkte. In der Praxis ist eine kleine Integrations‑Middleware nötig, die Exportdaten entgegennimmt, an externe Payout‑Provider übergibt (PayPal Payouts, Wise, Stripe Connect), Statusänderungen zurückmeldet und Buchungsbelege generiert. Dieser Beitrag zeigt präzise, welche Konfigurationen und Schritte erforderlich sind.
Kurzüberblick: Architektur und Verantwortlichkeiten
- Affilentra: Erzeugt Payout‑Exports und feuert Webhook‑Events mit den Auszahlungssätzen.
- Middleware (Ihr System oder kleines Connector‑Service): Validiert Webhook, mappt Felder, ruft Provider‑APIs auf, verarbeitet Provider‑Callbacks, erstellt Belege und schreibt Status zurück in Affilentra.
- Payout‑Provider (PayPal, Wise, Stripe Connect): Führt Zahlungen aus und liefert Zahlungsreferenzen / Webhooks für Finalstatus.
Voraussetzungen vor der Integration
- Affilentra‑Installation (self‑hosted) mit aktiviertem Webhook‑System und Exportfunktion. SSL für Webhook‑Endpoint.
- Account und API‑Zugangsdaten bei Ziel‑Providern (Sandbox‑Zugang für Tests).
- Mittelware mit HTTPS‑Endpoint, persistentem Store (DB), und Fähigkeit, Dateien/PDFs zu erzeugen und an Affilentra anzuhängen.
Schritt 1: Payout‑Export in Affilentra sauber definieren
Konfigurieren Sie in Affilentra einen Payout‑Export, der alle nötigen Felder liefert. Empfohlenes Format: JSON oder CSV mit UTF‑8. Wichtige Felder:
- payout_id (eindeutige interne ID)
- partner_id / partner_identifier
- payee_type (email | iban | account_id)
- payee_address (E‑Mail, IBAN, Bankkonto‑ID)
- amount (dezimal, z. B. 123.45)
- currency (ISO‑Code, z. B. EUR)
- gross / net / fee (falls getrennt ausgewiesen werden sollen)
- description / reference
Wichtig: Legen Sie ein Feld für eine externe Referenz (provider_reference) und ein Statusfeld (pending / sent / failed / reconciled) fest — die Middleware füllt diese.
Schritt 2: Webhook in Affilentra konfigurieren
- Erstellen Sie einen Webhook‑Endpoint in Affilentra, der beim Ausführen eines Payout‑Exports ein Event sendet (z. B. payout_exported).
- Sichern Sie das Webhook‑Event mit einer HMAC‑Signatur (Shared Secret). Die Middleware prüft diese Signatur gegen die erhaltenen Payloads.
- Richten Sie Wiederholversuche in Affilentra ein (z. B. 3 Versuche mit exponentiellem Backoff) und dokumentieren Sie Fehlermeldungen in Logs.
Schritt 3: Middleware – Ablauf und Implementierungspunkte
Die Middleware ist das zentrale Element. Kernaufgaben:
- Webhook‑Validierung (Signatur, Schema, Duplikatprüfung).
- Mapping: Konvertieren des Affilentra‑Exports in das Provider‑Payload.
- Provider‑Aufruf: Batches anlegen, Idempotency‑Keys setzen, API‑Fehler behandeln.
- Status‑Management: Provider‑Antworten verarbeiten, Status nach Affilentra zurückmelden.
- Belegerstellung: PDF/CSV/JSON erzeugen, an Payout anhängen und an Buchhaltung weitergeben.
Mapping‑Beispiele (praxisorientiert)
- PayPal: map payee_address → receiver_email, amount + currency → amount, verwenden Sie sender_batch_id = payout_id.
- Wise: falls IBAN vorhanden, legen Sie Recipient an, erstellen Quote (falls Währungsumtausch) und Transfer mit reference = payout_id.
- Stripe Connect: für verbundene Accounts nutzen Sie destination‑Parameter oder senden Payouts in Namen des Connected Account; führen Sie ggf. zuerst eine Transfer durch.
Provider‑Spezifika & Tipps
- PayPal Payouts: Nutzen Sie Batch‑Payouts für Effizienz; legen Sie sender_batch_id zur Idempotenz fest; speichern Sie payout_item_id und batch_status für spätere Reconciliation.
- Wise: Erstellen Sie Empfänger (recipient) einmal und wiederverwenden Sie die recipient_id; beachten Sie mögliche Quote‑Step bei Währungsumtausch.
- Stripe Connect: Prüfen Sie, ob Ihr Flow Transfers an verbundene Accounts oder externe Bankkonten verwenden soll; nutzen Sie Idempotency‑Keys und listen Sie balance_transfers.
Statusrückmeldung an Affilentra und Reconciliation
So stellen Sie verlässliche Buchungsläufe sicher:
- Sofort nach Provider‑Antwort: Aktualisieren Sie Affilentra‑Payouts mit provider_reference, status = sent (oder failed) und fee‑Informationen.
- Implementieren Sie einen Listener für Provider‑Webhooks (z. B. PayPal/Stripe Webhooks). Bei Eingang eines finalen Status (SUCCESS/FAILED/COMPLETED) aktualisiert die Middleware den Status in Affilentra.
- Führen Sie regelmäßige Reconciliations: Abgleich von Affilentra‑Export, Provider‑Berichten und Bankauszügen; differenzen protokollieren und alarmieren.
Buchhaltungsbelege automatisiert erzeugen
Automatisierte Belege sind Voraussetzung für revisionssichere Buchhaltung. Vorgehen:
- Erzeugen Sie pro Auszahlung ein PDF‑Beleg mit folgenden Angaben: payout_id, partner_id, Name/Adresse des Partners, Brutto/Netto/Fees, Währung, Zahlungsreferenz des Providers, Timestamp.
- Hängen Sie zusätzlich die Provider‑Receipt (API‑Download von PayPal/Stripe/Wise) als Anhang an das Payout in Affilentra an oder speichern Sie sie im Buchhaltungssystem.
- Exportformate: CSV für Massenimporte, PDF für einzelne Buchungsbelege, ggf. XML/DATEV‑kompatibel je nach Zielbuchhaltung.
Fehlerbehandlung, Idempotenz und Betrieb
- Idempotency: Verwenden Sie beim Provider eindeutige Keys (z. B. payout_id als sender_batch_id), um doppelte Zahlungen zu vermeiden.
- Retries: Implementieren Sie Backoff‑Strategien bei temporären Fehlern und eine manuelle Review‑Queue bei Persistenzfehlern.
- Monitoring & Alerting: Loggen Sie Webhook‑Payloads, Provider‑Antworten und Reconciliation‑Diffs; konfigurieren Sie Alerts bei Abweichungen.
- Sandbox‑Tests: Führen Sie Integrationsläufe im Sandbox‑Modus aller drei Provider durch, bevor Sie Produktivläufe starten.
Praxisfall: Ablauf einer Auszahlung (Kurzbeschreibung)
1) Affilentra erzeugt einen Payout‑Export und feuert payout_exported an Ihre Middleware. 2) Middleware validiert, mappt Felder und ruft Provider‑API auf. 3) Provider bestätigt mit Referenz → Middleware aktualisiert Affilentra mit status=sent und provider_reference. 4) Provider liefert finalen Webhook (z. B. completed) → Middleware setzt status=reconciled, zieht Gebühren und erstellt PDF‑Beleg, der an Affilentra angehängt wird.
Fazit und nächster Schritt
Die technische Integration von Affilentra‑Payouts mit PayPal, Wise und Stripe Connect über Webhooks ist ein klar strukturierter Prozess: sauberer Export, sichere Webhook‑Übergabe, Middleware mit Provider‑Mapping, zuverlässige Statusrückmeldung und automatische Belegerzeugung. So behalten Händler Kontrolle über Konditionen und Nachvollziehbarkeit, während Partner transparente Auszahlungshistorien erhalten.
Handeln Sie jetzt: Einstieg wählen: Besprechen Sie Ihre Anforderungen und Testumgebung mit dem Affilentra‑Team und starten Sie die Integration. Mehr Informationen und Kontakt: https://affilentra.de
Nächster Schritt
Affilentra selbst ausprobieren
Einheitliche Plattform, die Produktbereitstellung, Tracking, Conversion-Validierung, Provisionsberechnung und Auszahlung entlang klar getrennter Rollen transparent zusammenführt; Option zur self-hosted Installation mit Dauerlizenz ohne Umsatzbeteiligung; Händler behalten Kontrolle über Produkte, Konditionen und Werbemittel; Partner erhalten persönliche Trackinglinks und nachvollziehbare Auszahlungshistorie.