Passare alle API Payment Intents e 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 metodi di pagamento.

Prevediamo di disattivare l’assistenza API Sources per i metodi di pagamento locali. Se attualmente gestisci metodi di pagamento locali utilizzando l’API Sources, devi eseguirne la migrazione 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 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.

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. 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 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. La tabella seguente fornisce un confronto generale delle diverse tipologie di pagamento.

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.

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.

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.

Dopo aver scelto l’API da integrare, utilizza la guida ai metodi di pagamento 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 in cui hanno maggior rilevanza. Puoi abilitare i tutti metodi di pagamento disponibili nella Dashboard. 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, 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.

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.

I metodi 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:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 tutti i metodi di pagamento compatibili salvati tramite l’API Payment Methods.

{
  "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,

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

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.