Si consideri un checkout in cui il pagamento va a buon fine ma l'aggiornamento dell'ordine fallisce. Il cliente vede un errore e riprova. Nel frattempo, l'assistenza ha una registrazione della transazione, il magazzino non ha alcun ordine confermato e il reparto finanziario deve sapere se il cliente debba qualcosa.

Quale sistema dovrebbe risolvere la situazione? Incidenti come questo sono il punto in cui le decisioni architetturali diventano visibili: quando la proprietà non è definita, ogni occorrenza riceve una correzione costruita ad hoc, e quelle correzioni tendono ad accumularsi dove è più facile scriverle.

Un'architettura dovrebbe rispondere a questa domanda prima che la prima transazione arrivi in produzione. Diversamente, il codice di pagamento assorbe gradualmente il recupero degli ordini, le regole degli abbonamenti, le rettifiche delle fatture e le decisioni di evasione.

Il modello di proprietà delineato di seguito offre un punto di partenza pratico: mantenere il gateway concentrato sulla comunicazione con il provider, dare alle operazioni di pagamento una sede propria e lasciare le decisioni commerciali a fatturazione e ordini.

Partire con Quattro Responsabilità, Non Tre

Per questo design, distinguere il payment gateway dal più ampio servizio di pagamento. Il modello utilizza quattro confini logici che coprono il gateway, il servizio di pagamento, la fatturazione e gli ordini.

Trattarli come confini di proprietà, non come un'istruzione a distribuire quattro microservizi. Partire con moduli all'interno di un'unica applicazione va bene se si adatta al team. In ogni caso, le responsabilità dovbero essere rese esplicite.

Quando si esamina l'architettura di un payment gateway, abbinare il diagramma dei componenti a una mappa delle decisioni: chi decide l'importo, chi richiede l'incasso, chi registra l'esito e chi autorizza la successiva azione commerciale?

Mantenere il Gateway Vicino al Provider

Dare al gateway un contratto ristretto. Dovrebbe accettare un'operazione di pagamento supportata, tradurla nel formato del provider e restituire un risultato che il servizio di pagamento possa interpretare.

L'isolamento ha una motivazione pratica: i provider di pagamento differiscono per API, schemi di autenticazione, formati dei campi e meccanismi di notifica, e consolidare questa variazione in un unico livello tiene il resto del sistema isolato dalle specificità del provider.

Assegnargli responsabilità come:

• Validare la richiesta rivolta al provider
• Autenticare la comunicazione con il provider
• Tradurre i campi interni in campi specifici del provider
• Verificare le notifiche in arrivo dal provider
• Mappare le risposte conservando i dettagli utili del provider

La conoscenza del prodotto resta fuori da quel contratto. Il gateway non dovrebbe dover capire livelli fedeltà, idoneità alla spedizione, periodi di grazia degli abbonamenti o bundle promozionali. Passargli l'importo approvato, la valuta, il riferimento del pagamento e le informazioni richieste sul metodo di pagamento—non le regole che li hanno prodotti.

Una domanda di revisione utile: modificare la politica di reso richiederebbe modifiche al codice del gateway? In tal caso, riconsiderare il confine.

Dare alle Operazioni di Pagamento un Proprietario Separato

I tentativi di pagamento e i loro esiti appartengono al servizio di pagamento. Per ogni tentativo, registrare un identificatore interno, i riferimenti pertinenti al provider, l'importo richiesto, la valuta, il tipo di operazione e lo stato. Conservare storia sufficiente per indagare su ciò che è stato richiesto e su ciò che è stato effettivamente confermato.

Evitare di ridurre il modello a un singolo flag "paid". Definire invece le distinzioni di cui i flussi di lavoro hanno bisogno, compresi gli esiti non risolti. La comunicazione con il provider è a volte genuinamente incerta—timeout, notifiche in ritardo e aggiornamenti fuori sequenza sono routine—quindi il modello di stato ha bisogno di spazio per l'ambiguità anziché comprimere ogni esito in successo o fallimento.

Progettare esplicitamente per questa sequenza ipetica: il servizio di pagamento richiede un'autorizzazione, la richiesta raggiunge il provider e la risposta va persa. L'applicazione deve quindi decidere cosa fare dopo. Un timeout non dovrebbe mai attivare automaticamente un nuovo addebito. Richiedere al servizio di pagamento di risolvere o gestire in sicurezza il tentativo originale prima di consentire un'altra operazione.

Anche due tipi di retry dovrebbero essere separati:

• Retry tecnico: ripetere la comunicazione per la stessa operazione prevista secondo regole di sicurezza definite.
• Retry di incasso: effettuare un nuovo tentativo di riscossione di un saldo outstanding.

Assegnare la gestione dei retry tecnici al design dell'integrazione dei pagamenti. La fatturazione determina tempistica e idoneità dell'incasso, con il servizio di pagamento che esegue il tentativo approvato.

Lasciare alla Fatturazione la Decisione su Ciò Che è Dovuto

La fatturazione possiede l'obbligazione finanziaria: il calcolo dell'addebito, la fattura, i crediti e il saldo residuo. Per un prodotto in abbonamento, le regole per cambi di piano, pro-rata, periodi di fatturazione e calendari di incasso appartengono a questo dominio.

Richiedere alla fatturazione di emettere ogni richiesta di incasso con un importo esplicito, una valuta e un riferimento all'obbligazione oggetto di incasso. Il servizio di pagamento riporta l'esito, e la fatturazione determina quindi come quell'esito influisce sul saldo.

Si consideri un'ipotetica fattura di $100 con un credito di $30. La fatturazione dovrebbe richiedere i restanti $70. Non si dovrebbe mai chiedere al gateway di ricostruire quel calcolo dai metadati dell'abbonamento.

La posta in gioco cresce con la complessità dei prezzi: ogni calcolo che finisce nel componente sbagliato diventa logica che dovrà poi essere trovata, migrata e riconciliata tra i sistemi.

La stessa disciplina si applica dopo un rimborso. Le registrazioni dei pagamenti stabiliscono ciò che è stato restituito tramite il provider; la fatturazione determina quale fattura o rettifica del saldo corrisponde a quel reso.

Lasciare agli Ordini la Decisione su Ciò Che Accade all'Acquisto

Le decisioni di evasione e ciclo di vita dell'acquisto restano al dominio degli ordini. Il servizio di pagamento dovrebbe pubblicare un esito di pagamento, non emettere un'istruzione al magazzino, e il flusso degli ordini dovrebbe interpretare quell'esito insieme ai propri altri requisiti. Interpretare l'esito è un giudizio commerciale tanto quanto tecnico, poiché lo stesso pagamento confermato può avere un peso diverso per diversi modelli di evasione.

Un esempio di regola di evasione esplicita: rilasciare l'ordine solo quando la condizione di pagamento richiesta è soddisfatta, l'inventario è allocato e ogni revisione richiesta è completata. La condizione di pagamento dovrebbe essere scelta in base al modello di business e mai nascosta all'interno di un handler di risposta del provider.

Anche gli annullamenti meritano la stessa separazione. Gli ordini decidono se l'annullamento è consentito e cosa debba accadere all'acquisto, poi richiedono l'operazione di pagamento appropriata tramite il servizio di pagamento. Evitare un comando "cancel" sovraccarico che potrebbe significare annullare l'ordine, rilasciare un'autorizzazione, rimborsare un pagamento o terminare un abbonamento. Nominare ogni azione con precisione.

Coordinare i Rimborsi Senza Dare a un Sistema Tutti i Compiti

Un flusso di rimborso è un buon test della solidità dei confini. Si supponga che un cliente restituisca un articolo da un ordine di tre articoli. Strutturare il flusso in modo che:

• Il componente resi o ordini approvi il reso.
• Il proprietario designato del calcolo commerciale determini l'importo rimborsabile.
• Il servizio di pagamento verifichi la cronologia dei pagamenti e i limiti operativi applicabili.
• Il gateway invii la richiesta al provider.
• Il servizio di pagamento registri l'esito confermato o non risolto.
• Fatturazione e ordini aggiornino di conseguenza le proprie registrazioni.

Assegnare un unico proprietario a ciascun calcolo. Fatturazione e ordini non dovrebbero calcolare indipendentemente importi di rimborso diversi e lasciare ai pagamenti la scelta tra i due.

Mantenere "rimborso richiesto" separato da "rimborso confermato". Se l'esito del provider non è risolto, conservare quell'incertezza e prevedere un percorso di indagine anziché marcare l'intero flusso come completato.

Rendere il Recupero Parte del Contratto

Ogni operazione transfrontaliera dovrebbe specificare più della risposta di successo. Documentare:

• Come vengono identificate le richieste ripetute
• Quale componente possiede lo stato autorevole
• Come vengono gestite le notifiche tardive o duplicate
• Cosa accade quando il componente successivo non è disponibile
• Come il personale indaga sugli esiti non risolti
• Quali azioni possono essere ripetute sicurezza

Per le richieste ripetute in particolare, i provider offrono comunemente meccanismi di idempotenza progettati esattamente per questo scopo, consentendo di reinviare la stessa operazione senza che venga eseguita due volte.

Dare a ciascun dominio i propri identificatori e collegarli esplicitamente: order ID, invoice ID, payment ID, attempt ID e riferimento del provider. Non forzare un solo identificatore a rappresentare ogni relazione.

Il personale di assistenza può ricevere una timeline combinata, ma le correzioni dovrebbero restare sotto il controllo del componente proprietario. Una dashboard comoda non dovrebbe diventare il permesso di sovrascrivere la cronologia dei pagamenti o alterare silenziosamente i saldi delle fatture.

Verificare i Confini con i Cambiamenti di Business

Prima di approvare il design, percorrire diversi cambiamenti:

• Aggiungere un provider di pagamento senza modificare le regole di prezzo.
• Cambiare i tempi di incasso degli abbonamenti senza modificare gli adapter del gateway.
• Introdurre resi parziali senza riscrivere la gestione delle notifiche del provider.
• Cambiare la politica di evasione senza alterare le definizioni di stato dei pagamenti.

Trattare i cambiamenti transversali inattesi come segnali di revisione. Alcun coordinamento è legittimo; l'accoppiamento inspiegato merita attenzione.

La deriva delle responsabilità raramente si annuncia; si accumula una modifica opportunistica alla volta. Ripetere queste walkthrough ogni volta che si introduce un nuovo provider, metodo di pagamento o modello di prezzo mantiene i confini espliciti molto dopo la revisione iniziale del design.

Il gateway dovrebbe finire alla comunicazione di pagamento rivolta al provider. Il servizio di pagamento dovrebbe possedere l'esecuzione e le evidenze dei pagamenti. La fatturazione dovrebbe possedere obbligazioni e saldi. Gli ordini dovrebbero possedere l'acquisto e la sua evasione.

Scrivere quelle responsabilità nelle interfacce, nelle procedure di recupero e nella proprietà dei team. Un diagramma da solo non li manterrà separati.