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

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. Usalo insieme a Stripe per i clienti che preferiscono PayPal.

Requisiti

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

1. Accedi a 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

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://<your-domain>/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.

Eventi webhook

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

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

• 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), PayPal memorizza il token di pagamento nel proprio vault. NexCMP conserva solo un identificativo e l'indirizzo e-mail PayPal. Vedi 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

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.