Overzicht: moderne PayPal REST OAuth versus verouderde NVP API-handtekeningen
Wanneer bedrijven PayPal aan Passinstance koppelen om digitale passen, evenementtickets of lidmaatschapskaarten te verkopen via PassFlow, vragen zij vaak hoe zij een "PayPal API-handtekening" (PayPal API Signature) kunnen aanvragen.
In het oudere PayPal-ecosysteem gebruikte de klassieke NVP/SOAP (Name-Value Pair) API een driedelige set inloggegevens bestaande uit een API Username, API Password en API Signature. Moderne e-commercesystemen, mobiele wallet-applicaties en Passinstance maken echter gebruik van de PayPal REST API v2 op basis van OAuth 2.0:
| Inlogmodel | Architectuur | Onderdelen | Platformondersteuning & beveiliging |
|---|---|---|---|
| Moderne PayPal REST API (vereist) | OAuth 2.0 Client Credentials | Client ID & Client Secret | Ondersteund: Veilig getokeniseerd op werkruimteniveau; ondersteunt Smart Payment Buttons, Venmo, Pay in 4 en realtime webhooks. |
| Verouderde PayPal NVP / SOAP API | Klassieke 3-tokenauthenticatie | API Username, API Password, API Signature | Verouderd: Rechtstreeks opslaan van inloggegevens op formulierniveau wordt geblokkeerd via rejectLegacySecretWrites in de Passinstance API. |
Waarom opslag van verouderde geheimen wordt geblokkeerd (rejectLegacySecretWrites)
In oudere webarchitecturen plakten ontwikkelaars soms PayPal API-wachtwoorden en -handtekeningen rechtstreeks in formulierdefinities of sjablooninstellingen. In Passinstance wordt dit strikt geweigerd:
Belangrijk: In
forms.service.ts(regel 1269) handhaaft de Passinstance-backendrejectLegacySecretWrites. Elke poging om ruwe betaalgeheimen (payPalApiUsername,payPalApiPasswordofpayPalApiSignature) op te slaan in openbare formulierdefinities of sjabloonmetadata resulteert onmiddellijk in eenBadRequestException.
Betaalinloggegevens moeten eenmalig op werkruimteniveau worden geconfigureerd met OAuth REST-inloggegevens (Client ID en Client Secret), waarbij ze versleuteld worden opgeslagen in de tenantkluis en volledig losstaan van openbare registratieformulieren.
Stapsgewijze handleiding: PayPal REST-inloggegevens aanvragen
Volg deze stappen om uw PayPal REST API-inloggegevens te genereren via de officiële PayPal Developer Portal:
Stap 1: Log in op de PayPal Developer Portal
-
1
Open developer.paypal.com in uw browser.
-
2
Klik rechtsboven op Log In to Dashboard en meld u aan met uw PayPal Business-account.
Stap 2: Open "Apps & Credentials"
-
1
Klik in het linker navigatiemenu op Apps & Credentials.
-
2
Selecteer uw omgeving:
- Sandbox: Gebruik Sandbox-inloggegevens tijdens het testen van uw pasflow en het ontwerpen van sjablonen. - Live: Gebruik Live-inloggegevens zodra u klaar bent om echte klantbetalingen te ontvangen.
Stap 3: Maak een nieuwe REST API-app aan
-
1
Klik op de knop Create App.
-
2
Vul bij App Name een herkenbare naam in (bijv.
Passinstance Wallet Payments). -
3
Stel App Type in op Merchant.
-
4
Hebt u meerdere zakelijke Sandbox-accounts, selecteer dan het gewenste testaccount.
-
5
Klik op Create App.
Stap 4: Kopieer Client ID & Client Secret
PayPal opent de detailpagina van uw applicatie:
-
Kopieer de tekenreeks bij Client ID.
-
Klik onder Secret op Show en kopieer de Client Secret. Bewaar dit geheim strikt vertrouwelijk.
PayPal configureren in uw Passinstance-werkruimte
Zodra u uw REST-inloggegevens hebt, koppelt u PayPal aan uw werkruimte:
Via het Dashboard:
-
1
Ga naar Instellingen -> Integraties -> Betalingen (
/settings/integrations/payments). -
2
Zoek PayPal op en klik op Verbinden.
-
3
Selecteer uw omgeving (Sandbox of Live).
-
4
Plak uw Client ID en Client Secret.
-
5
Kies uw standaardvaluta (bijv.
EUR,USD,GBP). -
6
Klik op Opslaan & verbinding testen. Passinstance voert automatisch een OAuth-handshake uit om de inloggegevens te bevestigen voordat de gateway wordt geactiveerd.
Via de 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"
}
Respons (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
}
De PayPal-webhook configureren voor directe pasuitgifte
Om passen direct na betalingsvastlegging uit te geven, registreert u het webhook-endpoint van Passinstance in uw PayPal Developer Portal:
-
1
Scroll op uw PayPal-apppagina onder Apps & Credentials omlaag naar Webhooks.
-
2
Klik op Add Webhook.
-
3
Vul in het veld Webhook URL het webhook-endpoint van uw werkruimte in:
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
4
Vink onder Event Types de volgende gebeurtenissen aan:
- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)
-
5
Klik op Save. Kopieer de gegenereerde Webhook ID en plak deze in Passinstance bij uw PayPal-integratie-instellingen.
Wanneer een klant een betaling goedkeurt in PassFlow, meldt PayPal dit via deze webhook aan Passinstance. Passinstance verifieert de cryptografische header PAYPAL-TRANSMISSION-SIG, maakt het pasrecord aan en levert de pas direct in de wallet van de klant.
Probleemoplossing voor veelvoorkomende PayPal-fouten
| Foutcode / melding | Oorzaak | Oplossing |
|---|---|---|
INVALID_CLIENT | De Client ID of Secret is onjuist, of er zijn Sandbox-gegevens gebruikt in de Live-modus. | Controleer of u de inloggegevens nauwkeurig hebt gekopieerd en of de omgevingsmodus (Sandbox versus Live) in beide systemen overeenkomt. |
AUTHENTICATION_FAILURE | De Client Secret is opnieuw ingesteld in PayPal of bevat voorloop- of naloopspaties. | Genereer een nieuwe Client Secret in het PayPal Developer Dashboard en sla deze opnieuw op in Passinstance. |
CURRENCY_NOT_SUPPORTED | De valuta ingesteld in PassFlow (bijv. JPY of BRL) is niet geactiveerd in uw zakelijke PayPal-account. | Log in op uw PayPal Business-account -> Accountinstellingen -> Valuta's en schakel de gewenste valuta in. |
| Pas niet uitgegeven na betaling | De PayPal-webhook ontbreekt of wordt geblokkeerd door een firewall. | Controleer of de webhook-URL is opgeslagen in PayPal met het evenement PAYMENT.CAPTURE.COMPLETED ingeschakeld. Bekijk Activiteit & logboeken in Passinstance voor tijdstempels van webhookbezorging. |
Gerelateerde documentatie
-
Passen verkopen — Complete handleiding voor het instellen van betaalde passen en tickets in PassFlow.
-
Abonnementen verkopen — Terugkerende clublidmaatschappen beheren met PayPal Subscriptions.
-
Betaalmethoden — Betaalmethoden voor facturatie van uw werkruimte beheren.
