API Payment Intents

Usa l’API Payment Intents per creare un’integrazione in grado di gestire flussi di pagamento complessi con uno stato che cambia nel corso del ciclo di vita del PaymentIntent. Questa API monitora il pagamento dalla creazione fino al completamento della transazione e attiva ulteriori passaggi di autenticazione quando richiesto.

Ecco alcuni dei vantaggi derivanti dall’uso dell’API Payment Intents:

• Gestione dell’autenticazione automatica
• Nessun doppio addebito
• Nessun problema di chiave di idempotenza
• Supporto dell’autenticazione forte del cliente (SCA) e di modifiche normative simili

Una serie completa di API

Usa l’API Payment Intents insieme alle API Setup Intents e Payment Methods. Queste API ti consentono di gestire i pagamenti dinamici (ad esempio, aggiungendo un protocollo di autenticazione come 3D Secure) e preparare l’attività per l’espansione in altri Paesi, supportando al tempo stesso le nuove normative e modalità di pagamento locali.

La creazione di un’integrazione con l’API Payment Intents comporta due azioni: creazione e conferma di un PaymentIntent. Di norma ogni PaymentIntent è correlato a un singolo carrello degli acquisti o una singola sessione cliente nell’applicazione. Il PaymentIntent incapsula i dettagli sulla transazione, come le modalità di pagamento supportate, l’importo da riscuotere e la valuta desiderata.

Creare un PaymentIntent

Per iniziare consulta la guida su come accettare un pagamento. La guida descrive come creare un PaymentIntent sul server e passare al client la relativa chiave privata client anziché l’intero oggetto PaymentIntent.

Quando crei il PaymentIntent, puoi specificare opzioni quali l’importo e la valuta:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd

Pratiche ottimali

• Consigliamo di creare un PaymentIntent non appena si conosce l’importo, ad esempio quando il cliente inizia la procedura di pagamento, per monitorare l’imbuto di acquisto. Se l’importo cambia, puoi aggiornare il suo importo. Ad esempio, se il cliente esce dalla procedura di pagamento e aggiunge nuovi articoli al carrello, potrebbe essere necessario aggiornare l’importo quando avvia nuovamente tale procedura.

• Se la procedura di pagamento viene interrotta e ripresa in seguito, tenta di riutilizzare lo stesso PaymentIntent anziché crearne uno nuovo. Ogni PaymentIntent ha un ID univoco che ne consente il recupero in caso di necessità. Nel modello di dati dell’applicazione puoi archiviare l’ID del PaymentIntent nel carrello o nella sessione del cliente per facilitare il recupero. Il vantaggio del riutilizzo del PaymentIntent sta nel fatto che lo stato dell’oggetto consente di tenere traccia di qualsiasi tentativo di pagamento non riuscito per un determinato carrello o una determinata sessione.

• Ricorda di fornire una chiave di idempotenza per evitare di creare PaymentIntent doppi per lo stesso acquisto. Questa chiave è solitamente basata sull’ID che associ al carrello o alla sessione cliente nell’applicazione.

Passare la chiave privata client al lato client

Il PaymentIntent contiene una chiave privata client, ovvero una chiave univoca per il singolo PaymentIntent. Sul lato client dell’applicazione, Stripe.js utilizza la chiave privata client come parametro quando vengono richiamate le funzioni (ad esempio stripe.confirmCardPayment o stripe.handleCardAction) per completare il pagamento.

Recuperare la chiave privata client

L’oggetto PaymentIntent contiene una chiave privata client, che il lato client usa per completare la procedura di pagamento in modo sicuro. Per specificare la chiave privata sul lato client, puoi utilizzare approcci diversi.

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Dopo il pagamento

Una volta che il client avrà confermato il pagamento, la procedura ottimale consiste nel monitoraggio dei webhook da parte del server per rilevare quando il pagamento va a buon fine o non riesce.

Un PaymentIntent potrebbe avere più di un oggetto Charge associato se sono stati effettuati più tentativi di pagamento, come la ripetizione dei tentativi. Per ogni addebito puoi controllare l’esito e i dettagli della modalità di pagamento utilizzata.

Ottimizzazione delle modalità di pagamento per pagamenti futuri

Il parametro setup_future_usage salva le modalità di pagamento per un riutilizzo in futuro. Per le carte, ottimizza inoltre i tassi di autorizzazione in conformità con la legislazione locale e i regolamenti del circuito, ad esempio la SCA. Per stabilire il valore da utilizzare, valuta in che modo intendi utilizzare questa modalità di pagamento in futuro.

Con una carta configurata per i pagamenti all’interno della sessione puoi comunque accettare i pagamenti all’esterno della sessione, ma è più probabile che la banca rifiuti tali pagamenti e richieda l’autenticazione al titolare della carta.

Il seguente esempio illustra come creare un PaymentIntent e specificare setup_future_usage:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

Voce di estratto conto dinamica

Per impostazione predefinita, la voce per gli estratti conto del tuo account Stripe appare sugli estratti conto del cliente ogni volta che addebiti un importo sulla sua carta. Per specificare una voce diversa per ogni pagamento, includi il parametro statement_descriptor.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d statement_descriptor="Custom descriptor"

Le voci di estratto conto hanno un limite di 22 caratteri, non possono utilizzare i caratteri speciali <, >, ', " o * e non devono essere composte da soli numeri. Quando utilizzi le voci di estratto conto dinamiche, il testo dinamico viene aggiunto dopo il prefisso della voce di estratto conto impostata nella Dashboard Stripe. Vengono aggiunti anche un asterisco (*) e uno spazio per separare la voce di estratto conto predefinita dalla porzione dinamica. Questi 2 caratteri vengono inclusi nel calcolo del limite di 22 caratteri.

Archiviare informazioni nei metadati

Stripe supporta l’aggiunta dei metadati alle richieste più comuni effettuate, ad esempio l’elaborazione dei pagamenti. I metadati non vengono mostrati ai clienti né considerati per determinare se un pagamento deve essere o meno rifiutato o bloccato dal nostro sistema di prevenzione delle frodi.

Attraverso i metadati, puoi associare informazioni che ritieni importanti all’attività di Stripe.

Tutti i metadati che includi sono visibili nella Dashboard (ad esempio, nella pagina di un singolo pagamento) e sono inoltre disponibili nei report comuni. Ad esempio, puoi associare l’ID ordine del tuo negozio al PaymentIntent per tale ordine. Questo ti consente di riconciliare facilmente i pagamenti in Stripe con gli ordini nel tuo sistema.

Se utilizzi Radar for Fraud Teams, puoi specificare come metadati informazioni aggiuntive sui clienti e sugli ordini. Poi puoi scrivere regole Radar con gli attributi dei metadati e disporre nella Dashboard di maggiori informazioni, accelerando così la procedura di revisione.

Quando crea un addebito, un PaymentIntent vi copia i relativi metadati. I successivi aggiornamenti dei metadati del PaymentIntent non modificheranno i metadati degli addebiti precedentemente creati dal PaymentIntent stesso.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735