dogfather-universe/PAYPAL-EINRICHTEN.md

# PayPal für den Webdesign-Bereich einrichten

Das ist der einzige Schritt, den ich nicht selbst machen kann: PayPal
lässt Zugangsdaten nur über dein eingeloggtes Konto erzeugen.

Alles andere steht bereits — Bestellungen, Einzug, Webhook mit
Signaturprüfung, Schutz gegen Doppelverbuchung, die gesetzlich nötige
Zustimmung vor der Anzahlung. Sobald die vier Werte eingetragen sind,
funktionieren die Bezahlknöpfe.

**Zeitbedarf:** etwa 20 Minuten. **Kosten:** keine — ein
PayPal-Geschäftskonto ist kostenlos, Gebühren fallen nur pro Zahlung an.

---

## Schritt 0 — Zuerst nachsehen, was schon da ist

**Du hast wahrscheinlich schon die Hälfte.** Das DogiCrew-Supporter-Abo
läuft über dasselbe PayPal-Konto und benutzt dieselbe Client ID und
dasselbe Secret. Wenn das Abo live funktioniert, sind sie bereits da.

So siehst du es — ohne Konsole:

1. Verwaltung öffnen: `https://dogfather-universe.com/webdesign/verwaltung.html`
2. Reiter **Zahlungen**

Oben steht der Stand, bei jedem Feld eine Marke:

| Was dort steht | Bedeutung |
|---|---|
| *hinterlegt (auf dem Server)* | kommt aus der `.env`, du musst nichts tun |
| *hinterlegt* | schon über dieses Formular eingetragen |
| *fehlt* | musst du eintragen |

Steht bei **Client ID** und **Secret** schon *hinterlegt*, brauchst du
nur **Schritt 4** (Webhook) und danach Schritt 6.

> Warum das wichtig ist: Wenn du eine **zweite** App anlegst, obwohl
> schon eine läuft, hast du zwei Sätze Zugangsdaten für dasselbe Konto.
> Das funktioniert zwar, macht aber später jede Fehlersuche doppelt so
> mühsam — und beim Erneuern eines Secrets bricht womöglich das
> DogiCrew-Abo weg.

---

## Bevor du anfängst

Du brauchst ein **PayPal-Geschäftskonto** (kein privates). Falls du noch
keins hast: Auf paypal.com anmelden → *Einstellungen* → *Kontoart
ändern* → auf Geschäftskonto umstellen. Das geht mit demselben Konto und
kostet nichts.

> **Wichtig:** Das Geld landet direkt auf **deinem** PayPal-Konto. Es
> geht zu keinem Zeitpunkt über einen Vermittler oder über mich.

---

## Schritt 1 — Bei den Entwickler-Einstellungen anmelden

1. Gehe auf **https://developer.paypal.com**
2. Oben rechts auf **Log in to Dashboard**
3. Melde dich mit deinen ganz normalen PayPal-Zugangsdaten an
   (denselben wie auf paypal.com)

Du landest im *Developer Dashboard*.

---

## Schritt 2 — Auf „Live" umschalten

Oben auf der Seite gibt es einen Schalter mit zwei Stellungen:

```
   Sandbox   |   Live
```

**Stelle ihn auf „Live".**

> Sandbox ist die Spielwiese mit Testgeld. Solange der Schalter dort
> steht, erzeugst du Zugangsdaten, mit denen **kein echtes Geld** fliesst.
> Das ist der häufigste Fehler bei dieser Einrichtung.

---

## Schritt 3 — App anlegen

1. Klicke links auf **Apps & Credentials**
2. Klicke auf **Create App**
3. **App Name:** `Dogfather Webdesign`
4. **Type:** `Merchant` (falls gefragt)
5. Klicke **Create App**

Du siehst jetzt zwei Werte:

| Feld | Was du siehst |
|---|---|
| **Client ID** | eine lange Zeichenkette, sofort sichtbar |
| **Secret** | daneben ein Link **Show** — draufklicken |

**Beide brauchst du gleich.** Kopier sie irgendwohin, wo du sie
wiederfindest — am besten direkt nach Bitwarden.

> **Das Secret ist wie ein Passwort.** Schick es mir **nicht** im Chat —
> dort stuende es dauerhaft im Verlauf, und eintragen koennte ich es
> trotzdem nicht. In Schritt 6 fuegst du es selbst ein.

---

## Schritt 4 — Webhook einrichten

Der Webhook ist die Leitung, über die PayPal uns meldet: *„Die Zahlung
ist durch."* Ohne ihn würde eine Zahlung nicht als bezahlt erscheinen,
wenn der Kunde das Fenster zu früh schliesst.

1. Auf derselben App-Seite nach unten scrollen zu **Webhooks**
2. Klicke **Add Webhook**
3. **Webhook URL** — genau das hier eintragen:

```
https://postfach.dogfather-universe.com/webdesign/paypal-webhook
```

4. Bei **Event types** wähle **diese vier** aus:

   - [x] `Payment capture completed`
   - [x] `Payment capture denied`
   - [x] `Payment capture refunded`
   - [x] `Billing subscription cancelled`

   > Nicht „Select all" anklicken. Jedes zusätzliche Ereignis erzeugt
   > Meldungen, die niemand auswertet — das macht die Suche nach einem
   > echten Problem später unnötig schwer.

5. **Save**
6. Danach erscheint in der Liste eine **Webhook ID**. Die brauchst du
   für Schritt 6.

> **Achtung, hier stand vorher etwas Falsches:** Die Webhook-ID beginnt
> **nicht** mit `WH-`. Sie sieht aus wie `0NH55953DH663215D` — rund
> 17 Zeichen, Buchstaben und Ziffern gemischt, ohne Vorsilbe.
>
> Das `WH-` steht auf den **Ereignis**-Kennungen, also den einzelnen
> Meldungen, die PayPal später schickt (`WH-3F562076HD293871E-…`). Die
> braucht man hier nicht.

---

## Schritt 5 — Nur falls du die monatliche Betreuung anbieten willst

Für einmalige Zahlungen — Anzahlung, Restbetrag, Zusatzleistungen — bist
du hier fertig. **Überspring diesen Schritt, wenn du kein monatliches
Abo verkaufst.** Du kannst ihn jederzeit nachholen.

> **Wichtig:** Abo-Pläne legst du **nicht** im Entwicklerbereich an,
> sondern in deinem normalen PayPal-Geschäftskonto. Deshalb findest du
> sie unter developer.paypal.com nicht.

1. Gehe auf **https://www.paypal.com/billing/plans**
   (oder: paypal.com anmelden → Menü **Zahlungen** bzw.
   **Bezahlen & bezahlt werden** → **Abonnements**)
2. **Plan erstellen** / *Create Plan*
3. Produkt anlegen: Name `Dogfather Betreuung`, Art **Dienstleistung**
4. Preis und Rhythmus: **monatlich**, dein Betreuungspreis
5. Speichern, dann **Plan aktivieren** (*Turn on plan*) — ohne das
   ist er nicht nutzbar
6. Die **Plan-ID** notieren. Sie beginnt mit `P-`

---

## Schritt 6 — Werte in der Verwaltung eintragen

**Kein SSH, kein Texteditor, kein Neustart.**

1. Verwaltung öffnen: `https://dogfather-universe.com/webdesign/verwaltung.html`
2. Reiter **Zahlungen**
3. Die Felder ausfüllen:

| Feld | Woher |
|---|---|
| **Betriebsart** | *Echtbetrieb* anklicken |
| **Client ID** | aus Schritt 4 |
| **Secret** | aus Schritt 4 |
| **Webhook-Kennung** | aus Schritt 5 |
| **Plan für die Betreuung** | aus Schritt 5b — sonst leer lassen |

4. **Speichern**

> **Ein leeres Feld bedeutet „nicht anfassen", nicht „löschen".** Du
> kannst also einzeln nachtragen, ohne den Rest zu verlieren. Steht bei
> einem Feld schon *„hinterlegt (auf dem Server)"*, kommt der Wert aus
> der `.env` und du brauchst dort nichts einzugeben.

Die Werte werden verschlüsselt gespeichert und wirken sofort. Nach dem
Speichern leeren sich die Felder von selbst — ein Secret soll nicht
stehen bleiben, wenn jemand anders auf den Bildschirm schaut.

**Angezeigt wird ein gespeicherter Wert nie wieder.** Nur: *hinterlegt ·
80 Zeichen*. Wer ihn verliert, erzeugt bei PayPal einen neuen — das ist
sicherer, als ihn dauerhaft abrufbar zu halten.

---

## Schritt 7 — Verbindung testen

Gleich daneben steht der Knopf **Verbindung testen**. Draufklicken.

| Meldung | Bedeutung |
|---|---|
| „Anmeldung bei PayPal erfolgreich — Echtbetrieb." | Alles richtig, weiter zu Schritt 8 |
| „…aber im TESTMODUS" | Betriebsart auf *Echtbetrieb* stellen |
| „PayPal hat die Anmeldung abgelehnt" | Client ID und Secret stammen aus verschiedenen Apps oder aus dem Testbereich — beide aus **derselben** App neu kopieren |

> Der Test meldet sich probeweise bei PayPal an. **Es fließt kein Geld.**
> Aber erst er beweist, dass die Werte stimmen — *„hinterlegt"* heißt
> nur, dass etwas dasteht, nicht dass es richtig ist.

---

## Schritt 8 — Der erste echte Test mit 1 Euro

**Das ist der wichtigste Schritt.** Mach ihn, bevor ein echter Kunde
zahlt.

1. Verwaltung → Reiter **Kunden** → Testkunde anlegen (deine eigene
   E-Mail genügt)
2. Dazu ein Projekt mit Preis **1,00 €**
3. Im Projekt eine Zahlung erzeugen
4. Den Einladungslink im eigenen Browser öffnen, Passwort setzen,
   ins Portal gehen und bezahlen — mit VanVans PayPal oder per Karte
   als Gast
5. Prüfen: Kommt das Geld auf deinem Konto an? Steht die Zahlung in der
   Verwaltung auf **„bezahlt"**?
6. In PayPal wieder **erstatten**
7. Testkunde und Testprojekt löschen

> Der Testmodus verhält sich in Kleinigkeiten anders als der Echtbetrieb.
> Ein Durchlauf mit einem echten Euro ist der einzige Nachweis, der
> wirklich zählt — und er kostet dich nichts, weil du ihn zurückholst.

---

## Was passiert, wenn ein Kunde zahlt

1. Kunde klickt im Portal auf **Jetzt bezahlen**
2. Bei der **Anzahlung** muss er zuerst bestätigen, dass sofort begonnen
   werden darf und er dadurch sein Widerrufsrecht verliert
   (§ 356 Abs. 4 BGB — der genaue Wortlaut wird mit Zeitstempel
   gespeichert, weil im Streit du beweisen musst, dass er zugestimmt hat)
3. Er wird zu PayPal geleitet und bezahlt
4. **Das Geld geht sofort auf dein Konto** — es gibt keine Zwischenstufe
5. Die Zahlung erscheint als „bezahlt", das Projekt vermerkt Anzahlung
   bzw. Restbetrag als eingegangen

Schliesst der Kunde das Fenster zu früh, meldet der Webhook die Zahlung
trotzdem. Kommt dieselbe Meldung doppelt — was bei PayPal normal ist —
wird sie nur einmal verbucht.

---

## Wenn etwas nicht klappt

| Anzeichen | Ursache | Abhilfe |
|---|---|---|
| „noch nicht freigeschaltet" | Werte fehlen | Verwaltung → Zahlungen, dort steht welcher |
| Zahlung bleibt auf „freigegeben" | Webhook-Adresse falsch | Schritt 4 prüfen — die Adresse muss exakt stimmen |
| Kein echtes Geld | Schalter stand auf Sandbox | Schritt 2, dann neue Zugangsdaten erzeugen |
| PayPal meldet „invalid client" | Client ID und Secret aus verschiedenen Apps | beide aus derselben App neu kopieren |

---

## Zwei Dinge, die dauerhaft gelten

**Das Secret ist ein Passwort.** Es gehört nach Bitwarden, nicht in eine
Notiz, nicht in eine Nachricht, nicht ins Git. Wenn es je irgendwo
auftaucht, wo es nicht hingehört: in der App **Manage Credentials → new
secret** erzeugen und das alte löschen.

**Prüfe nach dem Umstellen auf Live einmal deinen Kontoauszug.** Nicht
weil zu erwarten wäre, dass etwas schiefgeht — sondern weil der Moment,
in dem zum ersten Mal echtes Geld fliessen kann, der richtige ist, um
einmal genau hinzusehen.