Integrazione del gateway di pagamento Stripe nel checkout (Progetto Aurora)

Trasforma un incarico parlato in un brief strutturato, pronto da consegnare.

Esempio di un output reale

Riassunto

Mark del team Pagamenti ha dettato un brief per collegare il gateway di pagamento Stripe al checkout dell'e-shop Progetto Aurora. L'obiettivo è sostituire l'attuale fatturazione manuale con il pagamento con carta online, con il supporto di Apple Pay e Google Pay. La scadenza per il rilascio in produzione è il 15 luglio, con un MVP sull'ambiente di staging entro la fine di giugno.

Verbale dettagliato

Cosa va costruito

L'obiettivo è aggiungere il pagamento con carta tramite Stripe al checkout esistente del Progetto Aurora. Dopo aver riempito il carrello, il cliente sceglie un metodo di pagamento e paga direttamente sulla pagina, senza essere reindirizzato a un gateway esterno. Mark ha sottolineato che il modulo di pagamento dovrebbe essere incorporato tramite Stripe Elements per restare all'interno del design dell'e-shop.

Oltre alla carta standard, vanno supportati Apple Pay e Google Pay, perché secondo l'analitica gli ordini da mobile rappresentano più della metà del traffico. Il pagamento in contanti e su fattura restano disponibili come alternative; Stripe è solo una terza opzione aggiuntiva.

Requisiti tecnici e misure di sicurezza

La conferma affidabile del pagamento è fondamentale. Lo stato dell'ordine non deve mai cambiare in base alla risposta del browser, ma esclusivamente tramite un webhook Stripe sul backend (l'evento payment_intent.succeeded). Mark ha messo esplicitamente in guardia contro la situazione in cui il cliente paga ma la connessione cade e l'ordine resta bloccato come non pagato.

Ogni chiamata deve essere idempotente (eseguirla di nuovo non crea un secondo pagamento) tramite un idempotency key. I webhook devono essere verificati tramite firma in modo che non possano essere falsificati. In caso di interruzione di Stripe è richiesto un fallback — il checkout non deve crollare del tutto; l'opzione carta viene semplicemente nascosta e vengono offerti i restanti metodi di pagamento.

Attività

Creare un endpoint backend per la creazione di un PaymentIntent con Stripe (importo, valuta, idempotency key). · responsabile team backend · scadenza entro il 27 giugno alta
Integrare Stripe Elements nel checkout del frontend (carta, Apple Pay, Google Pay) nel design dell'e-shop. · responsabile team frontend · scadenza entro il 30 giugno alta
Implementare un handler webhook per payment_intent.succeeded e payment_intent.payment_failed con verifica della firma. · responsabile team backend · scadenza entro il 27 giugno alta
Aggiungere un fallback: quando Stripe non è disponibile, nascondere il pagamento con carta e offrire contanti e fattura. · responsabile team frontend · scadenza entro il 3 luglio media
Preparare gli scenari di test (successo, errore della carta, interruzione del webhook, pagamento duplicato) sull'ambiente di staging. · responsabile Lucy (QA) · scadenza entro l'8 luglio media

Decisioni

Il modulo di pagamento verrà incorporato tramite Stripe Elements direttamente nel checkout, senza reindirizzamento a una pagina esterna. 💬 dalla trascrizione: „"Lo voglio all'interno, nello stesso design, non che sbalzi la persona su una pagina di terze parti."“
La conferma del pagamento è gestita dal webhook lato server payment_intent.succeeded, non dalla risposta del client. 💬 dalla trascrizione: „"La fonte di verità è il webhook sul backend, punto."“
Apple Pay e Google Pay fanno parte del primo MVP, non di una fase successiva. 💬 dalla trascrizione: „"Considera Apple Pay e Google Pay parte della base, non un bonus per dopo."“

Approfondimenti chiave

Lo stato dell'ordine è guidato esclusivamente dal webhook lato server, non dalla risposta del browser — questo protegge dalla perdita di un pagamento quando la connessione cade. 💬 dalla trascrizione: „"Mai, e dico mai, confermare un ordine in base a ciò che torna al browser. Solo in base al webhook sul server."“
Gli ordini da mobile rappresentano oltre il 50% del traffico, ed è per questo che Apple Pay e Google Pay fanno parte dell'MVP, non di una seconda fase. 💬 dalla trascrizione: „"Più della metà delle persone compra dal telefono, quindi Apple Pay e Google Pay devono esserci subito, non in un secondo momento."“
Se Stripe va in down, l'intero checkout non deve rompersi — viene nascosto solo il pagamento con carta e restano contanti e fattura. 💬 dalla trascrizione: „"Se Stripe va in down, non far crollare tutto il checkout. Nascondi semplicemente l'opzione carta e le persone pagano in un altro modo."“

Dati

15 luglio data Rilascio in produzione Scadenza per il lancio del gateway di pagamento in esercizio reale.
fine giugno data MVP su staging Un'integrazione funzionante pronta per i test.
alta priorità Priorità del compito Mark ha segnalato i pagamenti con carta come bloccanti per la campagna estiva.
oltre 50 % Quota degli ordini da mobile Il motivo per includere Apple Pay e Google Pay nell'MVP.

Punti non chiari / rischi

Non è specificato se debba essere supportato il salvataggio delle carte per i pagamenti ricorrenti (saved cards), oppure solo i pagamenti una tantum.
Mark non ha menzionato una soglia specifica per i rimborsi automatici (refund) — va definita con il team di supporto.
Non è stato indicato in quali valute si pagherà (solo CZK, oppure anche EUR per i clienti internazionali).

Brief per l'implementatore

Brief di implementazione — Integrazione del gateway di pagamento Stripe (Progetto Aurora)

Obiettivo

Aggiungere il pagamento con carta tramite Stripe al checkout esistente dell'e-shop Progetto Aurora, inclusi Apple Pay e Google Pay, come terzo metodo di pagamento accanto a contanti e fattura.

Ambito (scope)

Modulo di pagamento incorporato tramite Stripe Elements direttamente nel checkout (nessun reindirizzamento a un gateway esterno).
Supporto dei metodi di pagamento: carta, Apple Pay, Google Pay.
Conferma dei pagamenti lato server tramite webhook (fonte di verità = backend, non il browser).
Fallback quando Stripe non è disponibile (degradazione controllata senza far crollare l'intero checkout).

Fuori ambito (out of scope)

Salvataggio delle carte per i pagamenti ricorrenti (saved cards) — per ora non gestito, in attesa di una decisione.
Rimborsi tramite l'interfaccia di amministrazione — per l'MVP è sufficiente il rimborso tramite la Stripe Dashboard.

Requisiti funzionali

Creazione del pagamento
- L'endpoint backend crea un PaymentIntent (importo, valuta, idempotency_key).
- Il frontend richiede il client_secret e renderizza Stripe Elements.
Conferma del pagamento
- Lo stato dell'ordine viene modificato esclusivamente dal webhook payment_intent.succeeded.
- La risposta del client serve solo a mostrare la schermata di "grazie", mai a confermare l'ordine.
Fallimento del pagamento
- Webhook payment_intent.payment_failed → l'ordine resta nello stato "in attesa di pagamento" e il cliente ha la possibilità di riprovare.
Fallback
- Quando Stripe non è disponibile, il pagamento con carta viene nascosto e vengono mostrati contanti + fattura. Il checkout non deve crollare del tutto.

Requisiti non funzionali

Idempotency: ogni chiamata PaymentIntent usa un idempotency key (un nuovo invio non crea un secondo pagamento).
Sicurezza dei webhook: verifica della firma (Stripe-Signature), rifiuto delle richieste non verificate.
Secrets: le chiavi API di Stripe esclusivamente in GCP Secret Manager, mai nel codice né in un file .env su git.
Logging: ogni fallimento di pagamento e ogni webhook in entrata vanno nel structured logging (Cloud Logging).

Criteri di accettazione

Il cliente paga con carta e l'ordine viene segnato come pagato solo dopo la ricezione del webhook payment_intent.succeeded.
Apple Pay e Google Pay appaiono sui dispositivi supportati e funzionano end-to-end.
Se la connessione cade dopo il pagamento (browser chiuso), l'ordine viene comunque segnato come pagato grazie al webhook.
Inviare un pagamento due volte non crea due pagamenti (verificato tramite l'idempotency key).
Un webhook falsificato senza firma valida viene rifiutato (HTTP 400).
Durante un'interruzione simulata di Stripe, il checkout non si rompe — il pagamento con carta semplicemente scompare.

Scadenze

MVP su staging: fine giugno
Produzione: 15 luglio

Domande aperte

Salvataggio delle carte per i pagamenti ricorrenti — sì/no?
Valute: solo CZK, oppure anche EUR?
Soglia per il rimborso automatico?

Esempio di trascrizione

Mark (committente)

Bene, passiamo ai pagamenti. Voglio che finalmente integriamo il pagamento con carta tramite Stripe nel checkout di Aurora. Adesso la gente paga o in contanti alla consegna o su fattura, e questo ci rallenta.

Mark (committente)

La cosa importante è che resti all'interno, nello stesso design. Niente sbalzi su una pagina di terze parti. Lo incorporiamo tramite i loro Elements, così sembra parte dell'e-shop.

Mark (committente)

E ora la parte più importante. Mai, e dico mai, confermare un ordine in base a ciò che torna al browser. Solo in base al webhook sul server. Abbiamo già avuto un caso in cui una persona ha pagato, le è caduta la connessione e l'ordine è rimasto appeso come non pagato. Non deve più succedere.

Mark (committente)

Considera Apple Pay e Google Pay parte della base, non un bonus per dopo. Più della metà delle persone compra dal telefono, quindi deve esserci subito.

Mark (committente)

E un'altra cosa. Se Stripe va in down, non far crollare tutto il checkout. Nascondi semplicemente l'opzione carta e le persone pagano in un altro modo. Non voglio perdere un'intera vendita per un'interruzione del gateway.

Mark (committente)

In definitiva lo voglio in produzione entro il 15 luglio, per la campagna estiva. Su staging facciamo in modo che funzioni entro la fine di giugno, così Lucy ha abbastanza tempo per provarlo per bene.

Prova Voxibly