Guida alla migrazione dei prezzi di Checkout

L’API Prices 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 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.
• Applica aliquote fiscali dinamiche a abbonamenti e pagamenti una tantum.

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 sono una nuova entità principale in Stripe che funziona con abbonamenti, fatture e Checkout. Ogni prezzo è associato a un singolo prodotto 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 e solitamente di un prezzo.
• La modalità 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 con l’API o la Dashboard.

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 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 oppure definisci i dettagli del prodotto in modo dinamico utilizzando price_data.product_data. Il seguente esempio illustra il flusso di creazione di una voce una tantum.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -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" \
  -d cancel_url="https://example.com/cancel"

Codice lato server per i prezzi una tantum

Con questa nuova integrazione, puoi creare un catalogo di prodotti e prezzi 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 o mediante la Dashboard. 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 https://api.stripe.com/v1/products \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Abbonamenti

Le integrazioni per i pagamenti ricorrenti prevedono le seguenti modifiche:

• Tutte le voci sono specificate in un singolo campo line_items anziché subscription_data.items.
• La modalità 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 https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -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" \
  -d cancel_url="https://example.com/cancel"

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 per sapere come i vecchi campi line_items si adattano alla nuova integrazione. Puoi creare un prodotto e un prezzo tramite l’API Prices o tramite la Dashboard Stripe. Puoi anche creare l’articolo una tantum in linea. L’esempio seguente utilizza un ID prezzo esistente:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -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" \
  -d cancel_url="https://example.com/cancel"

Modifiche dell’oggetto Response

Anziché elencare le voci con display_items, l’oggetto sessione 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 quando crei una sessione di Checkout:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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 "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Modifiche webhook

Poiché line_items può essere incluso, la risposta webhook 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 https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Per maggiori dettagli, consulta la sezione sull’evasione ordini con Checkout.