Überblick: Modernes PayPal REST OAuth vs. klassische NVP-API-Signaturen
Wenn Unternehmen PayPal in Passinstance integrieren, um digitale Pässe, Event-Tickets oder Mitgliedskarten über PassFlow zu monetarisieren, stellt sich häufig die Frage nach einer „PayPal-API-Signatur“.
Im älteren PayPal-Ökosystem verwendete die klassische NVP/SOAP-API (Name-Value Pair) einen dreiteiligen Zugangsdatensatz aus API-Benutzername, API-Passwort und API-Signatur. Moderne E-Commerce-Systeme, mobile Wallet-Anwendungen und Passinstance nutzen jedoch die PayPal REST API v2 auf Basis von OAuth 2.0:
| Zugangsdaten-Modell | Architektur | Bestandteile | Plattformunterstützung & Sicherheit |
|---|---|---|---|
| Moderne PayPal REST API (Erforderlich) | OAuth 2.0 Client Credentials | Client ID & Client Secret | Unterstützt: Auf Workspace-Ebene sicher verschlüsselt, unterstützt Smart Payment Buttons, Venmo, Pay in 4 und Echtzeit-Webhooks. |
| Klassische PayPal NVP / SOAP API | Klassische 3-Token-Authentifizierung | API-Benutzername, API-Passwort, API-Signatur | Veraltet: Direktes Speichern von Zugangsdaten auf Formularebene wird durch rejectLegacySecretWrites in der Passinstance-API blockiert. |
Warum klassische Secret-Schreibvorgänge blockiert werden (rejectLegacySecretWrites)
In älteren Webarchitekturen wurden PayPal-API-Passwörter und -Signaturen gelegentlich direkt in Formularfeld-Definitionen oder Vorlageneinstellungen eingefügt. In Passinstance wird dieses Vorgehen strikt abgelehnt:
Wichtig: In
forms.service.ts(Zeile 1269) erzwingt das Passinstance-BackendrejectLegacySecretWrites. Jeder Versuch, rohe Zahlungsgeheimnisse (payPalApiUsername,payPalApiPasswordoderpayPalApiSignature) in öffentlichen Formulardefinitionen oder Vorlagen-Metadaten zu speichern, führt sofort zu einerBadRequestException.
Zahlungszugangsdaten müssen einmalig auf Workspace-Ebene mittels OAuth-REST-Zugangsdaten (Client ID und Client Secret) eingerichtet werden. Dort werden sie im Mandanten-Vault verschlüsselt gespeichert und vollständig von öffentlich zugänglichen Registrierungsformularen getrennt.
Schritt-für-Schritt-Anleitung: PayPal-REST-Zugangsdaten erstellen
Folgen Sie diesen Schritten, um Ihre PayPal-REST-API-Zugangsdaten im offiziellen PayPal Developer Portal zu erzeugen:
Schritt 1: Im PayPal Developer Portal anmelden
-
1
Öffnen Sie developer.paypal.com in Ihrem Browser.
-
2
Klicken Sie oben rechts auf Log In to Dashboard und melden Sie sich mit Ihrem PayPal-Geschäftskonto an.
Schritt 2: „Apps & Credentials“ öffnen
-
1
Klicken Sie im linken Navigationsmenü auf Apps & Credentials.
-
2
Wählen Sie Ihre Umgebung:
- Sandbox: Verwenden Sie Sandbox-Zugangsdaten, während Sie Ihren PassFlow testen und Vorlagen gestalten. - Live: Verwenden Sie Live-Zugangsdaten, sobald Sie bereit sind, echte Kundenzahlungen entgegenzunehmen.
Schritt 3: Neue REST-API-App erstellen
-
1
Klicken Sie auf die Schaltfläche Create App.
-
2
Geben Sie im Feld App Name einen eindeutigen Namen ein (z. B.
Passinstance Wallet Payments). -
3
Stellen Sie App Type auf Merchant.
-
4
Falls Sie mehrere Sandbox-Geschäftskonten besitzen, wählen Sie das gewünschte Testkonto aus.
-
5
Klicken Sie auf Create App.
Schritt 4: Client ID & Client Secret kopieren
PayPal öffnet die Detailseite Ihrer Anwendung:
-
Kopieren Sie die Zeichenkette unter Client ID.
-
Klicken Sie unter Secret auf Show und kopieren Sie das Client Secret. Bewahren Sie dieses Geheimnis vertraulich auf.
PayPal in Ihrem Passinstance-Workspace konfigurieren
Sobald Sie Ihre REST-Zugangsdaten haben, verbinden Sie PayPal mit Ihrem Workspace:
Über das Dashboard:
-
1
Navigieren Sie zu Einstellungen -> Integrationen -> Zahlungen (
/settings/integrations/payments). -
2
Suchen Sie PayPal und klicken Sie auf Verbinden.
-
3
Wählen Sie Ihre Umgebung (Sandbox oder Live).
-
4
Fügen Sie Ihre Client ID und Ihr Client Secret ein.
-
5
Wählen Sie Ihre Standardwährung (z. B.
EUR,USD,GBP). -
6
Klicken Sie auf Speichern & Verbindung testen. Passinstance führt einen automatisierten OAuth-Handshake durch, um die Zugangsdaten vor der Aktivierung des Gateways zu verifizieren.
Über die REST-API (POST /payments/admin/:customerId/integrations):
POST /api/v1/payments/admin/{customerId}/integrations HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Content-Type: application/json
{
"provider": "PAYPAL",
"clientId": "AWr_7B8c9D0e1F2G3H4I5J6K7L8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2",
"clientSecret": "EPa_1B2c3D4e5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6",
"mode": "live",
"currency": "EUR"
}
Antwort (201 Created):
{
"success": true,
"data": {
"provider": "PAYPAL",
"mode": "live",
"currency": "EUR",
"status": "ACTIVE",
"webhookUrl": "https://api.passinstance.com/api/v1/payments/webhooks/paypal"
},
"description": "PayPal integration configured successfully",
"statusCode": 201
}
PayPal-Webhook für die sofortige Pass-Ausgabe konfigurieren
Damit Pässe unmittelbar nach dem Zahlungseinzug ausgegeben werden, hinterlegen Sie den Webhook-Endpunkt von Passinstance in Ihrem PayPal Developer Portal:
-
1
Scrollen Sie auf Ihrer PayPal-App-Seite unter Apps & Credentials nach unten zum Abschnitt Webhooks.
-
2
Klicken Sie auf Add Webhook.
-
3
Tragen Sie im Feld Webhook URL den Webhook-Endpunkt Ihres Workspace ein:
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
4
Aktivieren Sie unter Event Types die folgenden Ereignisse:
- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)
-
5
Klicken Sie auf Save. Kopieren Sie die erzeugte Webhook ID und fügen Sie sie in Passinstance in Ihren PayPal-Integrationseinstellungen ein.
Autorisiert eine Kundin oder ein Kunde eine Zahlung im PassFlow, benachrichtigt PayPal Passinstance über diesen Webhook. Passinstance verifiziert den kryptografischen Header PAYPAL-TRANSMISSION-SIG, erstellt den Pass-Datensatz und übergibt den Pass direkt an das Wallet der Kundin bzw. des Kunden.
Fehlerbehebung bei häufigen PayPal-Fehlern
| Fehlercode / Meldung | Ursache | Lösung |
|---|---|---|
INVALID_CLIENT | Die Client ID oder das Secret ist fehlerhaft, oder Sandbox-Zugangsdaten wurden im Live-Modus verwendet. | Prüfen Sie, ob die Zugangsdaten vollständig kopiert wurden und der Umgebungsmodus (Sandbox vs. Live) in beiden Systemen übereinstimmt. |
AUTHENTICATION_FAILURE | Das Client Secret wurde in PayPal zurückgesetzt oder enthält führende bzw. nachgestellte Leerzeichen. | Generieren Sie im PayPal Developer Dashboard ein neues Client Secret und speichern Sie es erneut in Passinstance. |
CURRENCY_NOT_SUPPORTED | Die im PassFlow gewählte Währung (z. B. JPY oder BRL) ist in Ihrem PayPal-Händlerkonto nicht aktiviert. | Melden Sie sich im PayPal-Geschäftskonto unter Kontoeinstellungen -> Währungen an und aktivieren Sie die Zielwährung. |
| Pass nach Zahlung nicht ausgestellt | Der PayPal-Webhook fehlt oder wird durch eine Firewall blockiert. | Stellen Sie sicher, dass die Webhook-URL in PayPal zusammen mit dem Ereignis PAYMENT.CAPTURE.COMPLETED gespeichert ist. Prüfen Sie unter Aktivität & Protokolle in Passinstance die Zeitstempel eingehender Webhooks. |
Weiterführende Dokumentation
-
Pässe verkaufen — Vollständige Anleitung zum Einrichten kostenpflichtiger Pässe und Tickets in PassFlow.
-
Abonnements verkaufen — Wiederkehrende Club-Mitgliedschaften mit PayPal Subscriptions verwalten.
-
Zahlungsmethoden — Zahlungsmethoden für die Workspace-Abrechnung verwalten.
