PPartnerDesk

31 — Stripe-Integration

Aktualisiert am 1. Juni 2026

31 — Stripe-Integration

PartnerDesk empfängt Stripe-Webhook-Events und verarbeitet sie als Sales, Refunds oder Subscription-Charges.

Webhook-URL

https://<tenant-slug>.partnerdesk.io/api/webhooks/<tenant-slug>/stripe

Verarbeitete Events

Stripe-Event Aktion in PartnerDesk
checkout.session.completed Neue Transaktion + MLM-Provisionen
invoice.paid Folgezahlung (Recurring) bei Subscriptions; recurringNumber wird aus Stripe-Subscription-Cycle ermittelt
charge.refunded Bestehende Transaktion auf refunded setzen + Clawback-Logik

Andere Stripe-Events werden mit Status skipped quittiert (keine Fehler-Antwort an Stripe).

Setup

1. Webhook bei Stripe einrichten

Stripe-Dashboard → Developers → Webhooks → „Add endpoint":

  • URL: Ihre PartnerDesk-Webhook-URL (siehe oben).
  • Events: Mindestens checkout.session.completed, invoice.paid, charge.refunded.
  • Stripe zeigt nach dem Speichern ein Signing-Secret (whsec_...).

2. Secret in PartnerDesk eintragen

Admin → „Zahlungsanbieter" → Stripe → Webhook-Secret einfügen + Speichern.

3. Test

Im Stripe-Dashboard via „Send test webhook" oder:

stripe trigger checkout.session.completed

Im PartnerDesk-Webhook-Log (siehe 112) erscheint der Eintrag mit Status success.

Affiliate-Identifikation

Stripe selbst kennt keinen „Affiliate"-Begriff. Drei Wege, wie PartnerDesk den Partner zuordnet:

Wenn der Endkunde vorher einen Partner-Link geklickt hat und der Cookie noch gültig ist, findet PartnerResolver ihn automatisch.

B) Via Stripe-Metadata

Bei Anlage der Checkout-Session können Sie metadata.partner_id setzen:

const session = await stripe.checkout.sessions.create({
  ...
  metadata: { partner_id: 'P-12345' }
});

PartnerDesk liest das Feld und ordnet die TX entsprechend zu.

C) Via bestehenden Customer-Match

Wenn der Stripe-Customer schon einmal bei PartnerDesk getrackt wurde (lifetime-assigned), bekommt der Partner alle Folge-Sales automatisch.

Signaturprüfung

Stripe signiert jeden Webhook mit HMAC-SHA256. PartnerDesk validiert:

  1. Header Stripe-Signature lesen.
  2. Timestamp prüfen (max. 5 Min Skew).
  3. HMAC neu berechnen und vergleichen (hash_equals — timing-safe).

Bei ungültiger Signatur: HTTP 401, Event wird als invalid_signature geloggt — Sales werden nicht verarbeitet. Wichtigster Schutz gegen Spoof-Angriffe.

Brutto/Netto/Steuer

Stripe liefert standardmäßig den Brutto-Betrag. PartnerDesk extrahiert:

  • amount_total → Brutto.
  • total_details.amount_tax → Steuer.
  • Differenz → Netto.

Falls Stripe Tax nicht aktiv ist und nur Brutto geliefert wird, nimmt PartnerDesk den Tenant-Default-Steuersatz an (z. B. 19 %) und berechnet das Netto.

CSV-Import historischer Daten

Für Bestandsdaten aus Stripe gibt es einen separaten Import-Befehl:

app:import:provider <tenant> stripe <unified_payments.csv>

Verarbeitet das Standard-Export-Format vom Stripe-Dashboard. Details: …/083-stripe-import-provider-raw.md.

Stripe Connect (für Partner-Auszahlungen)

Stripe Connect ist etwas anderes als der reguläre Stripe-Webhook. Connect bedeutet, dass jeder Partner einen eigenen Stripe-Sub-Account hat, in den PartnerDesk Auszahlungen pusht. Details: 43 — Stripe Connect.

Verwandte Kapitel

Technische Tiefen-Doku: ../001-initial-setup.md, ../018-async-accounting-sync.md (StripeWebhookHandler-Tests)