Skip to content
Helpcentrum-gids · Externe integraties
5 min leestijdGecontroleerd 2026-11-16

Een PayPal API-handtekening en REST-referenties aanvragen

Configureer de PayPal-betalingsintegratie voor pasverkoop: moderne REST API OAuth-referenties (Client ID & Secret) versus traditionele NVP API-handtekeningen.

In deze gids

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:

InlogmodelArchitectuurOnderdelenPlatformondersteuning & beveiliging
Moderne PayPal REST API (vereist)OAuth 2.0 Client CredentialsClient ID & Client SecretOndersteund: Veilig getokeniseerd op werkruimteniveau; ondersteunt Smart Payment Buttons, Venmo, Pay in 4 en realtime webhooks.
Verouderde PayPal NVP / SOAP APIKlassieke 3-tokenauthenticatieAPI Username, API Password, API SignatureVerouderd: Rechtstreeks opslaan van inloggegevens op formulierniveau wordt geblokkeerd via rejectLegacySecretWrites in de Passinstance API.
SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PAYPAL REST OAUTH-INTEGRATIE & PASUITGIFTE
FASE 01 PAYPAL DEVELOPER DASHBOARD (HANDELAAR)
1
Maak REST-app aan onder Apps & Credentials (Sandbox of Live)
2
Genereer Client ID & Client Secret
FASE 02 PASSINSTANCE BETAALGATEWAYLAAG VAN DE WERKRUIMTE
Versleutelt inloggegevens veilig in het tenantregister
Valideert PayPal API-handshake via OAuth 2.0 Bearer-tokenuitwisseling
Laadt PayPal Smart Payment Buttons in PassFlow (PaymentStep)
FASE 03 PAYPAL WEBHOOK-LISTENER & REALTIME PASUITGIFTE
Webhook: PAYMENT.CAPTURE.COMPLETED / CHECKOUT.ORDER.APPROVED
Verifieert cryptografische handtekening (PAYPAL-TRANSMISSION-SIG)
Activeert directe pasuitgifte & levert Apple/Google Wallet-knoppen

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-backend rejectLegacySecretWrites. Elke poging om ruwe betaalgeheimen (payPalApiUsername, payPalApiPassword of payPalApiSignature) op te slaan in openbare formulierdefinities of sjabloonmetadata resulteert onmiddellijk in een BadRequestException.

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. 1
    Open developer.paypal.com in uw browser.
  2. 2
    Klik rechtsboven op Log In to Dashboard en meld u aan met uw PayPal Business-account.

Stap 2: Open "Apps & Credentials"

  1. 1
    Klik in het linker navigatiemenu op Apps & Credentials.
  2. 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. 1
    Klik op de knop Create App.
  2. 2
    Vul bij App Name een herkenbare naam in (bijv. Passinstance Wallet Payments).
  3. 3
    Stel App Type in op Merchant.
  4. 4
    Hebt u meerdere zakelijke Sandbox-accounts, selecteer dan het gewenste testaccount.
  5. 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. 1
    Ga naar Instellingen -> Integraties -> Betalingen (/settings/integrations/payments).
  2. 2
    Zoek PayPal op en klik op Verbinden.
  3. 3
    Selecteer uw omgeving (Sandbox of Live).
  4. 4
    Plak uw Client ID en Client Secret.
  5. 5
    Kies uw standaardvaluta (bijv. EUR, USD, GBP).
  6. 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):

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"
}

Respons (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
}

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. 1
    Scroll op uw PayPal-apppagina onder Apps & Credentials omlaag naar Webhooks.
  2. 2
    Klik op Add Webhook.
  3. 3
    Vul in het veld Webhook URL het webhook-endpoint van uw werkruimte in:
TEXT
https://api.passinstance.com/api/v1/payments/webhooks/paypal
  1. 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)

  1. 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 / meldingOorzaakOplossing
INVALID_CLIENTDe 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_FAILUREDe 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_SUPPORTEDDe 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 betalingDe 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.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.