Passare alle API Payment Intents e Payment Methods
Scopri come passare dalle API Sources e Tokens all'API Payment Methods.
L’API Payment Methods sostituisce le API Tokens e Sources esistenti come metodo consigliato nelle integrazioni per raccogliere e memorizzare i dati di pagamento. Interagisce con l’API Payment Intents per creare pagamenti con un’ampia gamma di modalità di pagamento.
Prevediamo di disattivare l’assistenza API Sources per le modalità di pagamento locali. Se attualmente gestisci modalità di pagamento locali utilizzando l’API Sources, devi migrarle all’API Payment Methods. Invieremo una comunicazione via email con ulteriori informazioni sulla cessazione dell’assistenza per le API Sources e Tokens.
Sebbene non abbiamo in programma di disattivare il supporto per le modalità di pagamento con carta, consigliamo comunque di eseguire la migrazione di queste modalità di pagamento alle API Payment Methods e Payment Intents. Per ulteriori informazioni sulla migrazione delle modalità di pagamento con carta, consulta Eseguire la migrazione all’API Payment Intents.
Eseguire la migrazione delle modalità di pagamento locali dall’API Sources all’API Payment Intents
Per eseguire la migrazione della modalità di pagamento locali, aggiorna il server e il front-end per utilizzare l’API Payment Intents. In genere sono disponibili tre opzioni di integrazione:
- Reindirizza l’utente a Stripe Checkout per il tuo flusso di pagamento.
- Utilizza Stripe Payment Element 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 una modalità di pagamento locale tramite l’API Payment Methods, consulta le istruzioni per tale modalità di pagamento nella documentazione relativa alle modalità di pagamento. 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. | Conferma che la sessione di Checkout è riuscita con il webhook payment_ | Conferma che il PaymentIntent è riuscito con il webhook payment_ | Conferma che il PaymentIntent è riuscito con il webhook payment_ |
Attenzione
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_ | Il pagamento non è riuscito. | Non applicabile |
requires_ | 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_ 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_
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_
.
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_
, 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. | Non applicabile | Non applicabile | |
source. | Non applicabile | Non applicabile | |
source. | Non applicabile | Non applicabile | |
charge. | checkout. | payment_ | Viene inviato anche il webhook charge. , quindi non devi aggiornare la tua integrazione per ascoltare il nuovo webhook. |
charge. | Non applicabile - Il cliente può ritentare il pagamento nella stessa sessione di Checkout fino alla scadenza. A quel punto riceverai un evento checkout. . | payment_ | Viene inviato anche il webhook charge. , quindi non devi aggiornare la tua integrazione per ascoltare il nuovo webhook. |
charge. | charge. | charge. |
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 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 per rappresentare lo stato del pagamento.
Nota
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 la modalità di pagamento con l’API Payment Methods | Tokens o Sources con l’API Charges |
---|---|---|
Carte | Pagamenti con carta | Supportato su Tokens, sconsigliato su Sources |
Addebito diretto ACH | Addebiti diretti su conti bancari degli Stati Uniti | Supportato su Tokens, non supportato su Sources |
Alipay | Pagamenti Alipay | Obsoleto |
Bancontact | Pagamenti Bancontact | Obsoleto |
EPS | Pagamenti EPS | Obsoleto |
giropay | Pagamenti giropay | Obsoleto |
iDEAL | Pagamenti iDEAL | [Obsoleto]/sources/ideal) |
Klarna | Pagamenti Klarna | Obsoleto |
Multibanco | Pagamenti Multibanco | Beta obsoleta |
Przelewy24 | Pagamenti Przelewy24 | Obsoleto |
Addebito diretto SEPA | Addebiti diretti SEPA (Single Euro Payments Area) | Obsoleto |
Sofort | Pagamenti Sofort | Obsoleto |
WeChat Pay | Pagamenti WeChat Pay | Obsoleto |
Dopo aver scelto l’API da integrare, utilizza la guida alle modalità di pagamento per aiutarti a determinare i giusti tipi di modalità di pagamento per cui hai bisogno dell’assistenza.
Questa guida include descrizioni dettagliate su ciascuna modalità di pagamento e descrive le differenze relative ai flussi per i clienti, insieme alle aree geografiche in cui hanno maggior rilevanza. Puoi abilitare tutte le modalità di pagamento disponibili nella Dashboard. L’attivazione è di norma istantanea e non richiede contratti aggiuntivi.
Compatibilità con modalità di pagamento precedenti riutilizzabili
Se in precedenza avevi elaborato una delle seguenti modalità di pagamento riutilizzabili con Sources, la migrazione delle fonti salvate esistenti non viene effettuata automaticamente.
- Alipay
- Addebito diretto Bacs
- Addebito diretto SEPA
Per preservare le modalità di pagamento salvate dai clienti esistenti, devi convertire tali fonti in modalità di pagamento utilizzando uno strumento di migrazione dei dati disponibile nella Dashboard Stripe. Per istruzioni su come convertirli, consulta la pagina dell’assistenza.
Compatibilità con gli oggetti delle carte precedenti
Se in precedenza hai acquisito i dettagli di pagamento dei clienti con Stripe utilizzando le carte o Sources, puoi iniziare a usare l’API Payment Methods immediatamente, senza dover eseguire la migrazione dei dati di pagamento.
Gli strumenti di pagamento compatibili che sono stati salvati in un oggetto Customer sono utilizzabili con tutte le API che accettano un oggetto PaymentMethod. Ad esempio, durante la creazione di un PaymentIntent puoi usare una carta salvata come PaymentMethod:
Quando associ l’oggetto al PaymentIntent, ricorda di fornire l’ID cliente usato per salvare il tuo strumento di pagamento compatibile.
Puoi recuperare tutti gli strumenti di pagamento compatibili salvati tramite l’API Payment Methods.
Con questa compatibilità non viene creato nessun nuovo oggetto: l’API Payment Methods fornisce infatti una vista diversa dello stesso oggetto corrispondente. Ad esempio, gli aggiornamenti di uno strumento di pagamento compatibile effettuati tramite l’API Payment Methods sono visibili tramite l’API Sources e viceversa.