Skip to content
Hilfecenter-Anleitung · Drittanbieter-Integrationen
5 Min. LesezeitGeprüft 2026-11-16

PayPal-API-Signatur & REST-Anmeldedaten anfordern

PayPal-Zahlungsintegration für den Pass-Verkauf konfigurieren: moderne REST-API-OAuth-Anmeldedaten (Client-ID & Secret) im Vergleich zu klassischen NVP-API-Signaturen.

In dieser Anleitung

Ü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-ModellArchitekturBestandteilePlattformunterstützung & Sicherheit
Moderne PayPal REST API (Erforderlich)OAuth 2.0 Client CredentialsClient ID & Client SecretUnterstützt: Auf Workspace-Ebene sicher verschlüsselt, unterstützt Smart Payment Buttons, Venmo, Pay in 4 und Echtzeit-Webhooks.
Klassische PayPal NVP / SOAP APIKlassische 3-Token-AuthentifizierungAPI-Benutzername, API-Passwort, API-SignaturVeraltet: Direktes Speichern von Zugangsdaten auf Formularebene wird durch rejectLegacySecretWrites in der Passinstance-API blockiert.
SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
PAYPAL-REST-OAUTH-INTEGRATION & PASS-AUSGABE
STUFE 01 PAYPAL DEVELOPER DASHBOARD (HÄNDLER)
1
REST-App unter Apps & Credentials erstellen (Sandbox oder Live)
2
Client ID & Client Secret generieren
STUFE 02 PASSINSTANCE-WORKSPACE-ZAHLUNGSGATEWAY-SCHICHT
Verschlüsselt Zugangsdaten sicher im Mandanten-Vault
Validiert PayPal-API-Handshake über OAuth-2.0-Bearer-Token-Austausch
Bindet PayPal Smart Payment Buttons in PassFlow (PaymentStep) ein
STUFE 03 PAYPAL-WEBHOOK-LISTENER & ECHTZEIT-PASSAUSGABE
Webhook: PAYMENT.CAPTURE.COMPLETED / CHECKOUT.ORDER.APPROVED
Prüft kryptografische Signatur (PAYPAL-TRANSMISSION-SIG)
Löst sofortige Pass-Ausgabe aus & stellt Apple-/Google-Wallet-Buttons bereit

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-Backend rejectLegacySecretWrites. Jeder Versuch, rohe Zahlungsgeheimnisse (payPalApiUsername, payPalApiPassword oder payPalApiSignature) in öffentlichen Formulardefinitionen oder Vorlagen-Metadaten zu speichern, führt sofort zu einer BadRequestException.

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. 1
    Öffnen Sie developer.paypal.com in Ihrem Browser.
  2. 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. 1
    Klicken Sie im linken Navigationsmenü auf Apps & Credentials.
  2. 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. 1
    Klicken Sie auf die Schaltfläche Create App.
  2. 2
    Geben Sie im Feld App Name einen eindeutigen Namen ein (z. B. Passinstance Wallet Payments).
  3. 3
    Stellen Sie App Type auf Merchant.
  4. 4
    Falls Sie mehrere Sandbox-Geschäftskonten besitzen, wählen Sie das gewünschte Testkonto aus.
  5. 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. 1
    Navigieren Sie zu Einstellungen -> Integrationen -> Zahlungen (/settings/integrations/payments).
  2. 2
    Suchen Sie PayPal und klicken Sie auf Verbinden.
  3. 3
    Wählen Sie Ihre Umgebung (Sandbox oder Live).
  4. 4
    Fügen Sie Ihre Client ID und Ihr Client Secret ein.
  5. 5
    Wählen Sie Ihre Standardwährung (z. B. EUR, USD, GBP).
  6. 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):

HTTP
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):

JSON
{
  "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. 1
    Scrollen Sie auf Ihrer PayPal-App-Seite unter Apps & Credentials nach unten zum Abschnitt Webhooks.
  2. 2
    Klicken Sie auf Add Webhook.
  3. 3
    Tragen Sie im Feld Webhook URL den Webhook-Endpunkt Ihres Workspace ein:
TEXT
https://api.passinstance.com/api/v1/payments/webhooks/paypal
  1. 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)

  1. 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 / MeldungUrsacheLösung
INVALID_CLIENTDie 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_FAILUREDas 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_SUPPORTEDDie 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 ausgestelltDer 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.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.