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.

Avviso

Questo documento contiene i registri delle modifiche relativi alle versioni beta di Elements con l’API Checkout Sessions.

Se fai già parte della release di Basil di Elements con l’API Checkout Sessions, questo documento non ti riguarda.

Migrazione a Basil

Modifiche

Breaking I metodi asincroni, ad esempio confirm o applyPromotionCode, 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 su confirm quando 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 su confirm o 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 per trovare la fattura associata.
- Per saperne di più, consulta il Log delle modifiche API.
È stata aggiunta percentOff a discountAmounts come opzione per visualizzare gli sconti.

Aggiornamento

Prima di eseguire la migrazione a Basil, aggiorna la tua integrazione 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 carichi Stripe.js tramite il tag script, aggiorna il tag dello script in modo per utilizzare Stripe.js con versioni numerate sostituendo il tag come segue:

checkout.html
<head>
 <title>Checkout</title>
 <script src="https://js.stripe.com/v3"></script>
 <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Rimuovi l’intestazione beta di Stripe.js all’inizializzazione di Stripe.js.

checkout.js
const stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);

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.

Prima

Dopo

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 es. custom_checkout_beta_6), impostata nella tua integrazione front-end.
Un’intestazione beta della versione dell’API (ad es. custom_checkout_beta=v1), impostata nella tua integrazione del back-end.

Versioni beta front-end

Specifica la versione beta del front-end durante l’inizializzazione di Stripe.js.

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 è 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. 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 ora risponde a qualsiasi Billing Address Element o Shipping Address Element montato.
- canConfirm ora diventa false se è presente una conferma in transito.
- È stato rimosso confirmationRequirements.
Breaking updateEmail genera un errore se è stato specificato 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 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.
- 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 raccogliere gli ID fiscali dei clienti. Scopri come raccogliere gli ID fiscali.
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
- In di React Stripe.js, CustomCheckoutProvider è stato rinominato CheckoutProvider e useCustomCheckout è stato rinominato useCheckout.
Breaking Per confermare Express Checkout Element, chiama confirm, specificando l’evento confirm come expressCheckoutConfirmEvent
- In precedenza, Express Checkout Element veniva confermato chiamando event.confirm().
Breaking Quando viene chiamato 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, ad esempio parametri o configurazione non validi. Questi errori non devono essere mostrati ai clienti.
Breaking I metodi asincroni, ad esempio confirm o applyPromotionCode, 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.
Breaking Address Element non aggiorna più automaticamente i campi billingAddress o shippingAddress nell’oggetto Session.
- Finché Address Element è montato, i valori del modulo verranno utilizzati automaticamente durante la chiamata di confirm.
- Ascolta l’evento change per utilizzare il valore di Address Element prima della conferma.

custom_checkout_beta_4

Aggiunta di immagini all’oggetto Session.
Sono stati aggiunti i campi come opzione durante la creazione di Payment Element.
È stato aggiunto paymentMethods come opzione durante la creazione di Express Checkout Element.
Breaking Se specifichi opzioni non valide per createElement, viene generato un errore. In precedenza, le opzioni non riconosciute venivano ignorate automaticamente.
Breaking updateEmail e updatePhoneNumber 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:
Le carte salvate ora possono essere riutilizzate. Scopri come salvare e riutilizzare i metodi di pagamento.
Breaking Il 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 è 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’ in confirm.

custom_checkout_beta_2

Breaking Il campo lineItem.recurring.interval_count è stato rimosso e sostituito con lineItem.recurring.intervalCount.
Breaking Il campo lineItem.amount è stato rimosso e sostituito con il seguente:

custom_checkout_beta_1

Questa è la versione beta iniziale del front-end.

Log delle modifiche del back-end

Specifica la versione beta del back-end durante la configurazione della libreria del server.

Non sono presenti modifiche alla versione beta del back-end.