PayPal einrichten

Richten Sie PayPal als Zahlungsanbieter ein, wenn der Checkout PayPal-Zahlungen anbieten soll. Nutzen Sie für Tests zuerst den Sandbox-Modus.

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.

Sandbox in der Admin-Oberfläche eintragen

  1. Öffnen Sie Handel > Richtlinien & Steuern > Zahlungsanbieter.
  2. Aktivieren Sie PayPal.
  3. Wählen Sie Sandbox als Modus.
  4. Tragen Sie die Client-ID aus Ihrer PayPal-Sandbox-App ein.
  5. Tragen Sie das Client Secret aus Ihrer PayPal-Sandbox-App ein.
  6. Tragen Sie die Webhook-ID des PayPal-Webhooks ein.
  7. Speichern Sie die Konfiguration.
  8. 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:

bash
cat > paypal-sandbox.json <<'JSON'
{
  "mode": "sandbox",
  "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:

bash
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:

bash
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:

text
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. Speichern Sie die Konfiguration.
  5. Führen Sie eine kontrollierte Testbestellung mit kleinem Betrag durch.

Fehler eingrenzen

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

  • Ist PayPal aktiv?
  • Steht der Modus auf Sandbox oder Live passend zu den verwendeten Zugangsdaten?
  • Sind Client-ID, Client Secret und Webhook-ID gesetzt?
  • 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?