Integrazione del gateway di pagamento: cosa fare bene
L'integrazione dei pagamenti sembra semplice in un tutorial ed è implacabile in produzione, perché ogni caso di errore comporta o un cliente che ha pagato e non ha ricevuto nulla, o un cliente che ha ricevuto qualcosa senza pagare.
Questa guida copre come funziona il flusso, la decisione progettuale che previene la maggior parte dei problemi, e i casi da collaudare di proposito prima del lancio.
Come funziona davvero il flusso#
Qualunque sia il fornitore, la forma è la stessa: il tuo server crea un'intenzione di addebito, il cliente si autentica presso il fornitore di pagamento, e il fornitore ti comunica l'esito — due volte, per due vie diverse.
- Il tuo server crea un'intenzione di pagamento con importo, valuta e un riferimento al tuo ordine.
- Il cliente inserisce i dati della carta in un campo o in una pagina ospitati, così i dati non toccano mai il tuo server.
- Può essere richiesta un'autenticazione forte, che aggiunge un passaggio da completare.
- Il fornitore riporta il cliente sul tuo sito con un esito.
- Separatamente, il fornitore invia un webhook da server a server con l'esito che fa fede.
- Il tuo sistema aggiorna l'ordine — dal webhook, non dal reindirizzamento.
- L'evasione parte solo dopo che il pagamento è confermato.
I passaggi 4 e 5 sono l'intera progettazione. Il reindirizzamento è un indizio di cosa è successo; il webhook è il fatto.
Perché i webhook devono fare fede#
Il browser del cliente è un narratore inaffidabile. Può chiudersi durante il reindirizzamento, perdere la connessione, o essere manipolato. Se lo stato del tuo ordine dipende dal ritorno del cliente sulla pagina di conferma, avrai ordini pagati mai registrati.
- Aggiorna lo stato dell'ordine solo da webhook verificati; tratta il reindirizzamento come un semplice messaggio all'utente.
- Verifica le firme dei webhook. Un endpoint non autenticato che segna ordini come pagati è esattamente grave quanto suona.
- Rendi idempotente la gestione dei webhook: i fornitori riprovano, e i duplicati arriveranno.
- Rispondi in fretta ed elabora in modo asincrono; gli endpoint lenti vengono riprovati e infine disattivati.
- Registra ogni payload di webhook. Le contestazioni di pagamento si risolvono con i registri.
- Gestisci eventi fuori ordine, perché possono arrivare così e lo faranno.
I casi di errore da collaudare#
Ciascuno di questi capita in produzione. Collaudali di proposito, con le carte di test del fornitore, prima del lancio.
| Caso | Cosa deve succedere |
|---|---|
| Il cliente chiude la scheda dopo aver pagato | Il webhook completa comunque l'ordine; l'e-mail di conferma parte |
| Carta rifiutata | Messaggio chiaro, carrello conservato, nuovo tentativo possibile |
| Autenticazione forte fallita | Ordine non confermato; al cliente viene detto cosa fare |
| Webhook duplicato | Ordine aggiornato una volta, non due; nessuna seconda spedizione |
| Il webhook arriva prima del reindirizzamento | La pagina di conferma rispecchia l'ordine già completato |
| Rimborso parziale | Totali dell'ordine ed eventuale export contabile restano coerenti |
| Scorte esaurite tra pagamento ed evasione | Processo definito: rimborso, attesa o sostituzione |
| Arrotondamento di valuta | L'importo addebitato corrisponde esattamente al totale mostrato |
Perimetro, conformità e denaro#
Poche decisioni determinano quanto onere normativo ti assumi e quanto della transazione ti resta.
- Non memorizzare mai numeri di carta. Usa campi o pagine ospitati perché i dati della carta non raggiungano mai il tuo server; così il perimetro PCI resta minimo.
- Capisci la struttura delle commissioni. Percentuale più quota fissa, più conversione valuta, più commissioni sugli storni. La percentuale in evidenza non è il costo.
- Verifica i tempi di accredito. I giorni fino al regolamento incidono sulla liquidità più di una piccola differenza di aliquota.
- Conferma che il percorso di rimborso funzioni da capo a fondo prima del lancio, rimborsi parziali compresi.
- Supporta i metodi locali che il tuo mercato usa davvero: la carta non è lo standard ovunque, e mancare il metodo locale dominante costa conversioni.
- Tieni pronto un secondo fornitore se i pagamenti sono critici. I disservizi capitano e fermano del tutto il fatturato.
Domande frequenti
Checkout ospitato o modulo integrato?
Il checkout ospitato è più semplice, tiene il perimetro PCI al minimo ed è mantenuto dal fornitore: per la maggior parte dei negozi è l'impostazione predefinita giusta. I campi integrati tengono il cliente sul tuo dominio e danno più controllo sull'esperienza, al costo di più codice e più responsabilità. Entrambi tengono i dati della carta fuori dal tuo server, che è la parte che conta.
Cosa succede se il mio endpoint webhook cade?
I fornitori riprovano con attesa crescente, tipicamente per ore o giorni, quindi un disservizio breve si recupera da solo. Un disservizio lungo significa ordini non confermati, quindi monitora l'endpoint e fatti avvisare in caso di errore. Costruisci anche una riconciliazione quotidiana che confronti le transazioni del fornitore con i tuoi ordini: recupera tutto ciò che i tentativi hanno mancato.
Devo gestire l'autenticazione forte del cliente?
Se vendi a clienti in aree che la richiedono, sì, e gli SDK moderni dei fornitori gestiscono la maggior parte del flusso. Ciò che devi gestire tu è l'esito: un ordine in attesa di autenticazione non è pagato, e trattarlo come pagato significa spedire merce mai incassata.
Come collaudo i pagamenti in sicurezza?
Ogni fornitore ha una modalità di test con carte che innescano esiti specifici: rifiuto, autenticazione richiesta, frode. Percorri l'elenco completo, casi scomodi della tabella qui sopra compresi. Poi fai una piccola transazione reale in produzione prima del lancio e rimborsala, perché la modalità di test non sollecita né le tue chiavi reali né il tuo URL di webhook reale.
integrazione gateway di pagamentopagamenti e-commercewebhookconformità pcisviluppo checkoutpagamenti online
