PayPal REST API: introduzione e primi passi

Le PayPal REST API sono l'interfaccia HTTP/JSON moderna per integrare PayPal lato server. Sostituiscono le vecchie API NVP/SOAP (deprecate) e offrono flussi più semplici, payload JSON leggibili, autenticazione OAuth2 standard e una documentazione completa. In questa guida vediamo i concetti base, l'autenticazione, il primo ordine e la cattura del pagamento con esempi pratici.

Cosa permettono di fare le REST API

Le API coprono l'intero ciclo di vita del pagamento: creare ordini (Orders v2), catturare fondi, rimborsare, gestire abbonamenti ricorrenti (Subscriptions), generare payout multipli (Payouts), gestire dispute (Disputes), inviare fatture (Invoicing), accedere a report transazioni (Reporting). Sono pensate sia per integrazioni server-to-server tradizionali sia per uso ibrido con Smart Buttons (createOrder lato server, approvazione lato client).

Autenticazione OAuth2

Le REST API usano OAuth2 con grant "client_credentials". Il merchant ottiene un access_token usando client_id e client_secret tramite POST a /v1/oauth2/token. Il token ha validità di ~9 ore e va incluso negli header successivi come "Authorization: Bearer {token}". Best practice: caching del token con scadenza 5 minuti prima dell'expiry, refresh automatico, segregazione dei segreti in variabili d'ambiente o secret manager.

Procedura passo-passo: primo ordine

1. Crea app REST nel Developer Dashboard e copia client_id/secret Sandbox.
2. Ottieni access_token con POST /v1/oauth2/token (Basic Auth + grant_type=client_credentials).
3. Crea ordine con POST /v2/checkout/orders, body JSON con intent, purchase_units e amount.
4. Ricevi response con order_id e link "approve" verso il flusso PayPal.
5. Reindirizza il cliente al link approve oppure usa Smart Buttons che gestisce il flusso.
6. Dopo approvazione, ricevi callback o webhook con order_id.
7. Cattura il pagamento con POST /v2/checkout/orders/{id}/capture.
8. Ricevi response con capture_id e status COMPLETED.
9. Salva capture_id nel database per refund e tracking futuro.

Struttura della risposta JSON

Le risposte hanno una struttura prevedibile: id (identificativo univoco PayPal), status (CREATED, APPROVED, COMPLETED, VOIDED), intent (CAPTURE o AUTHORIZE), purchase_units (array con dettagli prodotti, importi, payee), create_time e update_time ISO 8601, links (HATEOAS verso azioni successive). I link sono auto-documentanti: l'azione "capture" è raggiungibile dal link con rel="capture", "void" con rel="void", e così via.

Errori e codici HTTP

Le API tornano codici standard. 200/201: successo. 400: richiesta malformata (campi mancanti, formato JSON errato). 401: token scaduto o invalido. 403: permessi insufficienti (app non autorizzata per quel servizio). 404: risorsa non trovata (order_id inesistente). 422: validazione fallita (importo negativo, valuta non supportata). 500/503: errore server PayPal. Implementa retry esponenziale per 5xx, mai per 4xx.

Sicurezza e segregazione

Best practice: chiamate API solo da server, mai dal browser (esporrebbe il secret). Usa HTTPS sempre, anche per call interne. Conserva il secret in vault (HashiCorp Vault, AWS Secrets Manager) o variabili d'ambiente, mai nel codice sorgente o nel database. Ruota le credenziali ogni 90 giorni. Limita gli IP che possono chiamare le API tramite la console PayPal se possibile. Logga le chiamate con request_id per debug ma maschera dati sensibili.

Errori comuni e come risolverli

• Token usato dopo scadenza: implementa cache con refresh proattivo.
• Currency mismatch: l'order ha valuta diversa dall'account. Verifica configurazione.
• Intent sbagliato: AUTHORIZE richiede capture esplicita entro 29 giorni, CAPTURE addebita subito.
• Mancata gestione idempotenza: usa header PayPal-Request-Id univoco per ogni POST.

Domande frequenti

D: Posso chiamare le REST API direttamente dal browser?
R: No, il secret resterebbe esposto. Solo Smart Buttons usa client_id lato client senza secret.

D: Quanto costa usare le REST API?
R: Le API sono gratuite. Paghi solo le commissioni di transazione standard PayPal.

D: Come faccio refund?
R: POST /v2/payments/captures/{capture_id}/refund con amount opzionale per rimborso parziale.

Consigli operativi e best practice

Per consolidare quanto visto nei paragrafi precedenti tieni a mente alcuni accorgimenti pratici che fanno la differenza nel quotidiano. Documenta sempre ogni passaggio della configurazione in un registro interno aziendale: serve sia per il team sia in caso di audit fiscale o di richiesta di chiarimenti da parte di PayPal. Conserva una copia delle ricevute, delle email transazionali e degli screenshot dei pannelli di amministrazione per almeno dieci anni, come richiesto dalla normativa civilistica italiana.

Pianifica una revisione trimestrale della tua integrazione PayPal: verifica le commissioni applicate, controlla i tassi di contestazione, leggi gli avvisi nel Centro Risoluzioni e aggiorna eventuali plugin o SDK obsoleti. Le aziende che fanno questo controllo regolare riducono del 40-60% gli incidenti operativi rispetto a chi gestisce PayPal in modo reattivo. Coinvolgi anche il team di customer service: spesso sono loro i primi a notare pattern di richieste che possono indicare problemi nascosti nel flusso di pagamento.

Infine, abituati a monitorare i tempi di risposta nelle dispute e nei reclami: PayPal premia i merchant che rispondono entro 24-48 ore con score reputazionali migliori, che si traducono in minori riserve, commissioni più favorevoli al raggiungimento dei volumi e un'esperienza più fluida in caso di controlli antifrode. La gestione proattiva è sempre meno costosa di quella reattiva, in PayPal come nel resto del business online.

Hai bisogno di aiuto?

Se vuoi integrare PayPal nel tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.