Skip to content
Guida del Centro assistenza · Integrazioni di terze parti
5 min di letturaVerificato 2026-11-16

Richiesta di firma API PayPal e credenziali REST

Configura l'integrazione dei pagamenti PayPal per la vendita di pass: moderne credenziali OAuth REST API (Client ID e Secret) rispetto alle firme API NVP legacy.

In questa guida

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 credenzialiArchitetturaComponentiSupporto piattaforma e sicurezza
PayPal REST API moderna (Obbligatoria)Credenziali client OAuth 2.0Client ID e Client SecretSupportata: 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 legacyAutenticazione classica a 3 tokenAPI Username, API Password, API SignatureDeprecata: la scrittura diretta di credenziali a livello di modulo è bloccata tramite rejectLegacySecretWrites nell'API di Passinstance.
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
INTEGRAZIONE PAYPAL REST OAUTH ED EMISSIONE PASS
FASE 01 DASHBOARD PAYPAL DEVELOPER (MERCHANT)
1
Crea una REST App in Apps & Credentials (Sandbox o Live)
2
Genera Client ID e Client Secret
FASE 02 LIVELLO GATEWAY PAGAMENTI WORKSPACE PASSINSTANCE
Crittografa in sicurezza le credenziali nel registro del tenant
Valida l'handshake API PayPal tramite scambio token OAuth 2.0
Monta i PayPal Smart Payment Buttons all'interno di PassFlow (PaymentStep)
FASE 03 LISTENER WEBHOOK PAYPAL ED EMISSIONE IN TEMPO REALE
Webhook: PAYMENT.CAPTURE.COMPLETED / CHECKOUT.ORDER.APPROVED
Verifica la firma crittografica (PAYPAL-TRANSMISSION-SIG)
Attiva l'emissione istantanea del pass e mostra i pulsanti Apple/Google Wallet

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 applica rejectLegacySecretWrites. Qualsiasi tentativo di salvare segreti di pagamento in chiaro (payPalApiUsername, payPalApiPassword o payPalApiSignature) all'interno di definizioni di moduli pubblici o metadati di modelli genera immediatamente una BadRequestException.

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. 1
    Apri developer.paypal.com nel browser.
  2. 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. 1
    Nel menu di navigazione a sinistra, fai clic su Apps & Credentials.
  2. 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. 1
    Fai clic sul pulsante Create App.
  2. 2
    Nel campo App Name, inserisci un nome riconoscibile (ad es. Passinstance Wallet Payments).
  3. 3
    Imposta App Type su Merchant.
  4. 4
    Se disponi di più account business Sandbox, seleziona l'account di test appropriato.
  5. 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. 1
    Vai su Impostazioni -> Integrazioni -> Pagamenti (/settings/integrations/payments).
  2. 2
    Individua PayPal e fai clic su Connetti.
  3. 3
    Seleziona l'ambiente (Sandbox o Live).
  4. 4
    Incolla Client ID e Client Secret.
  5. 5
    Seleziona la valuta predefinita (ad es. EUR, USD, GBP).
  6. 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):

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

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

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. 1
    Nella pagina della tua app PayPal in Apps & Credentials, scorri fino a Webhooks.
  2. 2
    Fai clic su Add Webhook.
  3. 3
    Nel campo Webhook URL, inserisci l'endpoint webhook del workspace:
TEXT
https://api.passinstance.com/api/v1/payments/webhooks/paypal
  1. 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)

  1. 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 erroreCausa principaleSoluzione
INVALID_CLIENTIl 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_FAILUREIl 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_SUPPORTEDLa 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 pagamentoIl 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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.