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

Laboratorio di analisi immaginario vuoto: tre blocchi in ottone, quadrante vuoto, fogli e cartella bordeaux Illustrazione editoriale generata con IA

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. 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. 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. 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. 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. 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. 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

MeccanismoScopoVerifica o limitazione
Ritorno del browserInformare e riprendere l'interfacciaPuò essere mancante o interrotto
Webhook verificatoRicevere una modifica dello stato del fornitorePuò essere ripetuto, ritardato o fuori ordine
Riconciliazione del serverConfrontare lo stato del pagamento e dell'ordineNecessita di una regola di risoluzione delle discrepanze

Indicatori di gestione

IndicatoreCosa misuraPrima azione
Stati incertiOperazioni non risolte entro il ritardo previstoVerificare lo stato di riferimento
Effetti duplicatiOrdini o elaborazioni eseguiti due volteCorreggere la deduplicazione aziendale
Lacune chiuseCasi riconciliati con decisione e proveGestire 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 .