Skip to content
Help Center Guide · Third-Party Integrations
5 min readVerified 2026-11-16

Requesting a PayPal API Signature & REST Credentials

Configure PayPal payment integration for pass sales: modern REST API OAuth credentials (Client ID & Secret) vs legacy NVP API signatures.

In This Guide

Overview: Modern PayPal REST OAuth vs. Legacy NVP API Signatures

When integrating PayPal into Passinstance to monetize digital passes, event tickets, or membership cards via PassFlow, merchants often ask about requesting a "PayPal API Signature".

In the historical PayPal ecosystem, the classic NVP/SOAP (Name-Value Pair) API utilized a 3-part credential set consisting of an API Username, API Password, and API Signature. However, modern e-commerce systems, mobile wallet applications, and Passinstance utilize the PayPal REST API v2 powered by OAuth 2.0:

Credential ModelArchitectureComponentsPlatform Support & Security
Modern PayPal REST API (Required)OAuth 2.0 Client CredentialsClient ID & Client SecretSupported: Securely tokenized at the workspace level, supports Smart Payment Buttons, Venmo, Pay in 4, and real-time webhooks.
Legacy PayPal NVP / SOAP APIClassic 3-Token AuthenticationAPI Username, API Password, API SignatureDeprecated: Direct form-level credential writes are blocked via rejectLegacySecretWrites in Passinstance API.
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PAYPAL REST OAUTH INTEGRATION & PASS ISSUANCE
STAGE 01 PAYPAL DEVELOPER DASHBOARD (MERCHANT)
1
Create REST App under Apps & Credentials (Sandbox or Live)
2
Generate Client ID & Client Secret
STAGE 02 PASSINSTANCE WORKSPACE PAYMENT GATEWAY LAYER
Encrypts credentials securely in tenant registry
Validates PayPal API handshake via OAuth 2.0 Bearer token exchange
Mounts PayPal Smart Payment Buttons inside PassFlow (PaymentStep)
STAGE 03 PAYPAL WEBHOOK LISTENER & REAL-TIME ISSUANCE
Webhook: PAYMENT.CAPTURE.COMPLETED / CHECKOUT.ORDER.APPROVED
Verifies cryptographic signature (PAYPAL-TRANSMISSION-SIG)
Triggers instant pass issuance & delivers Apple/Google Wallet buttons

Why Legacy Secret Writes Are Blocked (rejectLegacySecretWrites)

In earlier web architectures, developers sometimes pasted PayPal API passwords and signatures directly into form field definitions or template settings. In Passinstance, doing so is strictly rejected:

Important: In forms.service.ts (line 1269), the Passinstance backend enforces rejectLegacySecretWrites. Any attempt to save raw payment secrets (payPalApiUsername, payPalApiPassword, or payPalApiSignature) inside public form definitions or template metadata throws an immediate BadRequestException.

Payment credentials must be configured once at the workspace level using OAuth REST credentials (Client ID and Client Secret), where they are encrypted in the tenant vault and decoupled from public-facing registration forms.


Step-by-Step Walkthrough: Obtaining PayPal REST Credentials

Follow these steps to generate your PayPal REST API credentials from the official PayPal Developer Portal:

Step 1: Log in to PayPal Developer Portal

  1. 1
    Open developer.paypal.com in your browser.
  2. 2
    Click Log In to Dashboard in the upper-right corner and authenticate with your PayPal Business Account.

Step 2: Open "Apps & Credentials"

  1. 1
    In the left navigation menu, click Apps & Credentials.
  2. 2
    Select your environment:

- Sandbox: Use Sandbox credentials while testing your pass flow and designing templates. - Live: Use Live credentials when you are ready to collect real payments from customers.

Step 3: Create a New REST API App

  1. 1
    Click the Create App button.
  2. 2
    In the App Name field, enter a recognizable name (e.g. Passinstance Wallet Payments).
  3. 3
    Set the App Type to Merchant.
  4. 4
    If you have multiple Sandbox business accounts, select the relevant test account.
  5. 5
    Click Create App.

Step 4: Copy Client ID & Client Secret

PayPal opens your application details page:

  • Copy the Client ID string.
  • Under Secret, click Show and copy the Client Secret string. Keep this secret confidential.

Configuring PayPal in Your Passinstance Workspace

Once you have your REST credentials, connect PayPal to your workspace:

Via Dashboard:

  1. 1
    Navigate to Settings -> Integrations -> Payments (/settings/integrations/payments).
  2. 2
    Locate PayPal and click Connect.
  3. 3
    Select your environment (Sandbox or Live).
  4. 4
    Paste your Client ID and Client Secret.
  5. 5
    Select your default currency (e.g. EUR, USD, GBP).
  6. 6
    Click Save & Test Connection. Passinstance performs an automated OAuth handshake to confirm the credentials before activating the gateway.

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

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

Configuring the PayPal Webhook for Instant Pass Issuance

To issue passes immediately upon payment capture, register Passinstance's webhook endpoint in your PayPal Developer Portal:

  1. 1
    In your PayPal app page under Apps & Credentials, scroll down to Webhooks.
  2. 2
    Click Add Webhook.
  3. 3
    In the Webhook URL field, enter your workspace webhook endpoint:
TEXT
https://api.passinstance.com/api/v1/payments/webhooks/paypal
  1. 4
    Under Event Types, check the following events:

- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)

  1. 5
    Click Save. Copy the generated Webhook ID and paste it into Passinstance under your PayPal integration settings.

When a customer authorizes payment in PassFlow, PayPal notifies Passinstance via this webhook. Passinstance verifies the cryptographic PAYPAL-TRANSMISSION-SIG header, mints the pass record, and hands the pass to the customer's wallet.


Troubleshooting Common PayPal Errors

Error Code / MessageRoot CauseSolution
INVALID_CLIENTThe Client ID or Secret is incorrect, or Sandbox credentials were used in Live mode.Verify you copied the credentials accurately and that the environment mode (Sandbox vs Live) matches in both systems.
AUTHENTICATION_FAILUREThe Client Secret was reset in PayPal or contains leading/trailing spaces.Generate a new Client Secret in the PayPal Developer Dashboard and re-save it in Passinstance.
CURRENCY_NOT_SUPPORTEDThe currency specified in PassFlow (e.g. JPY or BRL) is not enabled in your PayPal merchant account.Log in to your PayPal Business Account -> Account Settings -> Currencies and enable the target currency.
Pass Not Issued After PaymentPayPal webhook is missing or blocked by firewall.Verify the webhook URL is saved in PayPal with the PAYMENT.CAPTURE.COMPLETED event enabled. Check Passinstance Activity & Logs for webhook delivery timestamps.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.