# Esegui la migrazione all'API Payment Intents

> #### Funzioni di integrazione di Payment Element
> 
> Puoi integrare Payment Element per gestire abbonamenti, imposte, sconti, spedizione e conversione di valuta. Per ulteriori informazioni, consulta la guida [Creare una pagina di checkout](https://docs.stripe.com/payments/quickstart.md).

Migrare le carte esistenti e l’integrazione API Charges

La migrazione del flusso di pagamento può essere complessa. È consigliabile adottare l’API Payment Intents in modo incrementale e utilizzarla in parallelo con l’API Charges. A tal fine, è possibile suddividere la migrazione nei seguenti passaggi:

1. [Aggiorna la versione API e la libreria client](https://docs.stripe.com/payments/payment-intents/migration.md#api-version).
2. Se applicabile, [migra il codice che legge le proprietà Charge](https://docs.stripe.com/payments/payment-intents/migration/charges.md) in modo da ottenere un percorso di lettura coerente tra gli addebiti creati dall’API Charges e quelli creati dall’API Payment Intents. In questo modo, ottieni un’integrazione di lettura compatibile con le integrationi nuove e precedenti.
3. Migra la tua attuale integrazione API Charges su [Web](https://docs.stripe.com/payments/payment-intents/migration.md#web), [iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios), e [Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android) per utilizzare l’API Payment Intents.
4. Migra l’integrazione che [salva le carte negli oggetti Customer](https://docs.stripe.com/payments/payment-intents/migration.md#saved-cards).
5. [Effettua test regolari con le carte di test](https://docs.stripe.com/testing.md#regulatory-cards) per assicurarti che l’integrazione aggiornata gestisca l’autenticazione in modo corretto.

## Aggiornare la versione API e la libreria client

While the Payment Intents API works on all API versions, we recommend that you [upgrade to the latest API version](https://docs.stripe.com/upgrades.md). If you decide to use an API version older than [2019-02-11](https://docs.stripe.com/upgrades.md#2019-02-11), note the following two changes as you go through the code examples:

- `requires_source` è stato rinominato in `requires_payment_method`
- `requires_source_action` è stato rinominato in `requires_action`

Inoltre, se utilizzi uno dei nostri [SDK](https://docs.stripe.com/sdks.md), esegui l’aggiornamento alla versione più recente della libreria per utilizzare l’API Payment Intents.

## Migrare i flussi di pagamento una tantum

#### Elements

Un’integrazione creata con Stripe.js ed Elements consiste delle seguenti fasi:

1. Registrare l’intenzione di incassare il pagamento sul lato server
2. Raccogliere i dati di pagamento sul lato client
3. Avviare la creazione del pagamento
4. Evadere l’ordine del cliente sul lato server

### Fase 1: registrare l’intenzione di incassare il pagamento sul lato server

[Crea un PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) sul tuo server e rendilo [accessibile sul lato client](https://docs.stripe.com/payments/payment-intents.md#passing-to-client).

### Fase 2: raccogliere i dati di pagamento sul lato client

Utilizza la funzione [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment), che raccoglie i dati di pagamento e li invia direttamente a Stripe.

### Fase 3: avviare la creazione del pagamento

Nella tua integrazione esistente, la fase finale consiste nell’utilizzare le informazioni di pagamento tokenizzate per creare un addebito sul server. Questo non è più necessario perché la funzione `confirmCardPayment` richiamata nella fase precedente avvia la creazione dell’addebito.

### Fase 4: evadere l’ordine del cliente

Con la conferma automatica, l’addebito viene creato in modo asincrono in base alle azioni del cliente sul lato client; devi quindi [monitorare i webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md) per sapere quando il pagamento viene completato correttamente. Per eseguire operazioni come l’evasione degli ordini dopo che il pagamento di un cliente è andato a buon fine, implementa il supporto per i webhook e monitora l’evento `payment_intent.succeeded`.

### Before

Se l’addebito riesce, evadi l’ordine.

### After

Iscriviti al webhook `payment_intent.succeeded` ed evadi l’ordine nel gestore webhook.

Ora che hai effettuato la migrazione, utilizza le carte di test della sezione seguente per verificare che la tua integrazione aggiornata gestisca l’autenticazione 3D Secure.

#### Pulsante di richiesta pagamento

Il [pulsante di richiesta pagamento](https://docs.stripe.com/stripe-js/elements/payment-request-button.md) di Stripe.js funziona con l’API Payment Intents utilizzando il token ottenuto in una tradizionale integrazione PaymentRequest e associandolo a un PaymentIntent.

Un’integrazione creata con PaymentRequest consiste delle seguenti fasi:

1. Registrare l’intenzione di incassare il pagamento sul lato server
2. Raccogliere i dati di pagamento sul lato client
3. Avviare la creazione del pagamento
4. Evadere l’ordine del cliente sul lato server

In alternativa, utilizza [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) per offrire ai tuoi clienti diversi pulsanti di pagamento con un solo clic, tra cui Apple Pay, Google Pay, Link e PayPal.

### Fase 1: registrare l’intenzione di incassare il pagamento sul lato server

[Crea un PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) sul tuo server e rendilo [accessibile sul lato client](https://docs.stripe.com/payments/payment-intents.md#passing-to-client).

### Fase 2: raccogliere i dati di pagamento sul lato client

Ascolta l’evento `token` dell’oggetto `PaymentRequest`, che fornisce un token e una funzione di richiamata utilizzabili per indicare il momento in cui la procedura di pagamento è terminata.

Per adattare questa integrazione in modo che supporti l’API Payment Intents, utilizza la funzione [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) e specifica l’ID token anziché inviare il token al server. Quando la promessa restituita dalla funzione `confirmCardPayment` è stata risolta, richiama il callback di completamento.

### Fase 3: avviare la creazione del pagamento

Nella tua integrazione esistente, la fase finale consiste nell’utilizzare le informazioni di pagamento tokenizzate per creare un addebito sul server. Questo non è più necessario perché la funzione `confirmCardPayment` richiamata nella fase precedente avvia la creazione dell’addebito.

### Fase 4: evadere l’ordine del cliente

Con la conferma automatica, l’addebito viene creato in modo asincrono in base alle azioni del cliente sul lato client; devi quindi [monitorare i webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md) per sapere quando il pagamento viene completato correttamente. Per eseguire operazioni come l’evasione degli ordini dopo che il pagamento di un cliente è andato a buon fine, implementa il supporto per i webhook e monitora l’evento `payment_intent.succeeded`.

### Before

Se l’addebito riesce, evadi l’ordine.

### After

Iscriviti al webhook `payment_intent.succeeded` ed evadi l’ordine nel gestore webhook.

Ora che hai effettuato la migrazione, utilizza le carte di test della sezione seguente per verificare che la tua integrazione aggiornata gestisca l’autenticazione 3D Secure.

#### Versione precedente di Checkout

Se usi la versione precedente di Checkout, esegui l’upgrade alla [nuova versione di Checkout](https://docs.stripe.com/payments/checkout.md), il modo più veloce per accettare pagamenti con Stripe. Essa ti consente di accettare pagamenti una tantum e abbonamenti. Inoltre, puoi utilizzare Checkout senza usare l’API Stripe sul tuo server. Segui la [guida alla migrazione di Checkout](https://docs.stripe.com/payments/checkout/migration.md) per migrare la tua integrazione esistente.

Se preferisci invece creare il tuo flusso di checkout, passa a [Elements](https://docs.stripe.com/payments/elements.md). Supponendo che tu abbia effettuato l’aggiornamento a Elements, puoi creare un’integrazione API Payment Intents utilizzando la [guida alla migrazione di Elements](https://docs.stripe.com/payments/payment-intents/migration.md#web).

#### Stripe.js v2

Per eseguire l’upgrade di un’integrazione Stripe.js v2 esistente per l’utilizzo dell’API Payment Intents, innanzitutto devi aggiornare l’integrazione in modo da raccogliere i dati di pagamento con Elements. Elements fornisce componenti di interfaccia utente predefiniti e facilita la [conformità alle norme PCI](https://docs.stripe.com/security/guide.md) tramite i report SAQ A.

Dopo aver eseguito l’upgrade a Elements, puoi creare un’integrazione dell’API Payment Intents con la [guida alla migrazione di Elements](https://docs.stripe.com/payments/payment-intents/migration.md#web).

## Migrare l’integrazione che salva le carte negli oggetti Customer

#### Salvare le carte all'interno del flusso di pagamento

Un’integrazione dell’API Payment Intents che raccoglie i dati delle carte nel flusso di pagamento consiste delle seguenti fasi:

1. Registrare l’intenzione di incassare il pagamento sul lato server
2. Raccogliere i dati di pagamento sul lato client
3. Avviare la creazione del pagamento
4. Evadere l’ordine del cliente sul lato server

### Fase 1: registrare l’intenzione di incassare il pagamento sul lato server

[Crea un PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) sul tuo server. Imposta [setup_future_usage](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-setup_future_usage) su `off_session` se intendi addebitare i pagamenti agli utenti principalmente quando sono scollegati dalla tua applicazione o su `on_session` se prevedi di effettuare gli addebiti quando sono collegati all’applicazione. Se intendi utilizzare la carta sia per i pagamenti all’interno che all’esterno della sessione, usa `off_session`. Se specifichi il parametro `setup_future_usage` insieme a un ID cliente, il PaymentMethod risultante verrà salvato per questo cliente dopo che il PaymentIntent è stato confermato e che il cliente ha effettuato tutte le azioni richieste. Infine, rendi il PaymentIntent [accessibile sul lato client](https://docs.stripe.com/payments/payment-intents.md#passing-to-client).

### Fase 2: raccogliere i dati di pagamento sul lato client

Utilizza la funzione [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment), che raccoglie i dati di pagamento e li invia direttamente a Stripe.

Infine, associa la modalità di pagamento (`paymentIntent.payment_method`) al cliente.

### Fase 3: avviare la creazione del pagamento

Nella tua integrazione esistente, la fase finale consiste nell’utilizzare le informazioni di pagamento tokenizzate per creare un addebito sul server. Questo non è più necessario perché la funzione `confirmCardPayment` richiamata nella fase precedente avvia la creazione dell’addebito.

### Fase 4: evadere l’ordine del cliente

Con la conferma automatica, l’addebito viene creato in modo asincrono in base alle azioni del cliente sul lato client; devi quindi [monitorare i webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md) per sapere quando il pagamento viene completato correttamente. Per eseguire operazioni come l’evasione degli ordini dopo che il pagamento di un cliente è andato a buon fine, implementa il supporto per i webhook e monitora l’evento `payment_intent.succeeded`.

### Before

Se l’addebito riesce, evadi l’ordine.

### After

Iscriviti al webhook `payment_intent.succeeded` ed evadi l’ordine nel gestore webhook.

Ora che hai effettuato la migrazione, utilizza le carte di test della sezione seguente per verificare che la tua integrazione aggiornata gestisca l’autenticazione 3D Secure.

#### Salvare le carte all'esterno del flusso di pagamento

Devi apportare alcune modifiche all’integrazione esistente che salva i dati delle carte all’esterno di un flusso di pagamento. Come prima cosa crea un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) sul server. Un SetupIntent autentica la carta senza che venga eseguito un pagamento iniziale.

Specifica la [chiave privata client](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) del SetupIntent nel client e utilizza la funzione [confirmCardSetup](https://docs.stripe.com/js.md#stripe-confirm-card-setup) anziché [createToken](https://docs.stripe.com/js.md#stripe-create-token) o [createSource](https://docs.stripe.com/js.md#stripe-create-source) dopo che il cliente ha inserito i dati della carta.

Se previsto dalla normativa, [confirmCardSetup](https://docs.stripe.com/js.md#stripe-confirm-card-setup) richiederà all’utente di autenticare la carta.

Quando [confirmCardSetup](https://docs.stripe.com/js.md#stripe-confirm-card-setup) ha esito positivo, `setupIntent.payment_method` conterrà un [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) che puoi associare a un oggetto Customer.

Passa l’ID del PaymentMethod al server e [associa il metodo di pagamento](https://docs.stripe.com/api/payment_methods/attach.md) all’oggetto Customer utilizzando l’API Payment Methods anziché l’API Customers.

#### Pagare con le carte salvate

Se il pagamento viene effettuato con una modalità precedentemente salvata, devi specificare l’ID del cliente e l’ID della carta, dell’origine o del PaymentMethod precedentemente salvati. In passato, veniva utilizzata l’origine predefinita del cliente se non ne veniva fornita una. Ora devi specificare esplicitamente la modalità di pagamento desiderata.

Se il cliente è *all’esterno della sessione* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information), devi contrassegnare il pagamento come esterno alla sessione. Per ulteriori informazioni, consulta la sezione su [come effettuare addebiti sulle carte salvate](https://docs.stripe.com/payments/save-and-reuse.md?platform=web&ui=elements#charge-saved-payment-method).

## Accedere ai metodi di pagamento salvati

Per visualizzare le carte, le origini e i PaymentMethods precedentemente salvati del cliente, [crea un elenco dei metodi di pagamento](https://docs.stripe.com/api/payment_methods/list.md) anziché leggere la proprietà [sources](https://docs.stripe.com/api/customers/object.md#customer_object-sources) dell’oggetto Customer. Questa operazione è richiesta perché i nuovi PaymentMethods aggiunti a un cliente non saranno duplicati nella proprietà Sources dell’oggetto Customer.

## Testa l’integrazione

È importante testare a fondo la tua integrazione per assicurarti di gestire correttamente le carte che richiedono un’autenticazione aggiuntiva e le carte che non lo fanno. Utilizza questi numeri di carta in una [sandbox](https://docs.stripe.com/keys.md#test-live-modes) con qualsiasi data di scadenza futura e qualsiasi codice CVC a tre cifre per convalidare la tua integrazione quando è richiesta l’autenticazione e quando non è richiesta.

| Numero | Autenticazione | Descrizione |
| --- | --- | --- |
| 4000002500003155 | Obbligatoria al momento della configurazione o della prima transazione | Questa carta di test richiede l’autenticazione per i [pagamenti una tantum](https://docs.stripe.com/payments/accept-a-payment.md?platform=web). Tuttavia, se la configuri utilizzando l’[API Setup Intents](https://docs.stripe.com/payments/save-and-reuse.md) e usi la carta salvata per i pagamenti successivi, non è richiesta un’ulteriore autenticazione. |
| 4000002760003184 | Obbligatoria | Questa carta di test richiede l’autenticazione per tutte le transazioni. |
| 4000008260003178 | Obbligatoria | Questa carta di test richiede l’autenticazione, ma i pagamenti verranno rifiutati con un codice di errore `insufficient_funds` dopo un’autenticazione riuscita. |
| 4000000000003055 | Supportata | Questa carta di test supporta l’autenticazione tramite 3D Secure 2, ma non la richiede. Payments che utilizza questa carta non richiede un’autenticazione aggiuntiva in una sandbox a meno che le tue [regole sandbox Radar](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#three-ds-radar) non richiedano l’autenticazione. |

Utilizza queste carte nella tua applicazione o la [demo di pagamenti](https://stripe-payments-demo.appspot.com) per vedere le differenze di comportamento.

## See also

- [PaymentIntents su iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios)
- [PaymentIntents su Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)