PayPal einrichten

Richten Sie PayPal als Zahlungsanbieter ein, wenn der Checkout PayPal-Zahlungen anbieten soll. Legen Sie dabei immer fest, ob die Konfiguration für echten Checkout oder für Demo- und Testabläufe gedacht ist.

Voraussetzungen

• Sie haben Zugriff auf den Workspace-Adminbereich.
• Ihre Rolle darf Zahlungsanbieter lesen und ändern.
• Sie haben ein PayPal-Developer-Konto mit einer Sandbox-App.
• Sie haben Client-ID, Client Secret und Webhook-ID der Sandbox-App.

Integrationsart wählen

Wählen Sie in PayPal die Standard-Integration. Workspace nutzt PayPal als Wallet-Zahlart im Checkout und führt Erstellung, Capture und Webhook-Verarbeitung serverseitig aus.

Nutzen Sie die erweiterte PayPal-Integration nur, wenn Sie eigene Kreditkartenfelder direkt im Checkout einbetten wollen. Diese Variante braucht zusätzliche Prüfung, Oberfläche und Sicherheitsfreigaben und gehört nicht zur Standard-Konfiguration.

Modus und Nutzung festlegen

Workspace prüft PayPal-Konfigurationen gegen die Runtime-Stage der Installation. Wenn keine Runtime-Stage konfiguriert ist, behandelt Workspace die Installation konservativ als production.

Wählen Sie in der Admin-Oberfläche zwei Werte:

• Modus: PayPal-Umgebung, also Sandbox oder Live.
• Nutzung: Zweck der Konfiguration, also Live checkout oder Demo/test.

Diese Kombinationen sind erlaubt:

Verwenden Sie Live checkout nur, wenn Kunden echte Zahlungen auslösen sollen. Verwenden Sie Demo/test für Sandbox-Zahlungen, Demoshops, Abnahmetests und Schulungen.

Sandbox in der Admin-Oberfläche eintragen

1. Öffnen Sie Handel > Stammdaten > Zahlung > Zahlungsanbieter.
2. Aktivieren Sie PayPal.
3. Wählen Sie Sandbox als Modus.
4. Wählen Sie Demo/test als Nutzung.
5. Tragen Sie die Client-ID aus Ihrer PayPal-Sandbox-App ein.
6. Tragen Sie das Client Secret aus Ihrer PayPal-Sandbox-App ein.
7. Tragen Sie die Webhook-ID des PayPal-Webhooks ein.
8. Speichern Sie die Konfiguration.
9. Prüfen Sie den Umgebungsstatus. Er muss erlaubt sein; bei Sandbox zeigt Workspace den Testmodus an.
10. Prüfen Sie im Checkout, ob PayPal als Zahlart erscheint.

Workspace speichert PayPal-Zugangsdaten verschlüsselt. Nach dem Speichern zeigt die Oberfläche gespeicherte Secret-Werte nur maskiert an. Lassen Sie Secret-Felder bei späteren Änderungen leer, wenn Workspace den gespeicherten Wert behalten soll.

Per nucli setzen

Workspace stellt derzeit keinen eigenen Komfortbefehl wie nucli payments paypal configure bereit. Nutzen Sie nucli api, wenn Sie die PayPal-Konfiguration reproduzierbar setzen wollen.

Erstellen Sie die Eingabedatei lokal:

cat > paypal-sandbox.json <<'JSON'
{
  "mode": "sandbox",
  "usagePurpose": "demo_test",
  "clientId": "<paypal-sandbox-client-id>",
  "clientSecret": "<paypal-sandbox-client-secret>",
  "webhookId": "<paypal-sandbox-webhook-id>",
  "isActive": true
}
JSON

Senden Sie die Konfiguration an den aktiven Mandanten:

nucli --tenant <tenant> api PUT /api/v1/commerce/config/payment-providers/paypal --input paypal-sandbox.json --summary

Prüfen Sie die gespeicherte Konfiguration mit redigierter Ausgabe:

nucli --tenant <tenant> api GET /api/v1/commerce/config/payment-providers/paypal --redact

Löschen Sie die lokale Eingabedatei oder legen Sie sie in einem geschützten Secret-Store ab. Geben Sie PayPal-Zugangsdaten nicht in Tickets, Chatverläufen oder öffentlichen Dokumenten weiter.

Webhook prüfen

Hinterlegen Sie in PayPal die Webhook-URL Ihrer Workspace-Instanz:

https://<workspace-domain>/api/v1/webhooks/payment/paypal

Wählen Sie nicht All Events. Aktivieren Sie für den Standard-Checkout gezielt:

• CHECKOUT.ORDER.APPROVED
• CHECKOUT.ORDER.COMPLETED
• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.PENDING
• PAYMENT.CAPTURE.REFUNDED
• PAYMENT.CAPTURE.REVERSED

Aktivieren Sie Refund-Events nur, wenn Sie Refunds über PayPal auswerten:

• PAYMENT.REFUND.COMPLETED
• PAYMENT.REFUND.DENIED
• PAYMENT.REFUND.PENDING
• PAYMENT.REFUND.FAILED

Aktivieren Sie Dispute-Events nur, wenn Sie Disputes im Commerce-Prozess nachverfolgen:

• CUSTOMER.DISPUTE.CREATED
• CUSTOMER.DISPUTE.UPDATED
• CUSTOMER.DISPUTE.RESOLVED

Wenn PayPal statt einzelner Events nur Kategorien zeigt, wählen Sie Checkout, Payments & Payouts und bei Bedarf Customer dispute. Wählen Sie auch dann nicht All Events.

Nutzen Sie für Sandbox und Live jeweils die passende PayPal-App und Webhook-ID. Vermischen Sie Sandbox- und Live-Zugangsdaten nicht.

Auf Live wechseln

1. Erstellen oder öffnen Sie die Live-App im PayPal-Developer-Konto.
2. Tragen Sie die Live-Client-ID, das Live-Client Secret und die Live-Webhook-ID ein.
3. Wechseln Sie den Modus auf Live.
4. Wechseln Sie die Nutzung auf Live checkout.
5. Speichern Sie die Konfiguration.
6. Prüfen Sie den Umgebungsstatus. In Produktion muss er erlaubt sein.
7. Führen Sie eine kontrollierte Testbestellung mit kleinem Betrag durch.

Für reproduzierbare Live-Konfigurationen können Sie eine eigene Eingabedatei verwenden:

{
  "mode": "live",
  "usagePurpose": "live_checkout",
  "clientId": "<paypal-live-client-id>",
  "clientSecret": "<paypal-live-client-secret>",
  "webhookId": "<paypal-live-webhook-id>",
  "isActive": true
}

Fehler eingrenzen

Wenn PayPal im Checkout nicht erscheint, prüfen Sie zuerst:

• Ist PayPal aktiv?
• Steht die Nutzung auf Live checkout für echte Zahlungen oder auf Demo/test für Sandbox-Tests?
• Steht der Modus auf Sandbox oder Live passend zu den verwendeten Zugangsdaten?
• Sind Client-ID, Client Secret und Webhook-ID gesetzt?
• Zeigt der Umgebungsstatus eine Blockade?
• Erlaubt der aktuelle Checkout-Kontext PayPal als Zahlart?
• Zeigt nucli --tenant <tenant> api GET /api/v1/commerce/config/payment-providers/paypal --redact den Status active?

Typische Blockaden:

• provider_environment_live_checkout_requires_live: Sie haben Live checkout gewählt, PayPal steht aber auf Sandbox. Wechseln Sie für echte Zahlungen auf Live oder stellen Sie die Nutzung auf Demo/test.
• provider_environment_live_provider_blocked_on_nonproduction: Eine Entwicklungs- oder Staging-Installation soll Live-PayPal nutzen. Verwenden Sie dort Sandbox mit Demo/test.
• provider_environment_demo_test_requires_sandbox: Sie haben Demo/test gewählt, PayPal steht aber auf Live. Wechseln Sie für Demo- und Testabläufe auf Sandbox.