Risorse · 47
Pagamenti incerti: recupero del checkout senza ordini duplicati
Riconciliare ritardi di rete, resi del browser, notifiche e stato aziendale anziché considerare un singolo segnale come sufficiente.
Aggiornato · 4 min
Obiettivi di questa guida
- Separare tentativo, pagamento e ordine
- Gestire resi ritardati o mancanti
- Eliminare notifiche e richieste duplicate
- Spiegare l'incertezza senza chiedere agli utenti di pagare di nuovo
Verifica rapida
- Quale fonte conferma il pagamento?
- La chiusura del browser modifica lo stato aziendale?
- Un evento ripetuto prepara due ordini?
- Vengono verificate le firme degli eventi?
- Come fa l'assistenza a individuare un'operazione incerta?
Metodo passo passo
- 1
Definire gli stati
Separare carrello, tentativo, autorizzazione, pagamento confermato, ordine e rimborso. Scrivere transizioni, fonte autorevole e azioni consentite. Seguire il fornitore effettivo e i metodi di pagamento; non tutti i metodi confermano immediatamente.
Risultato: diagramma di stato e contratto commerciale.
- 2
Identificare l'operazione
Collegare un tentativo a un ordine e agli identificativi del fornitore. Utilizzare la regola di idempotenza documentata per la ripetizione della stessa operazione. Un nuovo scopo o parametri modificati richiedono una decisione esplicita anziché un riutilizzo cieco delle chiavi.
Risultato: identità stabile e regole di recupero.
- 3
Gestire il ritorno del browser
Visualizzare lo stato da un controllo lato server appropriato al fornitore. Un reindirizzamento a una pagina di successo da solo non costituisce prova di pagamento. Gestire un browser chiuso, un ritorno mancante, un'autenticazione interrotta e una rete lenta.
Risultato: percorso di ritorno e messaggi per stato.
- 4
Verifica delle notifiche
Verifica l'autenticità in base alla documentazione del fornitore, registra l'identità dell'evento e gestisci le ripetizioni senza effetti duplicati. Gli eventi possono essere in ritardo o fuori sequenza. Se necessario, recupera l'oggetto di riferimento prima di una transizione irreversibile.
Risultato: traccia del gestore testato e priva di dati bancari.
- 5
Riconcilia le discrepanze
Confronta le operazioni, gli ordini e l'evasione degli ordini del fornitore. Isola i pagamenti senza ordine, gli ordini senza conferma, le doppie elaborazioni e i rimborsi non propagati. Assegna a ciascuna discrepanza un responsabile e una procedura; non ripetere automaticamente un addebito incerto.
Risultato: coda di riconciliazione e decisioni.
- 6
Testa il ripristino completo
Nella modalità di test del fornitore, riproduci timeout, duplicati, eventi ritardati, ordini annullati e resi mancanti. Verifica una transizione aziendale, correggi le informazioni del cliente e la visibilità del supporto. I dettagli sull'idempotenza variano a seconda del fornitore. Risultato atteso (
): prove di non duplicazione e criteri di implementazione.
Esempio pratico fittizio
Situazione illustrativa
Situazione esemplificativa: il pagamento va a buon fine, ma il cliente perde la connessione prima della conferma e successivamente arrivano due notifiche.
Decisione e prove attese
Un ordine viene confermato. Il recupero mostra lo stato verificato e l'assistenza può riconciliare il riferimento senza richiedere i dati bancari.
Distinguere i meccanismi
| Meccanismo | Scopo | Verifica o limitazione |
|---|---|---|
| Ritorno del browser | Informare e riprendere l'interfaccia | Può essere mancante o interrotto |
| Webhook verificato | Ricevere una modifica dello stato del fornitore | Può essere ripetuto, ritardato o fuori ordine |
| Riconciliazione del server | Confrontare lo stato del pagamento e dell'ordine | Necessita di una regola di risoluzione delle discrepanze |
Indicatori di gestione
| Indicatore | Cosa misura | Prima azione |
|---|---|---|
| Stati incerti | Operazioni non risolte entro il ritardo previsto | Verificare lo stato di riferimento |
| Effetti duplicati | Ordini o elaborazioni eseguiti due volte | Correggere la deduplicazione aziendale |
| Lacune chiuse | Casi riconciliati con decisione e prove | Gestire i casi più vecchi e critici |
Errori comuni
- Conferma solo da un URL di successo
- Trattare il timeout come errore di pagamento
- Supponendo che gli eventi arrivino in ordine
- Ripetizione di un addebito prima della verifica
Domande frequenti
Un timeout significa errore?
No. Significa che la risposta non è stata ricevuta entro il tempo limite. Verificare lo stato dell'operazione prima di crearne un'altra.
L'idempotenza del fornitore è sufficiente?
No. La creazione, l'evasione e le notifiche degli ordini devono tollerare anche elaborazioni ripetute senza effetti duplicati sul business.
Cosa si dovrebbe comunicare all'utente?
Spiegare che la verifica è in corso, fornire un riferimento sicuro e un modo per recuperare lo stato. Evitare di richiedere un altro pagamento mentre il precedente è incerto.
Quali prove conservare per una verifica utile?
Conservare identificativi non sensibili, stati e prova di un solo effetto operativo. Collegare i tentativi al contratto API, non solo al timeout.
Webhook: firme e ripetizioni
Le note dettagliate di questa edizione sono disponibili in inglese.
A payment notification does not close reconciliation by itself
Authenticate each webhook, bind it to the right account and compare its effect with authorised server state. A repeated event must not repeat an initial activation; missing events must remain detectable.
- Separate notification identity from the operation to perform.
- Test overlapping manual resend and automatic retry.
- Retain uncertainty after an unknown external result and check the source before retrying.
See webhook signatures, digests and the ten cases →
Sources reviewed on · Stripe · Webhooks · Stripe · Manage webhook endpoints · GitHub · Validating webhook deliveries · GitHub · Best practices for using webhooks · GitHub · Handling failed webhook deliveries
Precisione importi API e unità esatte
Le note dettagliate di questa edizione sono disponibili in inglese.
Separate exact conversion from payment confirmation
An interface can display the correct price while preparing an incorrect provider integer. Acceptance must reconcile the server amount with the operation contract, then check confirmed state without mistaking arithmetic for completed payment.
- Test zero-, two- and three-decimal currencies.
- Include a case where step cannot be inferred from decimals.
- Retain an exact reference before localised formatting.
Check a unit in the workshop →
Adyen · Currency codes and minor units · Provider documentation · reviewed 2026-11-06
Stripe · Supported currencies and special cases · Provider documentation · reviewed 2026-11-06
Riferimenti ufficiali
I riferimenti supportano il metodo. Adattare i controlli al proprio contesto; non costituiscono una certificazione. I titoli dei riferimenti originali e i documenti di origine potrebbero essere in un'altra lingua.
Riferimenti consultati il .
- Stripe — Payment status updates
- Stripe — Webhooks
- Stripe — Idempotent requests
- Stripe · Manage webhook endpoints
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- Adyen · Currency codes and minor units
- Stripe · Supported currencies and special cases
