diff --git a/PAYPAL-EINRICHTEN.md b/PAYPAL-EINRICHTEN.md new file mode 100644 index 00000000..abbc55a6 --- /dev/null +++ b/PAYPAL-EINRICHTEN.md @@ -0,0 +1,228 @@ +# 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. + +--- + +## 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: + + - [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** (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 + +```bash +ssh dogi@ +sudo -u dogiintern nano /home/dogiintern/dogfather-universe/server-internal/.env +``` + +Diese Zeilen ergänzen bzw. ausfüllen: + +``` +PAYPAL_ENV=live +PAYPAL_CLIENT_ID= +PAYPAL_CLIENT_SECRET= +PAYPAL_WD_WEBHOOK_ID= +PAYPAL_WD_PLAN_BASIS= +``` + +Speichern (`Strg+O`, `Enter`, `Strg+X`), dann: + +```bash +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.