# Guida alla migrazione dei prezzi di Checkout Aggiornare l'integrazione per l'uso dei prezzi con Stripe Checkout L’integrazione dell’[API Prices](https://docs.stripe.com/api/prices.md) include: - Modello unificato per gli elementi di Checkout: anziché piani, *SKU* (SKUs (Stock Keeping Units) represent a specific Product variation, taking into account any combination of attributes and cost (for instance, size, color, currency, cost)) e voci riga inline, ogni elemento è *price*. - La possibilità di renderizzare le immagini di prodotto per le voci ricorrenti. - La capacità di creare un catalogo di prodotti e prezzi riutilizzabile anziché voci riga una tantum. - La capacità di creare tariffe in linea per gli *abbonamenti* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis). - Aliquote fiscali dinamiche per [abbonamenti](https://docs.stripe.com/billing/taxes/collect-taxes.md?tax-calculation=tax-rates#adding-tax-rates-to-checkout) e [pagamenti una tantum](https://docs.stripe.com/payments/checkout/taxes.md). Se non vuoi eseguire la migrazione, puoi continuare a utilizzare la tua integrazione attuale, ma non verranno aggiunte nuove funzioni. Puoi utilizzare eventuali nuovi piani o prezzi ricorrenti che crei nel parametro `plan` delle chiamate API esistenti. ## Panoramica di prodotti e prezzi I *prezzi* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) sono un’entità fondamentale all’interno di Stripe che funzionano con abbonamenti, *fatture* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) e Checkout. Ogni prezzo è legato a un singolo *prodotto* (Products represent what your business sells—whether that's a good or a service) e ogni prodotto può avere più prezzi. Diversi beni fisici o livelli di servizio sono rappresentati dai prodotti. I prezzi definiscono prezzo di base, valuta e, per i prodotti ricorrenti, ciclo di addebito. Questo ti consente di modificare e aggiungere i prezzi senza dover modificare i dettagli di ciò che offri. Ad esempio, potresti commercializzare un solo prodotto di fascia “gold” i cui prezzi corrispondono a 10 USD al mese, 100 USD all’anno, 9 EUR al mese e 90 EUR all’anno oppure una T-shirt blu con prezzi pari a 20 USD e 15 EUR. ## Pagamenti una tantum Le integrazioni per i pagamenti una tantum prevedono le seguenti modifiche: - Anziché voci riga ad hoc (ovvero che prevedono l’impostazione di nome, importo e valuta), la creazione di una sessione di Checkout richiede la creazione di un *prodotto* (Products represent what your business sells—whether that's a good or a service) e solitamente di un *prezzo* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions). - La [modalità](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) ora è obbligatoria. Il codice lato client rimane invariato. ### Tabella delle corrispondenze Anziché impostare ogni campo su `line_items`, Checkout utilizza gli oggetti prodotto e prezzo sottostanti per determinare nome, descrizione, importo, valuta e immagini. Puoi [creare prodotti e prezzi](https://docs.stripe.com/payments/accept-a-payment.md) con l’API o la Dashboard. | Senza prezzi | Con prezzi | | --- | --- | | `line_items.name` | `product.name` | | `line_items.description` | `product.description` | | `line_items.amount` | - `price.unit_amount` - `price_data.unit_amount` (se definito al momento della creazione della sessione di Checkout) | | `line_items.currency` | - `price.currency` - `price_data.currency` (se definito al momento della creazione della sessione di Checkout) | | `line_items.images` | `product.images` (visualizza la prima immagine fornita) | ### Codice lato server per le voci in linea In precedenza le voci una tantum potevano essere create solo in linea. Con i prezzi, puoi continuare a configurare le voci in linea, ma puoi anche definire i prezzi in modo dinamico con [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) al momento della creazione della sessione di Checkout. Quando crei la sessione di Checkout con `price_data`, fai riferimento a un ID prodotto esistente con [price_data.product](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product) oppure definisci i dettagli del prodotto in modo dinamico utilizzando [price_data.product_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data). Il seguente esempio illustra il flusso di creazione di una voce una tantum. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \ -d "line_items[0][price_data][unit_amount]"=2000 \ -d "line_items[0][price_data][product_data][name]"=T-shirt \ -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \ -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \ -d "line_items[0][price_data][currency]"=usd \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ### Codice lato server per i prezzi una tantum Con questa integrazione, puoi [creare un catalogo di prodotti e prezzi](https://docs.stripe.com/payments/accept-a-payment.md) anticipatamente anziché dover definire importo, valuta e nome ogni volta che crei una sessione di Checkout. Puoi creare un prodotto e un prezzo con l’[API Prices](https://docs.stripe.com/api/prices.md) o mediante la [Dashboard](https://dashboard.stripe.com/products). Per creare la sessione di Checkout è necessario l’ID prezzo. Il seguente esempio illustra come creare un prodotto e un prezzo tramite l’API: #### curl ```bash curl https://api.stripe.com/v1/products \ -u<>: \ -d name=T-shirt \ -d description="Comfortable cotton t-shirt" \ -d "images[]"="https://example.com/t-shirt.png" curl https://api.stripe.com/v1/prices \ -u<>: \ -d product="{{PRODUCT_ID}}" \ -d unit_amount=2000 \ -d currency=usd curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][quantity]"=1 \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d mode=payment \ -d success_url="https://example.com/success" \ ``` ## Abbonamenti Le integrazioni per i pagamenti ricorrenti prevedono le seguenti modifiche: - Tutte le voci sono specificate in un singolo campo [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) anziché `subscription_data.items`. - La [modalità](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) ora è obbligatoria. Imposta `mode=subscription` se la sessione include voci ricorrenti. Il codice lato client rimane invariato. I piani esistenti possono essere utilizzati ovunque vengano accettati i pagamenti ricorrenti. ### Codice lato server con piani Di seguito è riportato un esempio di creazione di una sessione di Checkout con una prova e utilizzando un piano esistente in modo intercambiabile con un prezzo. Il piano ora è specificato nel campo `line_items` anziché `subscription_data.items`. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \ -d "line_items[0][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ### Codice lato server per prezzo ricorrente con costo di attivazione Se hai piani ricorrenti con un costo di attivazione una tantum, crea il prodotto e il prezzo che rappresentano la tariffa una tantum prima di creare la sessione di Checkout. Consulta la [tabella di mappatura](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time) per scoprire come i campi `line_items` si associano a questa integrazione. Puoi creare un prodotto e un prezzo tramite [l’API Prices](https://docs.stripe.com/api/prices.md) o la [Dashboard Stripe](https://dashboard.stripe.com/products). Puoi anche [creare l’elemento una tantum inline](https://docs.stripe.com/payments/checkout/migrating-prices.md#server-side-code-for-inline-items). L’esempio seguente utilizza un ID prezzo esistente: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \ -d "line_items[1][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ## Modifiche dell’oggetto Response Anziché elencare le voci con `display_items`, l’oggetto sessione di Checkout utilizza `line_items`. Il campo `line_items` non viene visualizzato per impostazione predefinita come il campo `display_items`, ma puoi includerlo utilizzando il parametro [expand](https://docs.stripe.com/api/expanding_objects.md) quando crei una sessione di Checkout: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="card" \ -d "mode"="payment" \ -d "line_items[0][price]"="{{PRICE_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "success_url"="https://example.com/success" \ -d "expand[]"="line_items" ``` ## Modifiche webhook Poiché `line_items` può essere incluso, la risposta del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) `checkout.session.completed` non elenca gli elementi per impostazione predefinita. L’oggetto di risposta più compatto consente di ricevere più rapidamente i webhook di Checkout. Puoi recuperare gli elementi tramite l’endpoint `line_items`: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \ -u <>: ``` Per maggiori dettagli, consulta la sezione sull’[evasione ordini con Checkout](https://docs.stripe.com/checkout/fulfillment.md).