# Guida alla migrazione dei prezzi di Checkout Aggiornare l'integrazione per l'uso dei prezzi con Stripe Checkout L’[API Prices](https://docs.stripe.com/api/prices.md) aggiunge nuove funzionalità e flessibilità al modo in cui addebiti i pagamenti ai clienti. Questa nuova integrazione offre: - Modellazione più unificata per le voci 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 in linea, ora ogni voce è un *prezzo*. - La possibilità di renderizzare le immagini di prodotto per le voci ricorrenti. - Creare un catalogo di prodotti e prezzi riutilizzabile anziché voci riga una tantum. - 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). - Applica aliquote fiscali dinamiche a [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). Non vuoi eseguire la migrazione? Puoi continuare a utilizzare l’integrazione corrente, ma le nuove funzionalità non sono supportate. Puoi utilizzare qualsiasi nuovo piano o prezzo ricorrente creato 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 una nuova entità principale in Stripe che funziona 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 è associato 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. Beni fisici o livelli di servizio diversi devono essere rappresentati da prodotti. Le tariffe di tali prodotti devono essere rappresentate da prezzi. 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/mese, 100 USD/anno, 9 EUR/mese e 90 EUR/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 nuova 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 delle corrispondenze](https://docs.stripe.com/payments/checkout/migrating-prices.md#mapping-table-server-one-time) per sapere come i vecchi campi `line_items` si adattano alla nuova integrazione. Puoi creare un prodotto e un prezzo tramite l’[API Prices](https://docs.stripe.com/api/prices.md) o tramite la [Dashboard Stripe](https://dashboard.stripe.com/products). Puoi anche [creare l’articolo una tantum in linea](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 *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 più le voci per impostazione predefinita. L’oggetto Response più piccolo ti consente di ricevere i webhook di Checkout più rapidamente. Puoi recuperare le voci con il nuovo 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).