--- title: PayPal description: Verbinden Sie PayPal mit NexCMP für Guthabenaufladungen – REST-App-Anmeldedaten, Webhook, Sandbox-Tests und gespeicherte PayPal-Konten. url: https://nexcmp.com/de/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # PayPal > **Wo im Admin:** Finance › Payment channels › PayPal (`/payments/paypal`). Der Ein-/Ausschalter und die Gebühren befinden sich unter Finance › Payment channels › Fees & limits (`/payments/fees`). ## Funktion {#what-it-does} Ermöglicht Kunden, ihr USD-Guthaben mit ihrem PayPal-Guthaben, Bankkonto oder ihrer bei PayPal hinterlegten Karte aufzuladen. Kunden können NexCMP auch ihr PayPal-Konto für [automatic top-up](https://nexcmp.com/de/docs/billing/auto-top-up/) merken lassen. Verwenden Sie dies zusammen mit [Stripe](https://nexcmp.com/de/docs/billing/stripe/) für Kunden, die PayPal bevorzugen. ## Anforderungen {#requirements} | Komponente | Anforderung | |---|---| | PayPal-Konto | Ein PayPal-**Business**-Konto, das USD empfangen kann. | | REST-App | Eine REST-App im PayPal Developer Dashboard (**Apps & Credentials**), die eine **Client ID** und ein **Client secret** bereitstellt. Verwenden Sie den Tab **Sandbox** zum Testen und **Live** für die Produktion. | | Netzwerk | HTTPS aus dem Internet erreichbar (PayPal ruft den Webhook auf) und ausgehender Zugriff auf `api-m.paypal.com` (Live) oder `api-m.sandbox.paypal.com` (Sandbox), Port 443. | | Berechtigungen | Die REST-App benötigt die Berechtigungen für Rückerstattungen und Webhooks. Der **Check**-Dialog zeigt an, ob beide Scopes vorhanden sind. | | Abhängigkeiten | Keine. | ## Infrastruktur vorbereiten {#prepare-the-infrastructure} 1. Melden Sie sich mit Ihrem Business-Konto bei [developer.paypal.com](https://developer.paypal.com) an und öffnen Sie **Apps & Credentials**. 2. Wählen Sie **Sandbox** (Testen) oder **Live** und klicken Sie dann auf **Create App**. Benennen Sie sie beispielsweise „NexCMP“. 3. Kopieren Sie die **Client ID** und das **Secret** der App. 4. Verwenden Sie zum Testen **Testing Tools › Sandbox Accounts**, um ein *Personal*-Sandbox-Konto (Käufer) zu finden oder zu erstellen. 5. Sie müssen den Webhook nicht selbst erstellen; NexCMP erstellt ihn über die Schaltfläche **Create webhook**. ## In NexCMP verbinden {#connect-in-nexcmp} 1. Öffnen Sie **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. Wählen Sie unter **API keys** die Option **Mode**: `live` (Echtgeld, `api-m.paypal.com`) oder `sandbox` (`api-m.sandbox.paypal.com`). 3. Fügen Sie die **Client ID** (mindestens 20 Zeichen) und das **Client secret** ein. 4. Klicken Sie auf **Check**. Dadurch werden die eingegebenen Anmeldedaten getestet (ein Speichern ist nicht erforderlich), und die Verbindung, die App-ID, der Modus, das Vorhandensein der Scopes für Rückerstattungen und Webhooks sowie die Gültigkeitsdauer des Tokens werden ausgegeben. 5. Klicken Sie auf **Save**. 6. Vergewissern Sie sich in der Karte **Webhook**, dass die URL `https:///v1/billing/paypal/webhook` lautet (sie muss `https` sein), klicken Sie dann auf **Create webhook** und bestätigen Sie den Vorgang. NexCMP fordert PayPal auf, den Webhook mit 11 Ereignissen zu erstellen oder zu aktualisieren, und speichert die zurückgegebene **Webhook ID**. Die Schaltfläche verwendet die **gespeicherten** Schlüssel — speichern Sie diese zuerst, wenn Sie sie gerade bearbeitet haben. 7. Klicken Sie erneut auf **Check**: In der Zeile **Webhook** sollte „exists, 11 events“ stehen. 8. Öffnen Sie **Fees & limits**, schalten Sie **PayPal** ein, setzen Sie **PayPal fee %** (Standard 4.4) und **PayPal fixed fee (cents)** (Standard 30) auf Ihren Tarif und klicken Sie auf **Save channels & fees**. ![PayPal-Seite mit Sandbox-Modus und eingegebenen Zugangsdaten als Beispiel](https://nexcmp.com/de/docs/images/billing/paypal-01-keys.webp) ### Webhook-Ereignisse {#webhook-events} NexCMP registriert diese 11 Ereignisse: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Jeder Webhook wird durch Aufruf der Signaturverifizierungs-API von PayPal überprüft, einmalig gespeichert und idempotent verarbeitet. NexCMP vertraut niemals dem Betrag im Webhook-Body: Bevor eine Erfassung gutgeschrieben wird, ruft das System die Erfassung direkt von PayPal ab. ## Verifizierung {#verify} 1. Belassen Sie **Mode** auf `sandbox`. Öffnen Sie im Portal **Billing › Deposit**, wählen Sie **PayPal**, klicken Sie auf **Continue on PayPal** (oder auf die PayPal-Schaltfläche) und melden Sie sich mit dem Sandbox-Käuferkonto an. 2. Genehmigen Sie die Zahlung. Sie kehren zum Portal zurück, das Guthaben erhöht sich und die Zahlung erscheint unter **Finance › Billing › Top-ups** als *Completed*. 3. Öffnen Sie **Payment channels › Gateway events › PayPal & USDT**: Das Ereignis `PAYMENT.CAPTURE.COMPLETED` wird aufgelistet. 4. Wenn alles funktioniert, schalten Sie **Mode** auf `live` um, geben Sie die Live-Zugangsdaten ein, klicken Sie auf **Save** und anschließend erneut auf **Create webhook** (Sandbox- und Live-Webhooks sind getrennt). ## Limits & Hinweise {#limits-notes} - **Wie eine Zahlung abgeschlossen wird.** Die Bestellung wird in USD erstellt; nachdem der Kunde sie genehmigt hat, erfasst der **Server** den Betrag (idempotente Anforderungs-ID) und schreibt ihn dem Guthaben genau einmal gut. Der Webhook und ein alle 10 Minuten ausgeführtes Abgleichungsjob dienen als Sicherheitsnetz, falls der Kunde den Browser schließt. - **Ausstehende und abgebrochene Bestellungen.** Eine Bestellung kann 12 Stunden lang offen bleiben. Ein Kunde kann maximal 5 ausstehende Bestellungen haben (der Server antwortet mit `too_many_pending`, HTTP 429). Eine Bestellung, die nach 24 Stunden noch nicht erfasst wurde, wird als fehlgeschlagen markiert. - **Kein Webhook konfiguriert.** Das Panel antwortet auf jeden PayPal-Webhook mit HTTP 503, bis eine Webhook ID gespeichert ist. Über das Portal und den 10-Minuten-Abgleich getätigte Erfassungen schreiben dem Guthaben zwar etwas gut, aber alles, was PayPal per Webhook meldet (Streitfälle, Rückbuchungen, verspätete Erfassungen), wird nicht angewendet — klicken Sie auf **Create webhook**. - **Gespeichertes PayPal-Konto.** Wenn sich der Kunde dafür entscheidet, PayPal zu speichern (oder die erste Einzahlung tätigt, wodurch die [automatische Aufladung](https://nexcmp.com/de/docs/billing/auto-top-up/) aktiviert wird), speichert PayPal das Zahlungstoken in seinem Vault. NexCMP speichert lediglich eine Kennung und die PayPal-E-Mail-Adresse. Siehe [Saved payment methods](https://nexcmp.com/de/docs/billing/saved-payment-methods/). - **Rückerstattungen und Streitfälle** werden wie bei Stripe gehandhabt: Rückerstattungsanträge werden unter **Finance › Payouts › Card refunds** genehmigt; ein Streitfall sperrt das Konto des Kunden und stoppt dessen Prepaid-Dienste, bis Sie den Fall klären. - **Gebühren.** Die Gebühr von PayPal wird nicht ausgelesen; der von Ihnen konfigurierte Prozentsatz und die Fixgebühr bestimmen, was der Kunde sieht und was gutgeschrieben wird. Der tatsächliche Tarif hängt von Ihrem Land ab (das Formular gibt als Hinweis 4.4 % für Vietnam und 3.49 % für die USA an). ## Fehlerbehebung {#troubleshooting} | Symptom | Ursache | Behebung | |---|---|---| | "Client ID zu kurz" | Es wurden weniger als 20 Zeichen eingefügt | Kopieren Sie die vollständige Client ID. | | "Webhook URL muss https sein" | URL mit `http://` eingegeben | Verwenden Sie Ihre öffentliche `https://`-Domain. | | Prüfung meldet einen Verbindungsfehler | Falscher Modus (Live-Schlüssel in Sandbox oder umgekehrt), falsches Secret, kein ausgehender Zugriff | Passen Sie **Mode** an den Schlüsseltyp an; testen Sie `curl -I https://api-m.paypal.com` vom Server aus. | | Bereich Refund / Webhooks zeigt "no" | Der REST-App fehlen die Funktionen | Aktivieren Sie die Funktionen für die App im PayPal Developer Dashboard. | | Banner "PayPal-Schlüssel gesetzt, KEIN Webhook" | Webhook-ID fehlt | Klicken Sie auf **Create webhook**. | | "Webhook not found" bei der Prüfung | Der Webhook wurde bei PayPal gelöscht oder gehört zu einer anderen App | Klicken Sie erneut auf **Create webhook**. | | Dem Kunden wird mitgeteilt, dass PayPal die Zahlung abgelehnt hat | PayPal hat diese Zahlungsquelle abgelehnt | Bitten Sie den Kunden, eine andere Zahlungsquelle zu wählen. | | Kunde sieht "Too many pending requests" | 5 offene Bestellungen | Warten Sie, bis sie ablaufen, oder schließen Sie sie ab. | | PayPal-Schaltfläche fehlt | PayPal unter **Fees & limits** deaktiviert oder nicht konfiguriert | Aktivieren Sie es und speichern Sie die Zugangsdaten. |