> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Nimm Zahlungen in deinem Macaly-Projekt an

Mit der Stripe-Integration von Macaly nimmst du einmalige und wiederkehrende Zahlungen (Abos) direkt in deinem Projekt an. Eine voll funktionsfähige Testumgebung wird automatisch bereitgestellt, sodass du ohne Stripe-Konto mit dem Bauen und Testen beginnen kannst. Wenn du bereit für den Livebetrieb bist, verbindest du dein Stripe-Konto und wechselst in den Live-Modus.

<Callout icon="user">
  Verfügbar mit den [**Pro- und Agentur-Plänen**](/docs/de/welcome/pricing)
</Callout>

## Zahlungen zu deinem Projekt hinzufügen

Beschreibe dem Agenten im Chat deine Anforderungen an die Zahlungsabwicklung. Zum Beispiel:

```
Ich möchte meine Hautpflegeprodukte online verkaufen. Ich brauche
einen Shop mit Katalog und Checkout, damit Kunden mit Karte zahlen
können.
```

```
Ich habe ein E-Book geschrieben und möchte es für 19 $ verkaufen.
Erstelle eine Seite, auf der Leute dafür bezahlen und es sofort
herunterladen können.
```

```
Ich starte einen monatlichen Online-Yogakurs für 29 $ im Monat. Baue
eine Landingpage, auf der sich Mitglieder anmelden und ihr Abo
starten können.
```

Der Agent erstellt dein Projekt mit einem vollständigen Zahlungsablauf und richtet im Hintergrund eine Stripe-Testumgebung ein.

Um Zahlungen hinzuzufügen, kannst du auch im Tab **Zahlungen** in der oberen Navigationsleiste starten.

Du kannst sofort mit dem Testen beginnen, indem du die im Tab Zahlungen angezeigte Testkarte verwendest:

| Feld | Wert |
| - | - |
| Kartennummer | 4242 4242 4242 4242 |
| Ablaufdatum | Beliebiges zukünftiges Datum (z. B. 01/30) |
| CVC | Beliebige 3-stellige Zahl (z. B. 111) |
| PLZ | Beliebiger Wert (z. B. 11000) |

Navigiere zu deinem Projekt, schließe einen Testkauf ab und prüfe den Checkout-Ablauf.

<Tip>
  Du kannst mit Stripes speziellen Testkarten auch Fehlerszenarien wie abgelehnte Karten oder ungültige Zahlungsdaten testen. Die vollständige Liste der Testkartennummern und der Fehler, die sie simulieren, findest du in [Stripes Testdokumentation](https://docs.stripe.com/testing#declined-payments).
</Tip>

## Deinen sicheren Testbereich aktivieren

Wenn Macaly deine Testumgebung erstellt, richtet es eine Stripe Sandbox ein. Diese Sandbox funktioniert sofort und lässt dich Zahlungen testen, ist aber mit keinem Stripe-Konto verknüpft. Nicht gesicherte Sandboxes laufen nach 60 Tagen ab.

Wenn du die Sandbox sicherst, verknüpfst du sie mit deinem Stripe-Konto. Einmal gesichert, gehört dir die Sandbox dauerhaft, und du kannst sie direkt im Stripe Dashboard verwalten.

Du kannst die Sandbox auf zwei Arten sichern: über den Tab **Zahlungen** in deinem Projekt oder über die E-Mail, die Stripe dir nach der Erstellung der Testumgebung schickt.

Das Sichern ist außerdem der erste Schritt zur Annahme echter Zahlungen. Um live zu gehen, musst du die Sandbox sichern, dein Unternehmen bei Stripe verifizieren lassen und deine Live-API-Schlüssel eintragen.

<iframe src="https://www.youtube.com/embed/SVcTB6UZlIc" />

<Steps>
  <Step title="Tab Zahlungen öffnen">
    Öffne den Tab **Zahlungen** in deinem Projekt. Unter "Aktiviere deinen sicheren Testbereich" siehst du die Schaltfläche **Stripe Sandbox sichern**.
  </Step>

  <Step title="Auf Stripe Sandbox sichern klicken">
    Stripe öffnet sich in einem neuen Tab mit der Seite **Claim your sandbox**.

    Falls du bereits ein Stripe-Konto hast, wähle es aus der Liste aus. Andernfalls klicke auf **+ Create new account**, um kostenlos eins zu erstellen.

    Klicke auf **Continue**, um fortzufahren.
  </Step>

  <Step title="Gib die Daten deines Unternehmens an">
    Stripe fragt dich nach ein paar grundlegenden Informationen:

    1. **Name und Standort des Unternehmens.** Gib den Namen deines Unternehmens ein und wähle dein Land aus. Klicke auf **Continue**.
    2. **Website und Beschreibung des Unternehmens.** Gib die URL deiner Website und eine kurze Beschreibung deiner Produkte oder Dienstleistungen an. Diesen Schritt kannst du mit einem Klick auf **Skip** überspringen.
    3. **Geplante Nutzung von Stripe.** Wähle die für dein Unternehmen relevanten Zahlungsarten aus (z. B. einmalige oder wiederkehrende Zahlungen). Auch dieser Schritt kann übersprungen werden.
  </Step>

  <Step title="Sandbox-Einrichtung abschließen">
    Auf dem letzten Bildschirm zeigt Stripe eine Zusammenfassung der nächsten Schritte: Einrichtung abschließen, in den Live-Modus wechseln und Zahlungen annehmen. Klicke auf **Go to sandbox**, um abzuschließen.
  </Step>

  <Step title="Zurück zu Macaly">
    Navigiere zurück zu Macaly. Der Tab Zahlungen sollte jetzt in Orange **Zahlungen sind im Testmodus** anzeigen und damit bestätigen, dass die Sicherung erfolgreich war.

    <Info>
      Statusaktualisierungen können einen Moment brauchen, um sich zu synchronisieren. Falls die Schaltfläche zum Sichern noch sichtbar ist, lade die Seite neu.
    </Info>
  </Step>
</Steps>

## In den Live-Modus wechseln

Wenn du bereit bist, echte Zahlungen anzunehmen, musst du dein Stripe-Konto aktivieren und deine Live-API-Schlüssel mit Macaly verbinden.

<Warning>
  Du bist für alle rechtlichen und steuerlichen Pflichten im Zusammenhang mit Zahlungen verantwortlich, die du über dein Projekt annimmst. Wende dich bei Unsicherheiten über deine Pflichten an einen Steuerberater.
</Warning>

### Aktiviere dein Stripe-Konto

Bevor du auf die Live-API-Schlüssel zugreifen kannst, verlangt Stripe die Verifizierung deines Unternehmens. Das ist ein standardmäßiger Onboarding-Prozess, der vollständig auf Stripes Seite abläuft.

<Steps>
  <Step title="Stripe Dashboard öffnen">
    Gehe zu [dashboard.stripe.com](https://dashboard.stripe.com) und melde dich mit dem Konto an, mit dem du die Sandbox gesichert hast.
  </Step>

  <Step title="Einrichtungsanleitung abschließen">
    Stripe fordert dich auf, die Einrichtung deines Kontos abzuschließen. Das umfasst normalerweise:

    * Unternehmensdaten (rechtlicher Name, Adresse, Art des Unternehmens)
    * Persönliche Identitätsprüfung
    * Bankkonto oder Auszahlungsdaten für den Empfang von Geldern

    Folge Stripes Einrichtungsanleitung, bis alle Schritte als abgeschlossen markiert sind.
  </Step>

  <Step title="Auf die Verifizierung warten">
    Stripe prüft deine Angaben und aktiviert dein Konto. Das geht meist sofort, kann aber je nach Land und Unternehmensart bis zu ein paar Tage dauern.

    Sobald es verifiziert ist, ist dein Konto live, und deine Live-API-Schlüssel werden im Dashboard verfügbar.
  </Step>
</Steps>

<Info>
  Du kannst dein Projekt im Testmodus weiter bauen und testen, während du auf die Verifizierung deines Kontos durch Stripe wartest.
</Info>

### Trag deine Live-API-Schlüssel ein

Sobald dein Stripe-Konto verifiziert ist, kopiere deine Live-Schlüssel in Macaly.

<Steps>
  <Step title="Kopiere deine Schlüssel aus dem Stripe Dashboard">
    Im Stripe Dashboard werden deine API-Schlüssel in der Karte **API keys** auf der rechten Seite der Startseite angezeigt. Du findest sie auch unter **Developers → API keys** unten in der Seitenleiste.

    Du siehst zwei Schlüssel:

    * **Publishable key** beginnt mit `pk_live_`.
    * **Secret key** beginnt mit `sk_live_`.

    Kopiere beide Schlüssel.

    <Warning>
      Dein geheimer Schlüssel gewährt vollen Zugriff auf dein Stripe-Konto. Teile ihn niemals und füge ihn nicht in den Chat ein.
    </Warning>
  </Step>

  <Step title="Füge deine Schlüssel in Macaly hinzu">
    Klicke im Tab **Zahlungen** auf **Stripe-Verbindung hinzufügen**. Füge jeden Schlüssel in das entsprechende Feld ein und klicke auf **API-Schlüssel speichern**. Achte darauf, dass du deine Live-Schlüssel verwendest (beginnend mit `pk_live_` und `sk_live_`) und nicht die Testschlüssel (`pk_test_` und `sk_test_`).
  </Step>

  <Step title="In den Live-Modus wechseln">
    Klicke auf **In den Live-Modus wechseln**. Macaly konfiguriert dein Projekt neu, um dein Live-Stripe-Konto zu verwenden. Der Status wechselt in Grün zu **Zahlungen sind live**.
  </Step>

  <Step title="Veröffentliche dein Projekt">
    Veröffentliche dein Projekt, um die Änderungen zu übernehmen. Live-Zahlungen werden nur auf der veröffentlichten Website verarbeitet, nicht in der Vorschau.
  </Step>
</Steps>

## Deine Integration verwalten

Alle Zahlungseinstellungen sind über den Tab **Zahlungen** zugänglich:

* **Stripe öffnen** öffnet das Stripe Dashboard, wo du Transaktionen prüfen, Rückerstattungen ausstellen und Auszahlungen verfolgen kannst.
* **In den Live-Modus wechseln / In den Testmodus wechseln** lässt dich jederzeit zwischen den Umgebungen wechseln, ohne den Code deines Projekts zu verändern.
* **Stripe-Verbindung verwalten** lässt dich deine Live-API-Schlüssel nach der Ersteinrichtung aktualisieren.
* **Zahlungen testen** zeigt die Testkartendaten als Referenz an, solange du im Testmodus bist.

## Problembehandlung

<AccordionGroup>
  <Accordion title="Was ist eine Sandbox, und wie unterscheidet sie sich von meinem Stripe-Konto?">
    Eine Sandbox ist eine temporäre Testumgebung, die Macaly für dich erstellt. Sie hat eigene Test-API-Schlüssel und lässt dich Zahlungen simulieren, ohne dass echtes Geld bewegt wird. Sie ist **nicht** dein Stripe-Konto. Wenn du die Sandbox sicherst, verknüpfst du sie mit deinem tatsächlichen Stripe-Konto. Solange du sie nicht sicherst, ist die Sandbox anonym und läuft nach 60 Tagen ab.
  </Accordion>

  <Accordion title="Testzahlungen gehen nicht durch">
    Achte darauf, dass du die Testkartennummer **4242 4242 4242 4242** mit einem beliebigen zukünftigen Ablaufdatum, einem beliebigen 3-stelligen CVC und einer beliebigen Postleitzahl verwendest. Falls das Problem weiterhin besteht, prüfe die Fehlerdetails im Chat oder bitte den Agenten, den Zahlungsablauf zu analysieren.
  </Accordion>

  <Accordion title="Was ist der Unterschied zwischen Testmodus und Live-Modus?">
    Der **Testmodus** nutzt die Sandbox-Umgebung mit Testschlüsseln. Alle Zahlungen sind simuliert, und es ist kein echtes Geld beteiligt. Der **Live-Modus** nutzt dein verifiziertes Stripe-Konto mit Live-Schlüsseln. Es wird echtes Geld abgebucht und auf dein Bankkonto eingezahlt. Du kannst jederzeit im Tab Zahlungen zwischen den Modi wechseln. Der Wechsel des Modus verändert nicht den Code deines Projekts, sondern nur, welche Stripe-Schlüssel aktiv sind.
  </Accordion>

  <Accordion title="Ich finde keine Live-API-Schlüssel in meinem Stripe Dashboard">
    Das Sichern der Sandbox und die Verifizierung deines Stripe-Kontos sind zwei getrennte Schritte. Das Sichern verknüpft die Sandbox mit deinem Konto, aber du musst trotzdem noch Stripes Geschäftsverifizierung abschließen (Identität, Unternehmensdaten, Bankkonto), bevor Live-Schlüssel generiert werden. Öffne das Stripe Dashboard und folge der Einrichtungsanleitung, um die Verifizierung abzuschließen. Wenn du nur Testschlüssel siehst (beginnend mit `pk_test_` und `sk_test_`), ist dein Konto noch nicht vollständig verifiziert.
  </Accordion>

  <Accordion title="Macaly zeigt weiterhin Testmodus, nachdem ich mein Stripe-Konto verifiziert habe">
    Die Verifizierung deines Stripe-Kontos wechselt Macaly nicht automatisch in den Live-Modus. Du musst deine Live-API-Schlüssel manuell im Tab Zahlungen eintragen und dann auf **In den Live-Modus wechseln** klicken. Macaly behält dich im Testmodus, bis du ausdrücklich wechselst.
  </Accordion>

  <Accordion title="Live-Zahlungen gehen nicht durch">
    Prüfe in dieser Reihenfolge drei Dinge:

    1. **Hast du dein Projekt veröffentlicht?** Live-Zahlungen werden nur auf der veröffentlichten Website verarbeitet, nicht in der Vorschau.
    2. **Sind deine Schlüssel korrekt?** Prüfe, ob du den **Publishable key** (beginnend mit `pk_live_`) und den **Secret key** (beginnend mit `sk_live_`) eingetragen hast. Falls du versehentlich Testschlüssel eingefügt hast, klicke auf **Stripe-Verbindung verwalten** und aktualisiere sie.
    3. **Ist dein Stripe-Konto vollständig verifiziert?** Öffne das Stripe Dashboard und prüfe, ob es noch ausstehende Schritte in der Einrichtungsanleitung gibt. Stripe verlangt unter Umständen zusätzliche Dokumente, bevor es Live-Zahlungen verarbeitet.
  </Accordion>

  <Accordion title="Was passiert, wenn meine Sandbox abläuft?">
    Nicht gesicherte Sandboxes laufen nach 60 Tagen ab. Öffne den Tab Zahlungen und klicke auf **Neue Sandbox einrichten**, um eine neue Umgebung bereitzustellen. Dein bestehender Zahlungscode bleibt unverändert. Falls du deine Sandbox bereits gesichert und dein Stripe-Konto verifiziert hattest, musst du deine Live-Schlüssel nach der Einrichtung der neuen Sandbox erneut eintragen.
  </Accordion>
</AccordionGroup>

## Gut zu wissen

* **Es fallen Stripe-Gebühren an.** Macaly berechnet keine zusätzlichen Gebühren für Zahlungen. Für jede Transaktion gelten die üblichen Stripe-Verarbeitungsgebühren (siehe [stripe.com/pricing](https://stripe.com/pricing)).
* **Ablauf der Sandbox.** Nicht gesicherte Testumgebungen laufen nach 60 Tagen ab. Falls das passiert, öffne den Tab Zahlungen und klicke auf **Neue Sandbox einrichten**, um eine neue bereitzustellen.
* **Webhooks werden automatisch verwaltet.** Macaly konfiguriert und pflegt alle Webhook-Endpoints. Im Stripe Dashboard ist keine manuelle Einrichtung nötig.
* **Test- und Live-Umgebungen sind getrennt.** Testtransaktionen erscheinen nicht in deinem Live-Stripe-Konto, und es entstehen keine echten Kosten.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.