# Elements con log delle modifiche beta per l'API Checkout Sessions
Tieni traccia delle modifiche apportate all'integrazione beta di Elements con l'API Checkout Sessions.
> Questo documento contiene i registri delle modifiche relativi alle versioni beta di Elements con l’API Checkout Sessions.
>
> Questo registro delle modifiche non ti riguarda se utilizzi [Clover](https://docs.stripe.com/changelog/clover.md) o una versione successiva. Consulta invece il [registro delle modifiche](https://docs.stripe.com/changelog.md) di Stripe.
## Migrazione a Clover
### Modifiche a Clover
- (Breaking) Il metodo [stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) è ora sincrono anziché asincrono. In questo modo si riduce la latenza di rendering e si consente a Elements di mostrare prima i caricatori scheletrati. Per i dettagli sulla migrazione, consulta [Aggiorna initCheckout per renderlo sincrono](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md).
- (Breaking) I metodi di pagamento salvati vengono ora abilitati automaticamente in Payment Element quando configurati nella sessione di Checkout, senza richiedere ulteriori configurazioni lato client. Per ulteriori dettagli, consulta [Aggiornamenti al comportamento predefinito per i metodi di pagamento salvati](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md).
- (Breaking) I codici postali non vengono più raccolti automaticamente per i pagamenti con carta in Canada, Regno Unito e Porto Rico. Se ti affidi a questi dati, consulta la sezione [Rimozione del codice postale per i pagamenti con carta](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md).
- % badge color=“green” label=“Breaking” /%} Per le integrazioni React:
- I percorsi di importazione sono cambiati da `@stripe/react-stripe-js` a `@stripe/react-stripe-js/checkout`.
- [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) ora restituisce un’unione disgiunta che descrive lo stato asincrono (`{type: 'loading'}`, `{type: 'success', checkout: ...}`, o `{type: 'error', error: ...}`) anziché generare un errore.
- [CheckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) ora visualizza i figli incondizionatamente anziché renderli `null` quando [initCheckout](https://docs.stripe.com/js/custom_checkout/init) non va a buon fine.
### Aggiornamento di Clover
Prima di migrare a Clover, [aggiorna la tua integrazione](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-basil) a Basil.
- Se utilizzi pacchetti NPM Stripe, devi aggiornare `@stripe/stripe-js` ad almeno `8.0.0` e `@stripe/react-stripe-js` ad almeno `5.0.0`.
- Se carichi Stripe.js tramite il tag script, aggiorna il tag in riferimento a `clover` utilizzando la [nomenclatura Stripe.js con versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) come segue:
```html
Checkout
```
- Aggiorna la versione API almeno per il giorno `2025-09-30.clover` nella tua integrazione back-end.
#### HTML + JS
Aggiorna la tua integrazione come segue:
1. Rimuovi qualsiasi chiamata `await` o `.then()` associata a `initCheckout`.
1. Sostituisci la funzione `fetchClientSecret` con una stringa chiave privata client o Promise che risolve una stringa chiave privata client.
1. Chiama la nuova funzione asincrona `checkout.loadActions()` per accedere ad azioni quali `getSession()`, che sostituisce `session()`, o `confirm()`. È sufficiente chiamare `loadActions()` una sola volta.
1. Se in precedenza hai racchiuso `initCheckout` in un blocco `try...catch`, esamina invece il valore di `type` risolto di `loadActions()` per verificare la presenza di errori.
```javascript
const clientSecret = fetch("/create-checkout-session", {
method: "POST",
headers: { "Content-Type": "application/json" },
})
.then((r) => r.json())
.then((r) => r.clientSecret);
const checkout = stripe.initCheckout({
clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
const session = loadActionsResult.actions.getSession();
}
```
#### React
Aggiorna la tua dipendenza `@stripe/react-stripe-js` almeno all’ultima versione `5.0.0`. Se esegui l’aggiornamento da una versione precedente alla `4.0.0`, assicurati di leggere le [note di rilascio della v4.0.0](https://github.com/stripe/react-stripe-js/releases/tag/v4.0.0) per ulteriori passaggi di migrazione.
#### Importa modifiche
Aggiorna le tue importazioni per utilizzare il nuovo punto di ingresso specifico per il checkout:
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### Modifiche a CheckoutProvider e useCheckout
Sostituisci `fetchClientSecret` con `clientSecret`. Ora puoi eseguire il rendering degli elementi senza prima verificare se `useCheckout` ha restituito `type: 'success'`, il che riduce la latenza e consente agli elementi di mostrare prima i caricatori scheletrati.
```jsx
const App = () => {
const promise = useMemo(() => {
return fetch('/create-checkout-session', {
method: 'POST',
headers: { "Content-Type": "application/json" },
})
.then((res) => res.json())
.then((data) => data.clientSecret);
}, []);
return (
);
}
const CheckoutPage = () => {
const {type, ...rest} = useCheckout();
return (
);
}
```
Per ulteriori dettagli, consulta la voce del log delle modifiche [Aggiornamenti initCheckout per la sincronizzazione](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md).
## Migrazione a Basil
### Modifiche a Basil
- (Breaking) I metodi asincroni, ad esempio [confirm](https://docs.stripe.com/js/custom_checkout/confirm) o [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), vengono risolti con uno schema diverso:
- In caso di esito positivo, lo stato della sessione aggiornato viene compilato nella chiave `session`. In precedenza, questo si trovava nella chiave `success`.
- (Breaking) Ora viene generato un errore quando si specifica [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) su [confirm](https://docs.stripe.com/js/custom_checkout/confirm) quando [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) è già stato impostato nella sessione di Checkout.
- (Breaking) L’URL di reindirizzamento a cui l’utente veniva reindirizzato dopo che una conferma presentava parametri query incoerenti. I parametri aggiuntivi ora sono stati rimossi e l’URL contiene solo quanto specificato in [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) su [confirm](https://docs.stripe.com/js/custom_checkout/confirm) o [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) nella sessione di Checkout.
- (Breaking) Migliora la latenza dell’API Checkout Session per le sessioni in modalità abbonamento e corregge un bug che impediva ai clienti di aggiornare una sessione dopo il primo tentativo di pagamento.
- La modifica crea l’abbonamento dopo che l’utente ha completato il pagamento, pertanto `checkout_session.invoice` e `checkout_session.subscription` sono nulli fino al completamento della sessione di Checkout.
- Se attualmente utilizzi il campo `payment_intent.invoice` obsoleto, ti consigliamo di usare il webhook `checkout_session.completed`, che garantisce la presenza di una fattura, e `checkout_session.invoice` o [elenco di pagamento della fattura](https://docs.stripe.com/api/invoice-payment/list.md) per trovare la fattura associata.
- Per ulteriori informazioni, consulta il [Log delle modifiche API 2025-03-31.basil](https://docs.stripe.com/changelog/basil/2025-03-31/checkout-legacy-subscription-upgrade.md).
- È stata aggiunta [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) a [discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts) come opzione per visualizzare gli sconti.
### Aggiornamento di Basil
Prima di eseguire la migrazione a Basil, [aggiorna la tua integrazione](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog) a `custom_checkout_beta_6`.
- se utilizzi pacchetti Stripe NPM, devi prima eseguire l’upgrade di `@stripe/stripe-js` almeno a `7.0.0` e di `@stripe/react-stripe-js` almeno a `3.6.0`.
- Se stai caricando Stripe.js tramite il tag script e stai ancora utilizzando `v3` o `acacia`, aggiorna il tag in modo che faccia riferimento a `basil` utilizzando la [nomenclatura Stripe.js con versione](https://docs.stripe.com/sdks/stripejs-versioning.md) come segue:
```html
Checkout
```
- Rimuovi l’intestazione beta di Stripe.js all’inizializzazione di Stripe.js.
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- Rimuovi l’intestazione beta della versione dell’API e specifica che la versione dell’API deve essere almeno `2025-03-31.basil` nella tua integrazione del back-end.
### Before
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2026-04-22.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2025-03-31.basil' as any,
});
```
## Log delle modifiche beta
La versione beta di Elements con l’API Checkout Sessions utilizza due tipi di versioni beta:
- Un’intestazione beta Stripe.js (ad esempio, `custom_checkout_beta_6`), che viene impostata sull’integrazione front-end.
- Un’intestazione beta di versione API (ad esempio, `custom_checkout_beta=v1`), che viene impostata sull’integrazione back-end.
### Versioni beta front-end
Specifica la versione beta del front-end quando[inizializzi Stripe.js](https://docs.stripe.com/payments/quickstart-checkout-sessions.md).
#### custom_checkout_beta_6
Se utilizzi qualsiasi pacchetto Stripe NPM, devi prima aggiornare `@stripe/stripe-js` almeno a `6.1.0` e `@stripe/react-stripe-js` almeno a `3.5.0`.
- (Breaking) Il segno di [total.appliedBalance](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-appliedBalance) è stato invertito. Adesso un numero positivo aumenta l’importo da pagare mentre un numero negativo diminuisce l’importo da pagare.
- (Breaking) `clientSecret` sostituito con [fetchClientSecret](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret). Aggiorna l’integrazione per specificare una funzione asincrona che si risolve nella chiave privata client anziché specificare un valore statico.
- (Breaking) Elements è stato rinominato.
- Se utilizzi React Stripe.js, non devi fare altro che aggiornare `@stripe/react-stripe-js`.
- Se utilizzi HTML/JS:
- Utilizza `createPaymentElement()` anziché `createElement('payment')`
- Utilizza `createBillingAddressElement()` anziché `createElement('address', {mode: 'billing'})`.
- Utilizza `createShippingAddressElement()` anziché `createElement('address', {mode: 'shipping'})`.
- Utilizza `createExpressCheckoutElement()` anziché `createElement('expressCheckout')`.
- Utilizza `getPaymentElement()` anziché `getElement('payment')`.
- Utilizza `getBillingAddressElement()` anziché `getElement('address', {mode: 'billing'})`.
- Utilizza `getShippingAddressElement()` anziché `getElement('address', {mode: 'shipping'})`.
- Utilizza `getExpressCheckoutElement()` anziché `getElement('expressCheckout')`.
- (Breaking) Sono stati aggiornati i campi relativi alla conferma in modo che riflettano in modo più accurato lo stato della sessione.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) ora risponde a qualsiasi Billing Address Element o Shipping Address Element montato.
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) ora diventa `false` se è presente una conferma in transito.
- È stato rimosso `confirmationRequirements`.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) genera un errore se è stato specificato [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) durante la creazione della sessione di Checkout. Se vuoi precompilare un’email che il cliente può aggiornare, chiama `updateEmail` non appena viene caricata la pagina anziché specificare `customer_email`.
- (Breaking) [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) deve essere un URL assoluto, ovvero deve iniziare con `https://` anziché con un URL relativo, come `/success`.
- (Breaking) I campi delle tariffe sono stati aggiornati in un oggetto nidificato per facilitare il rendering.
- I valori numerici sono stati sostituiti con un oggetto contenente `amount` (una stringa di valuta formattata, ad esempio `$10.00`) e `minorUnitsAmount`, un numero intero che rappresenta il valore nell’unità più piccola della valuta. Se stai già leggendo l’importo, leggi invece da `minorUnitsAmount`.
- Ad esempio, sostituisci `total.total` con [`total.total.minorUnitsAmount`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-total-minorUnitsAmount).
- Devi leggere `total.total.amount` oppure singolarmente `total.total.minorUnitsAmount`, `currency` e `minorUnitsAmountDivisor` dall’oggetto `checkout` e visualizzarli nella tua interfaccia utente, altrimenti verrà generato un errore. In questo modo mantieni sincronizzata la tua pagina di pagamento man mano che la CheckoutSession si aggiorna, aggiungendo anche funzioni Stripe future, con modifiche minime al codice dell’interfaccia utente.
- Ora è possibile ottenere gli ID fiscali dei clienti. Scopri come [ottenere gli ID fiscali](https://docs.stripe.com/tax/checkout/tax-ids.md).
- Nella parte inferiore della pagina di pagamento è ora disponibile un assistente solo per la modalità di test, che offre indicazioni per la tua integrazione e scorciatoie per gli scenari di test più comuni.
#### custom_checkout_beta_5
- (Breaking) La funzione `initCustomCheckout` è stata rinominata [initCheckout](https://docs.stripe.com/js/custom_checkout/init)
- In di React Stripe.js, `CustomCheckoutProvider` è stato rinominato `CheckoutProvider` e `useCustomCheckout` è stato rinominato `useCheckout`.
- (Breaking) Per confermare Express Checkout Element, chiama [confirm](https://docs.stripe.com/js/custom_checkout/confirm), passando l’[evento di conferma](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) come `expressCheckoutConfirmEvent`.
- In precedenza, Express Checkout Element veniva confermato chiamando `event.confirm()`.
- (Breaking) Quando viene chiamato [confirm](https://docs.stripe.com/js/custom_checkout/confirm), Payment Element e Address Element convalidano gli input del modulo e visualizzano eventuali errori.
- (Breaking) I messaggi di errore sono stati standardizzati e migliorati.
- Gli errori restituiti/risolti da una funzione rappresentano scenari noti, come dati di pagamento non validi o fondi insufficienti. Si tratta di problemi prevedibili che possono essere comunicati al cliente visualizzando `message` nella pagina di pagamento.
- Gli errori generati/rifiutati da una funzione rappresentano errori nell’integrazione stessa, come parametri o configurazioni non validi. Questi errori non devono essere visualizzati dai clienti.
- (Breaking) I metodi asincroni, ad esempio [confirm](https://docs.stripe.com/js/custom_checkout/confirm) o [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code), vengono risolti con uno schema diverso:
- È stato aggiunto un campo discriminatore `type="success"|"error"`.
- In caso di esito positivo, lo stato aggiornato della sessione viene popolato nella chiave `success`. In precedenza, questa informazione era nella chiave `session`.
- In caso contrario, l’errore continua a essere popolato nella chiave `error`.
- Aggiunta delle opzioni `email`, `phoneNumber`, `billingAddress` e `shippingAddress` per [confirm](https://docs.stripe.com/js/custom_checkout/confirm).
- (Breaking) Address Element non aggiorna più automaticamente i campi [billingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-billingAddress) o [shippingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-shippingAddress) nell’oggetto Session.
- Finché Address Element è montato, i valori del modulo verranno utilizzati automaticamente durante la chiamata di [confirm](https://docs.stripe.com/js/custom_checkout/confirm).
- Ascolta l’[evento change](https://docs.stripe.com/js/element/events/on_change?type=addressElement) per utilizzare il valore di Address Element prima della conferma.
#### custom_checkout_beta_4
- Aggiunta di [immagini](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-images) all’[oggetto Session](https://docs.stripe.com/js/custom_checkout/session_object).
- Sono stati aggiunti i [campi](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields) come opzione durante la creazione di Payment Element.
- È stato aggiunto [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) come opzione durante la creazione di Express Checkout Element.
- (Breaking) Se specifichi opzioni non valide per [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element), viene generato un errore. In precedenza, le opzioni non riconosciute venivano ignorate automaticamente.
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) e [updatePhoneNumber](https://docs.stripe.com/js/custom_checkout/update_phone_number) applicano le modifiche in modo asincrono. La chiamata a questi metodi prima che il cliente finisca di inserire i valori completi potrebbe compromettere le prestazioni.
- Invece di chiamare `updateEmail` o `updatePhoneNumber` nell’evento di modifica di ogni input, attendi che il cliente completi l’inserimento, ad esempio quando l’utente fa clic al di fuori del campo di inserimento o quando invia il modulo per il pagamento.
- `updateEmail` verifica che l’input sia un indirizzo email formato correttamente e restituisce un errore se viene utilizzato un input non valido.
- `updatePhoneNumber` non esegue ancora alcuna convalida sulla stringa di input.
#### custom_checkout_beta_3
- I seguenti campi sono stati aggiunti all’[oggetto Session](https://docs.stripe.com/js/custom_checkout/session_object):
- [id](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-id)
- [livemode](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-livemode)
- [businessName](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-businessName)
- Le carte salvate ora possono essere riutilizzate. Scopri come [salvare e riutilizzare](https://docs.stripe.com/payments/checkout/save-during-payment.md) i metodi di pagamento.
- (Breaking) Il [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) predefinito di Payment Element è stato sostituito da `accordion`.
- Per continuare a utilizzare il layout predefinito precedente, devi specificare in modo esplicito `layout='tabs'`.
- (Breaking) Il comportamento predefinito di [confirm](https://docs.stripe.com/js/custom_checkout/confirm) è stato modificato in modo da reindirizzare sempre al tuo `return_url` dopo una conferma riuscita.
- In precedenza, `confirm` reindirizzava solo se il cliente sceglieva un metodo di pagamento con reindirizzamento. Per continuare a utilizzare il comportamento precedente, devi specificare [redirect=‘if_required’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) in `confirm`.
#### custom_checkout_beta_2
- (Breaking) Il campo `lineItem.recurring.interval_count` è stato rimosso e sostituito con [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount).
- (Breaking) Il campo `lineItem.amount` è stato rimosso e sostituito con il seguente:
- [lineItem.amountSubtotal](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountSubtotal)
- [lineItem.amountDiscount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountDiscount)
- [lineItem.amountTaxInclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxInclusive)
- [lineItem.amountTaxExclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxExclusive)
#### custom_checkout_beta_1
*Questa è la versione beta iniziale del front-end.*
### Versioni back-end
Specifica la versione beta del back-end quando [configuri la tua libreria server](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe).
*Non sono presenti modifiche alla versione beta del back-end.*