# Esegui la migrazione alle API Payment Methods e Payment Intents Scopri come passare dalle API Sources e Tokens all'API Payment Methods. L’[API Payment Methods](https://docs.stripe.com/docs/api/payment_methods.md) sostituisce le API [Tokens](https://docs.stripe.com/api/tokens.md) e [Sources](https://docs.stripe.com/api/sources.md) esistenti come metodo consigliato nelle integrazioni per raccogliere e memorizzare i dati di pagamento. Interagisce con l’[API Payment Intents](https://docs.stripe.com/docs/payments/payment-intents.md) per creare pagamenti con un’ampia gamma di metodi di pagamento. Abbiamo in programma di disattivare il supporto dell’API Sources per i *metodi di pagamento locali* (Payment methods used in specific countries or regions, such as bank transfers, vouchers, and digital wallets. Examples include Pix (Brazil, bank transfers), Konbini (Japan, vouchers), and WeChat Pay (China, digital wallet)). Se attualmente gestisci metodi di pagamento locali utilizzando l’API Sources, [devi migrarli all’API Payment Methods](https://docs.stripe.com/payments/payment-methods/transitioning.md#migrate-local-payment-methods). Ti invieremo un’email con ulteriori informazioni sulla fine del supporto per le API Sources e Tokens. Sebbene non abbiamo in programma di disattivare il supporto per i metodi di pagamento con carta, consigliamo comunque di eseguire la migrazione di questi metodi di pagamento alle API Payment Methods e Payment Intents. Per ulteriori informazioni sulla migrazione dei metodi di pagamento con carta, consulta [Eseguire la migrazione all’API Payment Intents](https://docs.stripe.com/payments/payment-intents/migration.md). ## Eseguire la migrazione delle modalità di pagamento locali dall’API Sources all’API Payment Intents Per eseguire la migrazione dei metodi di pagamento locali, aggiorna il server e il front-end per utilizzare l’[API Payment Intents](https://docs.stripe.com/api/payment_intents.md). In genere sono disponibili tre opzioni di integrazione: - Reindirizza l’utente a [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) per il tuo flusso di pagamento. - Utilizza Stripe [Payment Element](https://docs.stripe.com/payments/payment-element.md) sulla tua pagina di pagamento. - Crea il tuo modulo e utilizza l’SDK Stripe JS per completare il pagamento. Se utilizzi Stripe Checkout o Payment Element, puoi aggiungere e gestire la maggior parte delle modalità di pagamento presenti sulla Dashboard Stripe senza apportare modifiche al codice. Per informazioni specifiche sull’integrazione di un metodo di pagamento locale tramite l’API Payment Methods, consulta le istruzioni per tale metodo di pagamento nella [documentazione relativa ai metodi di pagamento](https://docs.stripe.com/payments/payment-methods/overview.md). La tabella seguente fornisce un confronto generale delle diverse tipologie di pagamento. | Integrazione precedente | Stripe Checkout | Payment Element | Tuo modulo | | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Complessità bassa | Complessità media | Complessità elevata | | Crea un oggetto Source sul front-end o sul server | Crea una sessione di Checkout sul server | Crea un PaymentIntent sul server | Crea un PaymentIntent sul server | | Autorizza il pagamento caricando un widget o reindirizzando a una terza parte | Non necessario | Trasmetti la chiave privata client al front-end e utilizza l’SDK Stripe JS per visualizzare un Payment Element per completare il pagamento | Trasmetti la chiave privata client al front-end, utilizza il tuo modulo per raccogliere le informazioni sul tuo cliente e completa il pagamento in base alla modalità di pagamento | | Conferma che l’oggetto Source è addebitabile e addebita l’importo all’oggetto Source | Non necessario | Non necessario | Non necessario | | Conferma che l’addebito è riuscito in modo asincrono con il webhook `charge.succeeded` | Conferma che la sessione di Checkout è riuscita con il webhook `payment_intent.succeeded` | Conferma che il PaymentIntent è riuscito con il webhook `payment_intent.succeeded` | Conferma che il PaymentIntent è riuscito con il webhook `payment_intent.succeeded` | > Un oggetto PaymentIntent rappresenta un pagamento nella nuova integrazione e crea un oggetto Charge quando confermi il pagamento sul front-end. Se in precedenza memorizzavi i riferimenti sull’oggetto Charge, puoi continuare a farlo recuperando l’ID addebito dal PaymentIntent dopo che il cliente ha completato il pagamento. Tuttavia, ti consigliamo anche di memorizzare l’ID PaymentIntent. ### Verifica dello stato del pagamento In precedenza l’integrazione avrebbe dovuto controllare sia lo stato dell’oggetto Source che lo stato dell’oggetto Charge dopo ogni chiamata API. Non devi più controllare due stati: devi solo controllare lo stato del PaymentIntent o della sessione di Checkout dopo averlo confermato sul front-end. | payment_intent.status | Significato | Istruzioni speciali | | ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `succeeded` | Il pagamento è riuscito. | Non applicabile | | `requires_payment_method` | Il pagamento non è riuscito. | Non applicabile | | `requires_action` | Il cliente non ha completato l’autorizzazione del pagamento. | Se il cliente non completa il pagamento entro 48 ore, lo stato del PaymentIntent diventa `requires_payment_method` e puoi riprovare la conferma. | Conferma sempre lo stato del PaymentIntent recuperandolo sul tuo server o ascoltando i webhook sul tuo server. Non fare affidamento esclusivamente sull’utente che ritorna al `return_url` fornito quando confermi il PaymentIntent. ### Rimborsi Puoi continuare a chiamare l’API Refunds con un oggetto Charge creato da PaymentIntent. L’ID dell’addebito è accessibile nel parametro `latest_charge`. In alternativa, puoi fornire l’ID PaymentIntent all’API Refunds anziché all’oggetto Charge. ### Gestione degli errori In precedenza, dovevi gestire gli errori su Sources. Con PaymentIntents, anziché verificare la presenza di errori su un oggetto Source, controlli la presenza di errori sul PaymentIntent quando viene creato e dopo che il cliente ha autorizzato il pagamento. La maggior parte degli errori sul PaymentIntent sono di tipo `invalid_request_error`, restituiti in una richiesta non valida. Quando esegui la migrazione dell’integrazione, tieni presente che i codici di errore di PaymentIntent possono essere diversi dai corrispondenti codici di errore per Sources. ### Webhook Se in precedenza ascoltavi gli eventi Source, potresti dover aggiornare la tua integrazione per ascoltare nuovi tipi di eventi. La tabella seguente mostra alcuni esempi. | Webhook precedente | Nuovo webhook su Checkout | Nuovo webhook su PaymentIntents | Istruzioni speciali | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `source.chargeable` | Non applicabile | Non applicabile | | | `source.failed` | Non applicabile | Non applicabile | | | `source.canceled` | Non applicabile | Non applicabile | | | `charge.succeeded` | `checkout.session.completed` | `payment_intent.succeeded` | Viene inviato anche il webhook `charge.succeeded`, quindi non devi aggiornare la tua integrazione per ascoltare il nuovo webhook. | | `charge.failed` | Non applicabile - Il cliente può ritentare il pagamento nella stessa sessione di Checkout fino alla [scadenza](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-expires_at). A quel punto riceverai un evento `checkout.session.expired`. | `payment_intent.payment_failed` | Viene inviato anche il webhook `charge.failed`, quindi non devi aggiornare la tua integrazione per ascoltare il nuovo webhook. | | `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` | | ## Transizione all’API Payment Methods La differenza più importante tra le API Payment Methods e Sources consiste nel fatto che Sources utilizza la proprietà [status](https://docs.stripe.com/api/sources/object.md#source_object-status) per descrivere lo stato della transazione. Ciò significa che ogni oggetto `Source` deve passare in uno stato addebitabile prima di poter essere utilizzato per un pagamento. Al contrario, un oggetto `PaymentMethod` è senza stato e si basa su un oggetto *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) per rappresentare lo stato del pagamento. > La tabella seguente non è un elenco completo delle modalità di pagamento. Se integri altre modalità di pagamento con l’API Sources, eseguine la migrazione anche all’API Payment Methods. | Flussi | Integrare il metodo di pagamento con l’API Payment Methods | Tokens o Sources con l’API Charges | | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Carte | [Pagamenti con carta](https://docs.stripe.com/payments/cards.md) | [Supportato su Tokens](https://docs.stripe.com/payments/charges-api.md), sconsigliato su Sources | | Addebito diretto ACH | [Addebiti diretti su conti bancari degli Stati Uniti](https://docs.stripe.com/payments/ach-direct-debit.md) | [Supportato su Tokens](https://docs.stripe.com/ach-deprecated.md), non supportato su Sources | | Bonifico ACH | [Bonifici bancari in USD](https://docs.stripe.com/payments/customer-balance/migrating-from-sources.md) | [Obsoleto](https://docs.stripe.com/sources/ach-credit-transfer.md) | | Alipay | [Pagamenti Alipay](https://docs.stripe.com/payments/alipay.md) | [Obsoleto](https://docs.stripe.com/sources/alipay.md) | | Bancontact | [Pagamenti Bancontact](https://docs.stripe.com/payments/bancontact.md) | [Obsoleto](https://docs.stripe.com/sources/bancontact.md) | | EPS | [Pagamenti EPS](https://docs.stripe.com/payments/eps.md) | Obsoleto | | giropay | [Pagamenti giropay](https://docs.stripe.com/payments/giropay.md) | [Obsoleto](https://docs.stripe.com/sources/giropay.md) | | iDEAL | [Pagamenti iDEAL](https://docs.stripe.com/payments/ideal.md) | [Obsoleto]/sources/ideal) | | Klarna | [Pagamenti Klarna](https://docs.stripe.com/payments/klarna.md) | Obsoleto | | Multibanco | [Pagamenti Multibanco](https://docs.stripe.com/payments/multibanco.md) | [Beta obsoleta](https://docs.stripe.com/sources/multibanco.md) | | Przelewy24 | [Pagamenti Przelewy24](https://docs.stripe.com/payments/p24.md) | [Obsoleto](https://docs.stripe.com/sources/p24.md) | | Bonifico SEPA | [Bonifici bancari in EUR](https://docs.stripe.com//payments/customer-balance/migrating-from-sepa-credit-transfer.md) | [Obsoleto](https://docs.stripe.com/sources/sepa-credit-transfer.md) | | Addebito diretto SEPA | [Addebiti diretti SEPA (Single Euro Payments Area)](https://docs.stripe.com/payments/sepa-debit.md) | [Obsoleto](https://docs.stripe.com/sources/sepa-debit.md) | | WeChat Pay | [Pagamenti WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) | [Obsoleto](https://docs.stripe.com/sources/wechat-pay.md) | Dopo aver scelto l’API da integrare, utilizza la [guida ai metodi di pagamento](https://stripe.com/payments/payment-methods-guide) per aiutarti a determinare i giusti tipi di metodi di pagamento per cui hai bisogno dell’assistenza. Questa guida include descrizioni dettagliate su ciascun metodo di pagamento e descrive le differenze relative ai flussi per i clienti, insieme alle [aree geografiche](https://stripe.com/payments/payment-methods-guide#payment-methods-fact-sheets) in cui hanno maggior rilevanza. Puoi abilitare i tutti metodi di pagamento disponibili nella [Dashboard](https://dashboard.stripe.com/account/payments/settings). L’attivazione è di norma istantanea e non richiede contratti aggiuntivi. ## Compatibilità con metodi di pagamento precedenti riutilizzabili Se in precedenza avevi elaborato uno dei seguenti metodi di pagamento riutilizzabili con [Sources](https://docs.stripe.com/sources.md), la migrazione delle fonti salvate esistenti non viene effettuata automaticamente. - Alipay - Addebito diretto Bacs - Addebito diretto SEPA Per preservare i metodi di pagamento salvate dai clienti esistenti, devi convertire tali fonti in metodi di pagamento utilizzando uno strumento di migrazione dei dati disponibile nella Dashboard Stripe. Per istruzioni su come convertirli, consulta [la pagina dell’assistenza](https://support.stripe.com/questions/reusable-object-migration). ## Compatibilità con gli oggetti delle carte precedenti Se in precedenza hai acquisito i dettagli di pagamento delle carte dei clienti con Stripe utilizzando [carte](https://docs.stripe.com/payments/charges-api.md) o [Sources](https://docs.stripe.com/sources.md), puoi iniziare a utilizzare immediatamente l’API Payment Methods senza migrare alcuna informazione di pagamento. I metodi di pagamento compatibili che sono stati salvati in un oggetto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) sono utilizzabili con tutte le API che accettano un oggetto *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs). Ad esempio, durante la creazione di un PaymentIntent puoi usare una carta salvata come PaymentMethod: ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "payment_method_types[]"=card \ -d amount=1099 \ -d currency=usd \ -d customer="{{CUSTOMER_ID}}" \ -d payment_method="{{CARD_ID}}" ``` Quando associ l’oggetto al PaymentIntent, ricorda di fornire l’ID cliente usato per salvare il tuo metodo di pagamento compatibile. Puoi [recuperare](https://docs.stripe.com/api/payment_methods/retrieve.md) tutti i metodi di pagamento compatibili salvati tramite l’API Payment Methods. #### Carta ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "card", "address_city": "San Francisco", "address_country": "US", "address_line1": "1234 Fake Street", "address_line1_check": null, "address_line2": null, "address_state": null, "address_zip": null, "address_zip_check": null, "brand": "Visa", "country": "US", "customer": "{{CUSTOMER_ID}}", "cvc_check": null, "dynamic_last4": null, "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "metadata": { }, "name": null, "tokenization_method": null } ``` ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "San Francisco", "country": "US", "line1": "1234 Fake Street", "line2": null, "postal_code": null, "state": null }, "name": null, "phone": null, "email": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 123456789, "customer": "cus_EepWxEKrgMaywv", "livemode": false, "metadata": { }, "type": "card" } ``` #### Origine carta ```json { "id": "src_1AhIN74iJb0CbkEwmbRYPsd4", "object": "source", "amount": null, "client_secret": "src_client_secret_sSPHZ17iQG6j9uKFdAYqPErO", "created": 1500471469, "currency": null, "flow": "none", "livemode": false, "metadata": { }, "owner": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "email": "jenny.rosen@example.com", "name": "Jenny Rosen", "phone": null, "verified_address": null, "verified_email": null, "verified_name": null, "verified_phone": null }, "status": "chargeable", "type": "card", "usage": "reusable", "card": { "exp_month": 4, "exp_year": 2024, "address_line1_check": "unchecked", "address_zip_check": "unchecked", "brand": "Visa", "country": "US", "cvc_check": "unchecked", "funding": "credit", "last4": "4242", "three_d_secure": "optional", "tokenization_method": null, "dynamic_last4": null } } ``` ```json { "id": "card_1EBXBSDuWL9wT9brGOaALeD2", "object": "payment_method", "billing_details": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "name": "Jenny Rosen", "phone": null, "email": "jenny.rosen@example.com" }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 4, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1500471469, "customer": "{{CUSTOMER_ID}}", "livemode": false, "metadata": { }, "type": "card" } ``` Con questa compatibilità non viene creato nessun nuovo oggetto: l’API Payment Methods fornisce infatti una vista diversa dello stesso oggetto sottostante. Ad esempio, gli aggiornamenti di uno strumento di pagamento compatibile effettuati tramite l’API Payment Methods sono visibili tramite l’API Sources e viceversa. ## See also - [Guida alle modalità di pagamento](https://stripe.com/payments/payment-methods-guide) - [Collegare pagamenti](https://docs.stripe.com/connect/charges.md) - [Documentazione di riferimento dell’API Payment Methods](https://docs.stripe.com/api/payment_methods.md)