# Stripe-Integration in Jomblo

## Übersicht

Das Jomblo-Projekt integriert Stripe für sichere Online-Zahlungen. Die Integration umfasst:

- **Checkout-Sessions**: Erstellung von Zahlungssitzungen für den Warenkorb.
- **Express Checkout**: Schnellzahlung mit Apple Pay, Google Pay, PayPal und Klarna.
- **Webhooks**: Automatische Verarbeitung von Zahlungsereignissen (z.B. erfolgreiche Zahlung).
- **Fulfillment**: Nach erfolgreicher Zahlung werden Kunden, Adressen, Bestellungen und Bestellpositionen in der Datenbank erstellt.

Die Integration nutzt die Stripe-Beta-API (`2025-02-24.acacia; custom_checkout_beta=v1`) für benutzerdefinierte Checkout-UI.

## Setup

### Umgebungsvariablen

Erforderliche ENV-Variablen in `.env.local`:

```bash
STRIPE_SECRET_KEY=sk_test_...  # Stripe Secret Key (Test- oder Live-Modus)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...  # Stripe Publishable Key
STRIPE_WEBHOOK_SECRET=whsec_...  # Webhook-Secret für Signatur-Verifizierung
```

### API-Keys

1. Erstelle ein Stripe-Konto unter [stripe.com](https://stripe.com).
2. Hole die API-Keys aus dem Dashboard (Developers > API keys).
3. Erstelle einen Webhook-Endpoint im Dashboard (Developers > Webhooks) mit URL `https://your-domain.com/api/stripe/webhook` und Ereignissen:
   - `checkout.session.completed`
   - `checkout.session.async_payment_succeeded`
   - `checkout.session.expired`

## Checkout-Sessions

Checkout-Sessions werden in `actions/checkout.ts` erstellt. Die Funktion `checkout` validiert den Warenkorb und erstellt eine Stripe-Session mit Preisdaten aus der Datenbank.

### Beispiel-Code

```typescript
const session = await stripe.checkout.sessions.create({
  mode: "payment",
  ui_mode: "custom" as any, // Beta-Feature
  return_url: "http://localhost:3000",
  line_items: [
    {
      price_data: {
        currency: "eur",
        product_data: { name: product.title },
        unit_amount: Math.round(price * 100),
      },
      quantity: item.quantity,
    },
  ],
});
```

Die Session liefert einen `client_secret`, der an den Client gesendet wird.

## Webhooks

Webhooks verarbeiten Stripe-Ereignisse asynchron. Der Endpoint `app/api/stripe/webhook/route.ts` verifiziert die Signatur und ruft `fulfillCheckout` auf.

### Verarbeitete Ereignisse

- `checkout.session.completed`: Zahlung erfolgreich – Bestellung erfüllen.
- `checkout.session.async_payment_succeeded`: Asynchrone Zahlung erfolgreich.
- `checkout.session.expired`: Session abgelaufen (Logging).

### Fulfillment-Prozess

In `actions/fulfill-checkout.ts`:

1. Stripe-Session abrufen mit Line-Items.
2. Kunden aus `customer_details` erstellen/aktualisieren.
3. Rechnungs- und Versandadressen verwalten.
4. Bestellung (`order`) und Positionen (`order_items`) in DB speichern.
5. Status auf "processing" setzen.

## Express Checkout

`components/cart/ExpressCheckout.tsx` implementiert Express Checkout für schnelle Zahlungen.

- Lädt Stripe.js und erstellt `expressCheckoutElement`.
- Unterstützt Apple Pay, Google Pay, PayPal, Klarna.
- Berechnet Gesamtbetrag aus Warenkorb.

## Testing

### Testkarten

Verwende Stripe-Testkarten:

- `4242 4242 4242 4242`: Erfolgreiche Zahlung.
- `4000 0000 0000 9995`: Ablehnung (insufficient_funds).

### Webhook-Testing

Verwende Stripe CLI oder Dashboard, um Webhooks zu simulieren.

### Integrationstests

Tests in `stripe-integration.test.ts` und `fulfill-checkout.test.ts` prüfen Session-Erstellung und Fulfillment.

## Troubleshooting

- **Webhook-Signatur-Fehler**: Überprüfe `STRIPE_WEBHOOK_SECRET`.
- **Session-Erstellung fehlgeschlägt**: Validiere Preisdaten und Produktverfügbarkeit.
- **Fulfillment-Fehler**: Prüfe DB-Verbindungen und Schema-Validierung.
- **Express Checkout nicht sichtbar**: Stelle sicher, dass Stripe.js geladen ist und Publishable Key korrekt ist.

Bei Problemen Logs in der Konsole und Stripe-Dashboard prüfen.