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 dieselben zwei Werte (PAYPAL_CLIENT_ID und PAYPAL_CLIENT_SECRET). Wenn das Abo live funktioniert, sind sie bereits eingetragen.

Prüf es mit diesem Befehl. Er zeigt nur ob ein Wert da ist, nie den Wert selbst:

ssh dogi@<dein-server>
sudo -u dogiintern grep -cE '^PAYPAL_CLIENT_ID=.+' \
  /home/dogiintern/dogfather-universe/server-internal/.env
sudo -u dogiintern grep -cE '^PAYPAL_CLIENT_SECRET=.+' \
  /home/dogiintern/dogfather-universe/server-internal/.env
sudo -u dogiintern grep -E '^PAYPAL_ENV=' \
  /home/dogiintern/dogfather-universe/server-internal/.env

Ergebnis	Bedeutung
beide 1, PAYPAL_ENV=live	Du brauchst nur Schritt 4 (Webhook). Springe direkt dorthin.
beide 1, PAYPAL_ENV=sandbox	Zugangsdaten sind Testdaten. Schritt 2–4 nötig.
0	Noch nichts da. Alle Schritte durchgehen.

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 der andere Bereich 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 brauche ich. Kopiere sie zunächst irgendwohin, wo du sie gleich wiederfindest.

Das Secret ist wie ein Passwort. Schick es mir nicht im Chat. Wie du es sicher hinterlegst, steht in Schritt 6.

---

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:

   • Payment capture completed
   • Payment capture denied
   • Payment capture refunded
   • 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 (beginnt meist mit WH-). Die brauche ich auch.

---

Schritt 5 — Nur falls du die monatliche Betreuung anbieten willst

Für einmalige Zahlungen (Anzahlung, Restbetrag, Zusatzleistungen) bist du hier fertig. Das monatliche Betreuungs-Abo braucht zusätzlich einen Plan:

1. Links auf Products & Plans (oder direkt unter Subscriptions)
2. Create Product → Name Dogfather Betreuung, Type Service
3. Dann Create Plan → monatlich, Preis eintragen
4. Die Plan ID (beginnt mit P-) notieren

Das kannst du auch später nachholen — die Einmalzahlungen laufen ohne.

---

Schritt 6 — Werte sicher hinterlegen

Die Zugangsdaten gehören in eine Datei auf dem Server, nicht in den Chat und nicht ins Git.

Du hast zwei Möglichkeiten:

Möglichkeit A — du trägst sie selbst ein

ssh dogi@<server>
sudo -u dogiintern nano /home/dogiintern/dogfather-universe/server-internal/.env

Diese Zeilen ergänzen bzw. ausfüllen:

PAYPAL_ENV=live
PAYPAL_CLIENT_ID=<Client ID aus Schritt 3>
PAYPAL_CLIENT_SECRET=<Secret aus Schritt 3>
PAYPAL_WD_WEBHOOK_ID=<Webhook ID aus Schritt 4>
PAYPAL_WD_PLAN_BASIS=<Plan ID aus Schritt 5, sonst leer lassen>

Speichern (Strg+O, Enter, Strg+X), dann:

sudo systemctl restart dogiintern.service

Möglichkeit B — über Bitwarden

Leg die vier Werte in Bitwarden ab und sag mir Bescheid. Ich sage dir dann, welche Zeile wohin gehört — die Werte selbst brauche ich nicht zu sehen.

---

Schritt 7 — Prüfen, ob es angekommen ist

Melde dich in der Verwaltung an und öffne den Bereich Zahlungen. Oben steht der Einrichtungsstand:

• „PayPal ist eingerichtet" → fertig
• „Es fehlt noch: …" → dort steht, welcher Wert leer ist

---

Schritt 8 — Der erste echte Test

Mach die erste Zahlung mit einem kleinen Betrag an dich selbst.

1. Leg in der Verwaltung ein Testprojekt mit 1,00 € Preis an
2. Erzeuge dazu eine Zahlung
3. Bezahle sie im Portal mit einem anderen PayPal-Konto (z. B. dem von VanVan) oder mit Karte als Gast
4. Prüfe: Kommt das Geld an? Steht die Zahlung auf „bezahlt"?
5. Erstatte den Betrag in PayPal wieder zurück

Ein Testlauf mit echtem Geld ist der einzige Weg, der wirklich etwas beweist. Die Sandbox verhält sich in Kleinigkeiten anders — und diese Kleinigkeiten fallen sonst beim ersten echten Kunden auf.

---

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 oder Dienst nicht neu gestartet	Schritt 6 wiederholen, Dienst neu starten
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.