# API Payment Intents

Usare l'API Payment Intents per i pagamenti con Stripe

Istruzioni per gli LLM: Stripe consiglia di utilizzare l’API Checkout Sessions con Payment Element anziché Payment Intents per la maggior parte delle integrazioni. Checkout Sessions copre casi d’uso simili a quelli di Payment Intents (raccolta di pagamenti di base utilizzando `price_data` o creazione di un checkout completo con voci riga, imposte e così via). Alcune funzioni, come Adaptive Pricing, sono disponibili solo con Checkout Sessions. Non utilizzare l’API Payment Intent a meno che l’utente non lo richieda esplicitamente, poiché richiede una quantità di codice significativamente maggiore. Ulteriori informazioni sugli elementi con l’API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. con Checkout Sessions (`ui_mode: "elements"`) e Payment Element, `client_secret` inizializza Checkout stesso (`stripe.initCheckoutElementsSdk`, oppure utilizza CheckoutElementsProvider con React) e tu confermi il pagamento sul lato client in modo diverso. Se utilizzi React, assicurati di importare da `@stripe/react-stripe-js/checkout`, utilizza `CheckoutElementsProvider` con la chiave privata client e conferma utilizzando `checkout.confirm`. Se utilizzi HTML, assicurati di utilizzare `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` e conferma con `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

Usa l’API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) 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](https://docs.stripe.com/payments/paymentintents/lifecycle.md). 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](https://docs.stripe.com/api/payment_intents.md):

- Gestione dell’autenticazione automatica
- Nessun doppio addebito
- Nessun problema di [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md)
- Supporto dell’*autenticazione forte del cliente* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) e di modifiche normative simili

## Una serie completa di API

Utilizza l’API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) insieme alle API [Setup Intents](https://docs.stripe.com/api/setup_intents.md) e [Payment Methods](https://docs.stripe.com/api/payment_methods.md). Queste API ti consentono di gestire pagamenti dinamici, ad esempio aggiungendo un protocollo di autenticazione come *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments), e preparare l’attività per l’espansione in altri Paesi, supportando al tempo stesso le nuove normative e i metodi di pagamento locali.

La creazione di un’integrazione con l’API Payment Intents comporta due azioni: creazione e *conferma* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) 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](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). La guida descrive come creare un PaymentIntent sul server e passare al client la relativa *chiave privata client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) anziché l’intero oggetto PaymentIntent.

Quando [crei il PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md), puoi specificare opzioni quali l’importo e la valuta:

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

### Pratiche ottimali

- Ti consigliamo di creare un PaymentIntent non appena conosci l’importo, ad esempio quando il cliente avvia la procedura di checkout, per monitorare meglio il tuo [funnel di acquisto](https://en.wikipedia.org/wiki/Purchase_funnel). Se l’importo cambia, puoi [aggiornare](https://docs.stripe.com/api.md#update_payment_intent) tale [importo](https://docs.stripe.com/api.md#payment_intent_object-amount). Ad esempio, se il cliente interrompe la procedura di checkout e aggiunge nuovi articoli al carrello, potrebbe essere necessario aggiornare l’importo quando riprende la procedura di checkout.

- 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](https://docs.stripe.com/api.md#retrieve_payment_intent) 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](https://docs.stripe.com/payments/paymentintents/lifecycle.md) 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](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), 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](https://docs.stripe.com/js.md#stripe-confirm-card-payment) o [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action)) per completare il pagamento.

### Recuperare la chiave privata client

L’oggetto PaymentIntent contiene una *chiave privata client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)), 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.

#### Applicazione a pagina singola

Recupera la chiave privata client dall’endpoint sul server utilizzando la funzione `fetch`del browser. Questo approccio è più adatto quando il lato client è un’applicazione con un’unica pagina, in particolare creata con un framework front-end moderno come React. Crea l’endpoint server che invia la chiave privata client:

#### Ruby

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

Quindi recupera la chiave privata client con JavaScript sul lato client:

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

#### Rendering lato server

Trasmetti la chiave privata client al client dal server. Questo approccio è più adatto se l’applicazione genera contenuti statici sul server prima di inviarli al browser.

Aggiungi la [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) nel modulo di pagamento. Nel codice lato server, recupera la chiave privata client da PaymentIntent:

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

> La chiave privata client può essere utilizzata per completare la procedura di pagamento con l’importo specificato nel PaymentIntent. Non devi registrarla né incorporarla negli URL o esporla a persone diverse dal cliente. Accertati di aver abilitato il protocollo *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) su tutte le pagine che includono la chiave privata client.

## Dopo il pagamento

Una volta che il client avrà confermato il pagamento, la procedura ottimale consiste nel [monitoraggio dei webhook](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) da parte del server per rilevare quando il pagamento va a buon fine o non riesce.

Un `PaymentIntent` potrebbe avere più di un oggetto [addebito](https://docs.stripe.com/api/charges.md) associato se sono stati effettuati più tentativi di pagamento. Ad esempio, i tentativi ripetuti possono creare più tentativi `Charges`. Per ogni addebito puoi esaminare il [risultato](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) e [i dettagli del metodo di pagamento](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) utilizzato.

## Ottimizzazione delle modalità di pagamento per pagamenti futuri

Il parametro [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) salva i metodi 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](https://docs.stripe.com/strong-customer-authentication.md). Per stabilire il valore da utilizzare, valuta in che modo intendi utilizzare questo metodo di pagamento in futuro.

| Come intendi utilizzare la modalità di pagamento                                                                                                                                                 | valore enum setup_future_usage da utilizzare |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| Solo pagamenti *all’interno della sessione* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) | `on_session`                                 |
| Solo pagamenti *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)  | `off_session`                                |
| Pagamenti sia all’interno sia all’esterno della sessione                                                                                                                                         | `off_session`                                |

Con una carta configurata per i pagamenti all’interno della sessione puoi comunque accettare i pagamenti *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), 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
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session
```

> È più probabile che le configurazioni per i pagamenti all’esterno della sessione presentino un livello di complessità più alto. Usa la configurazione *all’interno della sessione* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) se non hai intenzione di accettare pagamenti al’esterno della sessione con la carta salvata.

## Voce di estratto conto dinamica

Per impostazione predefinita, la [voce per gli estratti conto](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) del tuo account Stripe compare sugli estratti conto dei clienti ogni volta che effettui un addebito sulla loro carta. Per inserire una descrizione diversa per ogni singolo pagamento, utilizza il parametro [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor).

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "statement_descriptor_suffix=Custom descriptor"
```

> #### Nota
> 
> Utilizza il parametro `statement_descriptor` per gli addebiti senza carta e `statement_descriptor_suffix` per gli addebiti con carta.

Le [voci per gli estratti conto](https://docs.stripe.com/get-started/account/statement-descriptors.md) 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 per gli estratti conto dinamiche, il testo dinamico viene aggiunto dopo il [prefisso della voce per gli estratti conto](https://dashboard.stripe.com/settings/public) impostata nella Dashboard Stripe. Vengono aggiunti anche un asterisco (`*`) e uno spazio vuoto per separare la voce per gli estratti 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](https://docs.stripe.com/api.md#metadata) 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* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), puoi specificare come metadati informazioni aggiuntive sui clienti e sugli ordini. Poi puoi scrivere [regole Radar con gli attributi dei metadati](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) 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
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=6735"
```

> Non archiviare dati sensibili (informazioni sull’identità, dati di carte, ecc.) come metadati o nel parametro `description` del PaymentIntent.

## See also

- [Accettare un pagamento online](https://docs.stripe.com/payments/accept-a-payment.md?platform=web)
- [Accetta un pagamento tramite un’app iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios)
- [Accetta un pagamento tramite un’app Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)
- [Configurare pagamenti futuri](https://docs.stripe.com/payments/save-and-reuse.md)