Stripe Integration

Mit der Stripe-Integration werden bezahlte Stripe-Rechnungen automatisch als Buchungen in MILKEE erfasst. Auch Rückerstattungen werden automatisch verbucht. So sparst du dir das manuelle Erfassen deiner Stripe-Umsätze.

Voraussetzungen

• Ein aktives Stripe-Konto
• Zugang zum Stripe Dashboard
• Ein aktives MILKEE Abonnement

Übersicht: Was du benötigst

Für die Stripe-Integration brauchst du zwei Schlüssel aus deinem Stripe Dashboard:

1. Secret Key – Damit kann MILKEE dein Stripe-Konto lesen (Kunden, Produkte, Preise, Steuersätze).
2. Webhook Secret – Damit verifiziert MILKEE, dass eingehende Webhook-Nachrichten wirklich von Stripe stammen.

Benötigte Berechtigungen für den API Key

Wir empfehlen aus Sicherheitsgründen, einen Restricted Key zu erstellen.

Du kannst entweder einen Standard Secret Key verwenden (hat vollen Zugriff) oder einen Restricted Key mit den folgenden Mindestberechtigungen erstellen unter Stripe Dashboard → Developers → API keys → Create restricted key.

Die Rechnungs- und Rückerstattungsdaten kommen über den Webhook rein – der API Key braucht dafür keinen Zugriff auf Invoices oder Charges.

Stripe mit MILKEE verbinden

Schritt 1: Secret Key kopieren

1. Öffne dein Stripe Dashboard → Developers → API keys.
2. Kopiere deinen Secret Key (beginnt mit sk_live_   oder sk_test_  ).

Hinweis: Verwende für den produktiven Betrieb den Live-Key (sk_live_...  ). Den Test-Key (sk_test_...  ) kannst du zum Testen verwenden.

Schritt 2: Stripe in MILKEE aktivieren

1. Gehe in MILKEE zu Integrationen → Integrationen.
2. Klicke bei Stripe auf Aktivieren.
3. Schalte den Stripe-Schalter auf aktiviert.
4. Füge den Secret Key ein.
5. Klicke auf Verbindung testen.
6. Nach erfolgreicher Verbindung klicke auf Stripe verbinden.

Schritt 3: Webhook in Stripe einrichten

Nachdem die Integration erstellt wurde, zeigt MILKEE dir die exakte Webhook URL an. Erstelle nun einen Webhook in Stripe:

1. Öffne dein Stripe Dashboard → Developers → Webhooks.
2. Klicke auf + Add endpoint (bzw. Endpunkt hinzufügen).
3. Kopiere die Webhook URL aus den Stripe-Einstellungen in MILKEE (Klick auf das Kopier-Symbol) und trage sie als Endpoint URL ein.
4. Wähle unter Events to send (bzw. Zu sendende Ereignisse) folgende Events aus:

Tipp: Das wichtigste Event ist invoice.paid  . Die übrigen Events sind optional, aber empfohlen für eine vollständige Synchronisierung.

5. Klicke auf Add endpoint.
6. Auf der Endpoint-Detail-Seite findest du das Signing secret (beginnt mit whsec_  ). Klicke auf Reveal und kopiere es.

Schritt 4: Webhook Secret in MILKEE hinterlegen

1. Gehe zurück zu den Stripe-Einstellungen in MILKEE.
2. Füge das Webhook Secret (whsec_...  ) im Abschnitt Webhook einrichten ein.
3. Klicke auf Webhook Secret speichern.

Schritt 5: Einstellungen konfigurieren

Standard-Bankkonto

Wähle das MILKEE-Bankkonto, auf das Stripe-Zahlungen gebucht werden sollen. Es empfiehlt sich, hierfür ein separates Konto in MILKEE anzulegen (z.B. 1025 Stripe). Dieses Konto wird als Soll-Seite für Einnahmen und als Haben-Seite für Rückerstattungen verwendet.

Einmal-Import für Kund:innen und Prices

Du kannst einen initialen Import von Stripe zu MILKEE durchführen. Dieser erstellt alle Kunden und Prices von Stripe in MILKEE. Die Prices werden hierbei als Produkte erstellt.

Kunden automatisch erstellen

Wenn aktiviert, werden Stripe-Kunden automatisch als MILKEE-Kunden angelegt und bei Änderungen aktualisiert. So musst du Kunden nicht doppelt pflegen.

Kunden zu Stripe synchronisieren

Wenn aktiviert, werden Änderungen an verknüpften Kunden in MILKEE automatisch zu Stripe übertragen (Name, Adresse, E-Mail).

Schritt 6: Verknüpfungen einrichten

Damit MILKEE Stripe-Rechnungen korrekt verbuchen kann, benötigst du Verknüpfungen (Mappings) zwischen deinen Stripe-Entitäten und MILKEE.

Preise → Produkte

Verknüpfe Stripe-Preise (price_...  ) mit MILKEE-Produkten. Wenn eine Rechnung bezahlt wird, bestimmt das verknüpfte Produkt, auf welches Ertragskonto die Buchung gebucht wird (via Ertragskonto auf dem Produkt).

Tipp: Wenn du das Event price.created   aktiviert hast, erstellt MILKEE automatisch ein Produkt für jeden neuen Stripe-Preis. Du musst dann nur noch das richtige Ertragskonto auf dem Produkt hinterlegen.

Kunden

Verknüpfe Stripe-Kunden mit MILKEE-Kunden, um Buchungen automatisch dem richtigen Kunden zuzuordnen. Falls Kunden automatisch erstellen aktiviert ist, geschieht dies automatisch.

Steuersätze

Verknüpfe Stripe-Steuersätze mit MILKEE-Steuersätzen, damit die MwSt. korrekt zugewiesen wird.

Wie funktioniert die Synchronisierung?

Die Stripe-Integration funktioniert über Webhooks – Stripe benachrichtigt MILKEE in Echtzeit, wenn ein relevantes Ereignis eintritt.

Bezahlte Rechnung (invoice.paid  )

1. Stripe sendet das Event an MILKEE.
2. MILKEE prüft die Rechnungspositionen und sucht nach Verknüpfungen (Preis → Produkt → Ertragskonto).
3. Für jede Position wird eine Buchung erstellt:
   • Soll: Standard-Bankkonto
   • Haben: Ertragskonto des verknüpften Produkts
   • MwSt.: Verknüpfter Steuersatz (falls vorhanden)
   • Kunde: Verknüpfter Kunde (falls vorhanden)
4. Bei mehreren Positionen wird eine Sammelbuchung erstellt.

Rückerstattung (charge.refunded  )

1. MILKEE findet die ursprünglichen Buchungen zur Rechnung.
2. Für jede Buchung wird eine Gegenbuchung erstellt (Soll und Haben vertauscht).
3. Bei Teilrückerstattungen werden die Beträge anteilig berechnet.

Welche Daten werden synchronisiert?

Integration entfernen

Falls du die Stripe-Integration nicht mehr benötigst:

1. Gehe zu Automatisierungen → Integrationen → Stripe → Einstellungen.
2. Scrolle nach unten und klicke auf Integration entfernen.
3. Bestätige die Aktion im Dialog.
4. Empfohlen: Deaktiviere oder lösche auch den Webhook-Endpunkt in deinem Stripe Dashboard, damit Stripe keine Nachrichten mehr an MILKEE sendet.

Achtung: Beim Entfernen der Integration gehen alle Verknüpfungen verloren. Bereits erstellte Buchungen bleiben in MILKEE erhalten.

Häufige Fragen

Wo finde ich meinen Secret Key?

Öffne Stripe Dashboard → Developers → API keys. Der Secret Key beginnt mit sk_live_   (produktiv) oder sk_test_   (Test).

Wo finde ich das Webhook Secret?

Öffne Stripe Dashboard → Developers → Webhooks, klicke auf deinen Endpunkt, und dann auf Reveal beim Signing secret. Es beginnt mit whsec_  .

Was passiert, wenn eine Rechnung keine verknüpften Preise hat?

Wenn keine Preiszuordnung gefunden wird, erstellt MILKEE eine einzelne Buchung mit dem Gesamtbetrag auf das Standard-Ertragskonto deiner Firma.

Werden Duplikate verhindert?

Ja. Jede Rechnung und jede Rückerstattung wird mit einer eindeutigen ID gespeichert. Wird dasselbe Event erneut gesendet, wird es ignoriert.

Werden bestehende Rechnungen importiert?

Nein, nur neue Rechnungen, die nach dem Einrichten der Integration bezahlt werden, erzeugen Buchungen. Für bestehende Rechnungen musst du die Buchungen manuell erstellen.

Kann ich Test-Events senden?

Ja. Verwende den Test-Modus in Stripe (mit sk_test_...   Schlüssel und separatem Test-Webhook), um die Integration zu testen, bevor du sie produktiv schaltest.

Was passiert bei einer Teilrückerstattung?

MILKEE berechnet den Rückerstattungsanteil prozentual und erstellt Gegenbuchungen mit den anteiligen Beträgen für jede Originalposition.

Welche Stripe-Events muss ich mindestens aktivieren?

Das wichtigste Event ist invoice.paid  . Alle anderen Events sind optional, ermöglichen aber eine vollständigere Synchronisierung (automatische Kunden, Produkte, Steuersätze, Rückerstattungen).