--- title: PayPal description: Collega PayPal a NexCMP per le ricariche del portafoglio: credenziali dell'app REST, webhook, test in sandbox e account PayPal salvati. url: https://nexcmp.com/it/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # PayPal > **Where in the admin:** Finance › Payment channels › PayPal (`/payments/paypal`). L'interruttore di attivazione/disattivazione e le commissioni si trovano in Finance › Payment channels › Fees & limits (`/payments/fees`). ## Descrizione {#what-it-does} Consente ai clienti di ricaricare il proprio portafoglio in USD con il saldo PayPal, il conto bancario o la carta associata a PayPal. I clienti possono anche consentire a NexCMP di ricordare il proprio account PayPal per la [automatic top-up](https://nexcmp.com/it/docs/billing/auto-top-up/). Usalo insieme a [Stripe](https://nexcmp.com/it/docs/billing/stripe/) per i clienti che preferiscono PayPal. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Account PayPal | Un account PayPal **Business** in grado di ricevere USD. | | App REST | Un'app REST nel PayPal Developer Dashboard (**Apps & Credentials**) che fornisce un **Client ID** e un **Client secret**. Usa la scheda **Sandbox** per i test, **Live** per la produzione. | | Rete | HTTPS raggiungibile da Internet (PayPal chiama il webhook) e accesso in uscita verso `api-m.paypal.com` (live) o `api-m.sandbox.paypal.com` (sandbox), porta 443. | | Permessi | L'app REST richiede le funzionalità di rimborso e webhook. La finestra di dialogo **Check** mostra se entrambe le autorizzazioni sono presenti. | | Dipendenze | Nessuno. | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 1. Accedi a [developer.paypal.com](https://developer.paypal.com) con il tuo account Business e apri **Apps & Credentials**. 2. Scegli **Sandbox** (test) o **Live**, quindi **Create App**. Denominala ad esempio "NexCMP". 3. Copia il **Client ID** e il **Secret** dell'app. 4. Per i test, usa **Testing Tools › Sandbox Accounts** per trovare o creare un account sandbox *Personal* (acquirente). 5. Non è necessario creare il webhook manualmente; NexCMP lo crea con il pulsante **Create webhook**. ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels › PayPal** (`/payments/paypal`). 2. In **API keys**, scegli **Mode**: `live` (denaro reale, `api-m.paypal.com`) o `sandbox` (`api-m.sandbox.paypal.com`). 3. Incolla il **Client ID** (almeno 20 caratteri) e il **Client secret**. 4. Clicca su **Check**. Vengono testate le credenziali inserite (il salvataggio non è richiesto) e vengono segnalati la connessione, l'App ID, la modalità, la presenza o meno degli scope per rimborsi e webhook e la durata del token. 5. Clicca su **Save**. 6. Nella scheda **Webhook** conferma che l'URL sia `https:///v1/billing/paypal/webhook` (deve essere `https`), quindi clicca su **Create webhook** e conferma. NexCMP chiede a PayPal di creare o aggiornare il webhook con 11 eventi e memorizza il **Webhook ID** restituito. Il pulsante utilizza le chiavi **salvate**; salva prima se le hai appena modificate. 7. Clicca di nuovo su **Check**: la riga **Webhook** dovrebbe mostrare "exists, 11 events". 8. Apri **Fees & limits**, attiva **PayPal**, imposta **PayPal fee %** (predefinito 4.4) e **PayPal fixed fee (cents)** (predefinito 30) in base alla tua tariffa e clicca su **Save channels & fees**. ![Pagina PayPal con modalità sandbox e credenziali di esempio inserite](https://nexcmp.com/it/docs/images/billing/paypal-01-keys.webp) ### Eventi webhook {#webhook-events} NexCMP registra questi 11 eventi: `CHECKOUT.ORDER.APPROVED`, `PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.PENDING`, `PAYMENT.CAPTURE.DECLINED`, `PAYMENT.CAPTURE.REFUNDED`, `PAYMENT.CAPTURE.REVERSED`, `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.UPDATED`, `CUSTOMER.DISPUTE.RESOLVED`, `RISK.DISPUTE.CREATED`, `CHECKOUT.PAYMENT-APPROVAL.REVERSED`. Ogni webhook viene verificato chiamando l'API di verifica della firma di PayPal, salvato una volta ed elaborato in modo idempotente. NexCMP non si fida mai dell'importo nel corpo del webhook: prima di accreditare una cattura, recupera la cattura da PayPal. ## Verifica {#verify} 1. Mantieni **Mode** su `sandbox`. Nel portale, apri **Billing › Deposit**, scegli **PayPal**, clicca su **Continue on PayPal** (o sul pulsante PayPal) e accedi con l'account acquirente sandbox. 2. Approva il pagamento. Verrai reindirizzato al portale, il saldo aumenterà e il pagamento apparirà sotto **Finance › Billing › Top-ups** come *Completed*. 3. Apri **Payment channels › Gateway events › PayPal & USDT**: l'evento `PAYMENT.CAPTURE.COMPLETED` è elencato. 4. Quando tutto funziona, passa **Mode** a `live`, inserisci le credenziali live, fai clic su **Save**, quindi di nuovo su **Create webhook** (i webhook di sandbox e live sono separati). ## Limiti e note {#limits-notes} - **Come viene completato un pagamento.** L'ordine viene creato in USD; dopo che il cliente lo ha approvato, il **server** effettua la cattura (ID richiesta idempotente) e accredita il portafoglio esattamente una volta. Il webhook e un job di riconciliazione eseguito ogni 10 minuti costituiscono una rete di sicurezza nel caso in cui il cliente chiuda il browser. - **Ordini in sospeso e abbandonati.** Un ordine può rimanere aperto per 12 ore. Un cliente può avere al massimo 5 ordini in sospeso (il server risponde `too_many_pending`, HTTP 429). Un ordine non ancora catturato dopo 24 ore viene contrassegnato come fallito. - **Nessun webhook configurato.** Il pannello risponde HTTP 503 a ogni webhook di PayPal finché non viene salvato un Webhook ID. Le catture effettuate tramite il portale e la riconciliazione ogni 10 minuti accreditano comunque il portafoglio, ma nulla di ciò che PayPal segnala tramite webhook (contestazioni, storni, catture tardive) viene applicato: clicca su **Create webhook**. - **Account PayPal salvato.** Quando il cliente sceglie di salvare PayPal (o completa il primo deposito, attivando la [ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/)), PayPal memorizza il token di pagamento nel proprio vault. NexCMP conserva solo un identificativo e l'indirizzo e-mail PayPal. Vedi [Saved payment methods](https://nexcmp.com/it/docs/billing/saved-payment-methods/). - **Rimborsi e contestazioni** vengono gestiti come Stripe: le richieste di rimborso vengono approvate in **Finance › Payouts › Card refunds**; una contestazione blocca l'account del cliente e sospende i suoi servizi prepagati finché non la risolvi. - **Commissioni.** La commissione di PayPal non viene letta dinamicamente; la percentuale e la commissione fissa configurate determinano ciò che il cliente vede e ciò che viene accreditato. La tariffa reale dipende dal tuo paese (il modulo suggerisce il 4.4% per il Vietnam e il 3.49% per gli Stati Uniti). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "Client ID troppo breve" | Incollati meno di 20 caratteri | Copia il Client ID completo. | | "L'URL del webhook deve essere https" | URL digitato con `http://` | Usa il tuo dominio `https://` pubblico. | | Il controllo segnala un errore di connessione | Modalità errata (chiavi live in sandbox o viceversa), secret errato, nessun accesso in uscita | Corrispondi **Mode** al tipo di chiave; testa `curl -I https://api-m.paypal.com` dal server. | | Ambito rimborso / webhook mostra "no" | L'app REST non dispone delle funzionalità | Abilita le funzionalità sull'app nella dashboard per sviluppatori di PayPal. | | Banner "Chiave PayPal impostata, NESSUN webhook" | ID webhook mancante | Fai clic su **Create webhook**. | | "Webhook not found" nel controllo | Il webhook è stato eliminato su PayPal o appartiene a un'altra app | Fai clic di nuovo su **Create webhook**. | | Al cliente viene comunicato che PayPal ha rifiutato il pagamento | PayPal ha rifiutato quella fonte di finanziamento | Chiedi al cliente di scegliere un'altra fonte di pagamento. | | Il cliente visualizza "Too many pending requests" | 5 ordini aperti | Attendi che scadano o completali. | | Pulsante PayPal mancante | PayPal disattivato in **Fees & limits** o non configurato | Attivalo e salva le credenziali. |