Panoramica: PayPal REST OAuth moderno vs. firme API NVP legacy
Quando integrano PayPal in Passinstance per monetizzare pass digitali, biglietti per eventi o tessere socio tramite PassFlow, i merchant chiedono spesso come richiedere una "Firma API PayPal" (PayPal API Signature).
Nell'ecosistema PayPal storico, la classica API NVP/SOAP (Name-Value Pair) utilizzava un set di credenziali in 3 parti composto da Nome utente API, Password API e Firma API. Tuttavia, i moderni sistemi e-commerce, le app wallet mobili e Passinstance utilizzano la PayPal REST API v2 basata su OAuth 2.0:
| Modello di credenziali | Architettura | Componenti | Supporto piattaforma e sicurezza |
|---|---|---|---|
| PayPal REST API moderna (Obbligatoria) | Credenziali client OAuth 2.0 | Client ID e Client Secret | Supportata: tokenizzata in sicurezza a livello di workspace; supporta Smart Payment Buttons, Venmo, Paga in 4 rate e webhook in tempo reale. |
| PayPal NVP / SOAP API legacy | Autenticazione classica a 3 token | API Username, API Password, API Signature | Deprecata: la scrittura diretta di credenziali a livello di modulo è bloccata tramite rejectLegacySecretWrites nell'API di Passinstance. |
Perché la scrittura di segreti legacy è bloccata (rejectLegacySecretWrites)
Nelle architetture web precedenti, gli sviluppatori incollavano talvolta password e firme API PayPal direttamente nelle definizioni dei campi dei moduli o nelle impostazioni dei modelli. In Passinstance questa pratica è rigorosamente bloccata:
Importante: In
forms.service.ts(riga 1269), il backend di Passinstance applicarejectLegacySecretWrites. Qualsiasi tentativo di salvare segreti di pagamento in chiaro (payPalApiUsername,payPalApiPasswordopayPalApiSignature) all'interno di definizioni di moduli pubblici o metadati di modelli genera immediatamente unaBadRequestException.
Le credenziali di pagamento devono essere configurate una sola volta a livello di workspace utilizzando le credenziali REST OAuth (Client ID e Client Secret), dove vengono crittografate nel vault del tenant e disaccoppiate dai moduli di registrazione pubblici.
Procedura passo dopo passo: ottenere le credenziali PayPal REST
Segui questi passaggi per generare le credenziali PayPal REST API dal portale ufficiale PayPal Developer:
Passaggio 1: accedi al PayPal Developer Portal
-
1
Apri developer.paypal.com nel browser.
-
2
Fai clic su Log In to Dashboard nell'angolo in alto a destra e autenticati con il tuo Account PayPal Business.
Passaggio 2: apri "Apps & Credentials"
-
1
Nel menu di navigazione a sinistra, fai clic su Apps & Credentials.
-
2
Seleziona l'ambiente:
- Sandbox: utilizza le credenziali Sandbox mentre testi il PassFlow e progetti i modelli. - Live: utilizza le credenziali Live quando sei pronto a incassare pagamenti reali dai clienti.
Passaggio 3: crea una nuova app REST API
-
1
Fai clic sul pulsante Create App.
-
2
Nel campo App Name, inserisci un nome riconoscibile (ad es.
Passinstance Wallet Payments). -
3
Imposta App Type su Merchant.
-
4
Se disponi di più account business Sandbox, seleziona l'account di test appropriato.
-
5
Fai clic su Create App.
Passaggio 4: copia Client ID e Client Secret
PayPal apre la pagina dei dettagli dell'applicazione:
-
Copia la stringa Client ID.
-
Sotto Secret, fai clic su Show e copia la stringa Client Secret. Conserva questo segreto in modo riservato.
Configurare PayPal nel workspace Passinstance
Una volta ottenute le credenziali REST, collega PayPal al tuo workspace:
Dalla Dashboard:
-
1
Vai su Impostazioni -> Integrazioni -> Pagamenti (
/settings/integrations/payments). -
2
Individua PayPal e fai clic su Connetti.
-
3
Seleziona l'ambiente (Sandbox o Live).
-
4
Incolla Client ID e Client Secret.
-
5
Seleziona la valuta predefinita (ad es.
EUR,USD,GBP). -
6
Fai clic su Salva e testa connessione. Passinstance esegue un handshake OAuth automatico per verificare le credenziali prima di attivare il gateway.
Tramite 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"
}
Risposta (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
}
Configurazione del webhook PayPal per l'emissione istantanea dei pass
Per emettere i pass immediatamente alla cattura del pagamento, registra l'endpoint webhook di Passinstance nel PayPal Developer Portal:
-
1
Nella pagina della tua app PayPal in Apps & Credentials, scorri fino a Webhooks.
-
2
Fai clic su Add Webhook.
-
3
Nel campo Webhook URL, inserisci l'endpoint webhook del workspace:
https://api.passinstance.com/api/v1/payments/webhooks/paypal
-
4
Sotto Event Types, seleziona i seguenti eventi:
- Checkout order approved (CHECKOUT.ORDER.APPROVED) - Payment capture completed (PAYMENT.CAPTURE.COMPLETED) - Payment capture refunded (PAYMENT.CAPTURE.REFUNDED)
-
5
Fai clic su Save. Copia il Webhook ID generato e incollalo in Passinstance nelle impostazioni dell'integrazione PayPal.
Quando un cliente autorizza il pagamento in PassFlow, PayPal notifica Passinstance tramite questo webhook. Passinstance verifica l'header crittografico PAYPAL-TRANSMISSION-SIG, crea il record del pass e lo consegna al wallet del cliente.
Risoluzione degli errori PayPal più comuni
| Codice / Messaggio di errore | Causa principale | Soluzione |
|---|---|---|
INVALID_CLIENT | Il Client ID o il Secret non sono corretti, oppure sono state usate credenziali Sandbox in modalità Live. | Verifica di aver copiato correttamente le credenziali e che la modalità ambiente (Sandbox vs Live) coincida in entrambi i sistemi. |
AUTHENTICATION_FAILURE | Il Client Secret è stato rigenerato in PayPal oppure contiene spazi iniziali o finali. | Genera un nuovo Client Secret nella PayPal Developer Dashboard e salvalo nuovamente in Passinstance. |
CURRENCY_NOT_SUPPORTED | La valuta configurata in PassFlow (ad es. JPY o BRL) non è abilitata nel tuo account merchant PayPal. | Accedi al tuo Account PayPal Business -> Impostazioni account -> Valute e abilita la valuta desiderata. |
| Pass non emesso dopo il pagamento | Il webhook PayPal è mancante o bloccato da un firewall. | Verifica che l'URL del webhook sia salvato in PayPal con l'evento PAYMENT.CAPTURE.COMPLETED abilitato. Controlla Attività e log in Passinstance per i timestamp di consegna del webhook. |
Documentazione correlata
-
Vendere pass — Guida completa alla configurazione di pass e biglietti a pagamento in PassFlow.
-
Vendere abbonamenti — Gestione di abbonamenti ricorrenti con PayPal Subscriptions.
-
Metodi di pagamento — Gestione dei metodi di pagamento per la fatturazione del workspace.
