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 Model | Architecture | Components | Platform Support & Security |
|---|---|---|---|
| Modern PayPal REST API (Required) | OAuth 2.0 Client Credentials | Client ID & Client Secret | Supported: Securely tokenized at the workspace level, supports Smart Payment Buttons, Venmo, Pay in 4, and real-time webhooks. |
| Legacy PayPal NVP / SOAP API | Classic 3-Token Authentication | API Username, API Password, API Signature | Deprecated: Direct form-level credential writes are blocked via rejectLegacySecretWrites in Passinstance API. |
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 enforcesrejectLegacySecretWrites. Any attempt to save raw payment secrets (payPalApiUsername,payPalApiPassword, orpayPalApiSignature) inside public form definitions or template metadata throws an immediateBadRequestException.
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
Open developer.paypal.com in your browser.
-
2
Click Log In to Dashboard in the upper-right corner and authenticate with your PayPal Business Account.
Step 2: Open "Apps & Credentials"
-
1
In the left navigation menu, click Apps & Credentials.
-
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
Click the Create App button.
-
2
In the App Name field, enter a recognizable name (e.g.
Passinstance Wallet Payments). -
3
Set the App Type to Merchant.
-
4
If you have multiple Sandbox business accounts, select the relevant test account.
-
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
Navigate to Settings -> Integrations -> Payments (
/settings/integrations/payments). -
2
Locate PayPal and click Connect.
-
3
Select your environment (Sandbox or Live).
-
4
Paste your Client ID and Client Secret.
-
5
Select your default currency (e.g.
EUR,USD,GBP). -
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):
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):
{
"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
In your PayPal app page under Apps & Credentials, scroll down to Webhooks.
-
2
Click Add Webhook.
-
3
In the Webhook URL field, enter your workspace webhook endpoint:
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
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)
-
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 / Message | Root Cause | Solution |
|---|---|---|
INVALID_CLIENT | The 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_FAILURE | The 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_SUPPORTED | The 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 Payment | PayPal 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. |
Related Documentation
-
Selling Passes — Complete guide to setting up paid passes and tickets in PassFlow.
-
Selling Subscriptions — Managing recurring club memberships with PayPal Subscriptions.
-
Payment Methods — Managing workspace billing payment methods.
