Passa al contenuto principale

Introduzione alle Checkout APIs

Le Checkout APIs rappresentano il punto di arrivo dell'esperienza utente sui siti Webround. Questo modulo gestisce la transizione dal carrello alla transazione finanziaria vera e propria, orchestrando la comunicazione tra i dati del tuo store e l'infrastruttura di pagamento di Stripe.

L'obiettivo di queste API è trasformare un'intenzione d'acquisto in un ordine confermato, garantendo che ogni aspetto (fiscale, logistico e promozionale) sia validato prima che l'utente concluda la transazione.

Filosofia del Checkout: Redirect & Automazione​

Webround adotta un approccio redirect-based per massimizzare la sicurezza e ridurre il carico di conformità (PCI-DSS) sui tuoi sistemi.

  • Sessione Dinamica: L'API non processa direttamente il pagamento, ma genera una Stripe Checkout Session sicura. Restituisce un URL univoco a cui il frontend deve reindirizzare l'utente. Da questo punto in poi, Webround non lavora attivamente sull'ordine, ma ascolta solo gli eventi che riguardano quella Checkout Session ed eventuali subscriptions o invoices generate da Stripe per quel payment_intent.
  • Gestione Stato: Una volta completato il pagamento sul dominio protetto di Stripe, l'utente viene riportato sul sito, alla pagina home. Nel frattempo, Webround si occupa di sincronizzare l'ordine in background grazie alla ricezione degli eventi da Stripe.

Webhooks e Sincronizzazione Real-time​

Il cuore dell'affidabilità di Webround risiede nella gestione degli eventi asincroni. Ogni pagamento che passa per Stripe genera eventi dettagliati che ascoltiamo per conto tuo, grazie all'integrazione Stripe Connect. Il merchant deve solo eseguire l'onboarding su Stripe tramite Webround per abilitare l'ascolto di eventi per lo specifico store.

Ciclo di Vita dell'Ordine​

Webround avvia la sessione di checkout per conto del merchant. Questo significa che la semplice generazione dell'URL di checkout comporta la creazione immediata di un ordine nel database con stato di default created. L'ordine non attende il pagamento per esistere; esiste dal momento in cui l'utente manifesta l'intenzione di acquisto.

Se l'utente finalizza l'operazione, l'ordine evolve in base ai segnali inviati da Stripe. Webround sincronizza gli eventi in tempo reale e impiega misure rigorose (idempotenza e versioning) per evitare il replay accidentale di eventi, assicurando che i dati processati siano sempre i più recenti e che non vengano mai sovrascritti da notifiche obsolete.

suggerimento

Anche in casi di errore temporanei, brevi downtime o problemi imprevisti, Webround organizza gli eventi tramite code. La prima operazione è la conservazione dell'evento da Stripe. Successivamente, i sistemi interni li processano. In caso di problemi, le code riproveranno il processing degli eventi "fermi".

1. Native Stripe Webhooks​

Webround ascolta nativamente i server di Stripe. La ricezione dell'evento checkout.session.completed comporta quasi sempre il passaggio allo stato paid, ma il sistema gestisce l'intera macchina a stati di Stripe:

  • created: Stato iniziale predefinito. La sessione è aperta, l'ordine è registrato ma non ancora processato.
  • pending: Il pagamento è stato avviato ma è in attesa di conferma (es. bonifici o pagamenti asincroni che richiedono tempi tecnici).
  • authorized: Tipico dei flussi di pre-autorizzazione. I fondi sono bloccati sulla carta del cliente ma non ancora riscossi dal merchant.
  • partially_funded: Utilizzato in scenari di pagamenti frazionati o depositi parziali dove l'importo totale non è ancora stato coperto.
  • paid: Il pagamento è stato confermato e riscosso con successo.
  • failed: Il pagamento è stato rifiutato (es. carta declinata o errore tecnico su Stripe).
  • canceled: Questo stato viene impostato automaticamente quando un checkout viene abbandonato per un po' di tempo.
Nota importante

Webround non permette di alterare manualmente gli ordini sincronizzati con Stripe per garantirne l'integrità fiscale. Le uniche modifiche permesse al merchant riguardano la logica di spedizione (aggiornamento dello stato di spedizione e inserimento dell'URL di tracking).

2. Integrazioni Custom e Autonomia del Merchant​

Oltre alla gestione nativa, Webround garantisce al merchant la massima flessibilità:

  • Webround Webhooks: Puoi configurare il tuo backend per ricevere notifiche "pulite" ed elaborate da Webround ogni volta che un ordine cambia stato.
  • Autonomia su Stripe: Essendo un'integrazione basata su Stripe Connect in modalità standard, mantieni l'accesso totale alla dashboard di Stripe. Puoi collegare i tuoi sistemi esterni (es. gestionali, sistemi di licenze, CRM) direttamente ai webhook di Stripe per attivare logiche proprietarie in totale autonomia, senza alcuna interferenza da parte dei processi di Webround.

Business Logic e Validazione Preventiva​

Per evitare che una sessione di pagamento fallisca o generi errori fiscali, le Checkout APIs eseguono una serie di controlli rigorosi. Se i requisiti non sono soddisfatti, l'API restituisce un errore 400 (Bad Request) spiegando il motivo.

1. Requisiti di Identità e Sicurezza​

  • Verifica Email: Per gli utenti registrati, l'email deve essere verificata. Questo garantisce la validità legale delle fatture emesse e riduce i rischi di frode.
  • Prodotti Ricorrenti: Il checkout di abbonamenti (recurring) richiede obbligatoriamente che l'utente sia autenticato (non è permesso il guest checkout per le sottoscrizioni).

2. Coerenza del Carrello​

Il sistema impedisce la creazione di sessioni ibride che Stripe non potrebbe processare:

  • Valuta Unica: Tutti gli articoli nel carrello devono condividere lo stesso currencyCode.
  • Cadenza Uniforme: Non è possibile mischiare prodotti con frequenze di fatturazione diverse (es. un abbonamento mensile e uno annuale) nello stesso checkout.

3. Logistica e Fiscalità (Tax & Shipping)​

Il calcolo delle tasse è dinamico e basato sulla destinazione:

  • Shipping Country: Per i prodotti fisici, il paese di destinazione è un dato mandatorio. Senza di esso, il sistema non può risolvere la Tax Zone corretta né calcolare le spese di spedizione.
  • Disponibilità: Se il paese scelto non ha metodi di spedizione configurati nel back-office dello store e il prodotto prevede una spedizione, il checkout viene bloccato preventivamente.

4. Motore Promozionale​

I codici sconto vengono validati in tempo reale verificando:

  • Limiti di Utilizzo: Scadenza temporale, tetto massimo di utilizzi globali o limiti per singolo cliente.
  • Compatibilità: Esclusione di specifici prodotti o varianti che il merchant ha deciso di non scontare.

Autenticazione e Contesto​

  • Store Context: Ogni richiesta richiede l'header store-id per caricare le configurazioni fiscali e i conti Stripe connessi corretti.
  • Customer Context: Se presente, il token di autenticazione del cliente viene usato per applicare limiti d'uso dei coupon personali e abilitare l'attivazione di sottoscrizioni.

Note importanti e FAQ​

È supportato il checkout anonimo?​

Un utente che non si è mai registrato sul tuo sito Webround può acquistare direttamente senza problemi: l'intero flusso di pagamento è orchestrato tramite Stripe. Webround raccoglie solo i dati fondamentali:

  • Quali sono gli articoli dell'ordine
  • Email del cliente
  • Indirizzo di fatturazione
  • Indirizzo di spedizione se prevista

Vincolo Tecnico: Se il carrello contiene prodotti in abbonamento (recurring), il checkout anonimo non è consentito. In questo caso l'API restituirà un errore 400 poiché l'autenticazione è obbligatoria per gestire le ricorrenze.

Dove sono conservati i metodi di pagamento dei clienti?​

Webround non conserva mai i dettagli dei metodi di pagamento del cliente. È tutto conservato su Stripe. Assicurati di utilizzare lo Stripe Customer Portal URL (configurabile nelle impostazioni del tuo store) per dare ai tuoi clienti un punto di accesso per la gestione dei propri ordini, abbonamenti e metodi di pagamento.

Perché ricevo un errore di configurazione risorsa (Stripe resource configuration error)?​

Questo errore avviene solo se la configurazione dello SKU è incompleta o incoerente. Se un prodotto ha un normale prezzo su Webround senza opzioni Stripe avanzate, tutto fila liscio. Il blocco scatta solo se:

  • Hai inserito un Product ID senza il relativo Price ID (o viceversa).
  • Hai abilitato "Utilizza Stripe Tax" senza fornire il Tax Code ID.
  • Hai abilitato "Utilizza Stripe Tax" senza aver configurato correttamente il Product ID, il Price ID oppure il Tax Code ID.

Le fatture inviate da Stripe sono conformi alle leggi?​

In generale, le fatture di Stripe sono solo prove di documentazione tecnica di avvenuto pagamento. Non prevedono, a meno di integrazioni terze o personalizzate, almeno in Italia, la conformità fiscale al 100%.

Un cliente estero è soggetto a Reverse Charge. Come faccio ad evitare il pagamento dell'IVA per quel cliente?​

Ti basta impostare il flag di esenzione IVA nel profilo del cliente in Webround Commerce. Ricordati di farlo anche su Stripe.

Posso effettuare un rimborso da Webround?​

No, Webround è solo uno specchio sincronizzato con quello che avviene su Stripe. Qualsiasi operazione venga effettuata, che sia uno storno con nota di credito, un rimborso o una disputa, passa direttamente per Stripe.

Webround gestisce le aliquote fiscali su scala globale?​

Puoi impostare le tue aliquote tramite le Tax Zones e gestire tutto quello che serve. Se una Tax Zone non è presente per il paese di acquisto, il prezzo finale al checkout corrisponderà al prezzo netto inserito in Webround. Attenzione: Per calcolare le tasse sui prodotti fisici è indispensabile che il cliente fornisca il paese di destinazione, altrimenti l'API restituirà un errore 400.

Posso integrare Stripe Tax?​

Sì, Webround ti permette di integrare Stripe Tax delegando il calcolo dell'aliquota a Stripe. Dovrai gestire questo per singolo SKU inserendo Tax Code ID, Product ID e Price ID. Vincolo di compatibilità: Non puoi mischiare nello stesso carrello prodotti Stripe Tax e prodotti con calcolo tasse manuale Webround; il sistema bloccherà il checkout con un errore 400 per evitare conflitti nel calcolo del totale.

Quali sono i limiti del carrello?​

Per motivi di performance e limiti imposti dai gateway di pagamento, il carrello ha dei vincoli strutturali:

  • Quantità: Massimo 20 articoli per prodotti ricorrenti e 100 per prodotti una tantum.
  • Coerenza: Tutti gli articoli devono avere la stessa valuta e, nel caso di abbonamenti, la stessa cadenza di fatturazione.

Perché il mio codice promozionale non funziona?​

I coupon sono soggetti a validazioni rigorose. Un codice può essere respinto se è scaduto, se ha raggiunto il limite di utilizzi (globali o per cliente), se l'ordine non raggiunge l'importo minimo o se stai tentando di combinare un codice "esclusivo" con altri sconti o se il prodotto/variante è esplicitamente escluso.

Cos'è il Tax Rate ID?​

Il Tax Rate ID è un identificativo che puoi salvare all'interno di una Tax Zone o sull'aliquota di default del prodotto (il consiglio è di ragionare sempre per Tax Zone). Questo ID si mappa direttamente a un Tax Rate creato sulla tua dashboard di Stripe.

Configurare correttamente il Tax Rate ID permette a Stripe di compilare il campo IVA nelle sue ricevute con la dicitura e l'aliquota corretta. È importante distinguere due scenari:

  • Se usi Stripe Tax: Non è necessario configurare questo campo, poiché Stripe gestisce tutto in autonomia.
  • Se usi il calcolo manuale di Webround: Webround calcola l'aliquota in base alla Tax Zone per determinare il totale dell'ordine. Il Tax Rate ID serve "solo" a rendere l'invoice di Stripe più pulita e professionale, riportando esplicitamente il quantitativo di IVA applicato.

Consiglio: Ti suggeriamo di inserirlo sempre. In caso contrario, l'ordine su Stripe riporterà comunque il totale corretto comprensivo di IVA, ma non apparirà il campo esplicito "IVA" nella scomposizione del prezzo sulla ricevuta di Stripe.