# Aggiornamenti di stato dei pagamenti

Monitorare e verificare lo stato pagamento in modo da poter rispondere ai pagamenti riusciti e non riusciti.

I *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) si aggiornano in risposta alle azioni intraprese dal cliente o alla modalità di pagamento. L’integrazione può ispezionare il PaymentIntent per determinare lo stato della procedura di pagamento, consentendoti così di intraprendere azioni aziendali o di rispondere agli stati che richiedono un ulteriore intervento.

Puoi utilizzare la Dashboard Stripe anche per configurare il tuo account in modo che ti invii un’email sullo stato del pagamento, ad esempio in caso di pagamenti riusciti. Modifica le [notifiche email](https://docs.stripe.com/get-started/account/teams.md#email-notifications) nelle [impostazioni utente](https://dashboard.stripe.com/settings/user).

## Stati dei pagamenti e stati dei PaymentIntent

La pagina [Payments](https://dashboard.stripe.com/payments) della Dashboard mostra per ciascun pagamento uno stato del pagamento che puoi usare per filtrare l’elenco. Questo stato riassume il pagamento ma non include i dettagli aggiuntivi forniti dallo [stato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) del PaymentIntent.

`status` del PaymentIntent tiene traccia dello stato di un pagamento e indica quando quest’ultimo richiede ulteriori elaborazioni o azioni del cliente. Un pagamento che utilizza un PaymentIntent potrebbe richiedere un metodo di pagamento, una conferma o un’altra azione per andare a buon fine. Nella Dashboard questi stati corrispondono a **Incompleto**.

Per comprendere lo stato incompleto di un pagamento, fai clic sul pagamento e usa [Workbench Inspector](https://docs.stripe.com/workbench/overview.md#inspector) per visualizzare i dettagli del PaymentIntent in JSON. Cerca `status` per vederne il valore esatto.

La seguente tabella mappa ogni `status` del PaymentIntent con gli stati dei pagamenti della Dashboard. I casi limite come tentativi scaduti e codici di rifiuto specifici possono influire su questa mappatura. Usa l’API o Workbench Inspector per ottenere lo stato autorevole.

| `status` PaymentIntent | Stato dei pagamenti | Descrizione |
| --- | --- | --- |
| `requires_payment_method` | **Non completato** | In genere, si verifica se non ci sono [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) o se il PaymentIntent non è andato oltre la riscossione. A seconda del metodo di pagamento, degli importi e degli errori, lo stato del pagamento può essere anche **Pagato in parte**, **In attesa dei fondi** o **Non riuscito**. |
| `requires_confirmation` | **Non completato** | Si verifica dopo che il cliente ha fornito le informazioni per il pagamento ed è pronto alla conferma. La maggior parte delle integrazioni salta questo stato perché invia le informazioni del metodo di pagamento al momento della conferma. |
| `requires_action` | **Non completato** | Si verifica quando il pagamento richiede azioni aggiuntive, come l’autenticazione con il protocollo [3D Secure](https://docs.stripe.com/payments/3d-secure.md). In caso di determinate condizioni di autenticazione o di errore, nella Dashboard lo stato del pagamento può risultare anche **Pagato in parte**, **In attesa dei fondi** o **Non riuscito**. |
| `processing` | **In sospeso** | Si verifica quando le azioni richieste sono state completate e il pagamento utilizza un *metodo di pagamento asincrono* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed), come gli addebiti bancari. L’elaborazione di questi metodi di pagamento può richiedere fino a un paio di giorni. |
| `requires_capture` | **Non acquisito** o **Acquisizione parziale** | Si verifica se il tuo flusso utilizza l’[acquisizione separata](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md). Se viene ricevuto qualsiasi importo per il PaymentIntent, lo stato è **Acquisizione parziale**. Se non viene ricevuto alcun importo, lo stato è **Non acquisito**. |
| `succeeded` | **Andato a buon fine** | Un PaymentIntent con stato `succeeded` (andato a buon fine) indica che il flusso di pagamento corrispondente è completo. I fondi si trovano sul tuo account e puoi procedere all’evasione dell’ordine.

Se il tentativo di pagamento non va a buon fine (per esempio a causa di un rifiuto), lo stato del PaymentIntent ritorna a `requires_payment_method` cosicché il pagamento possa essere riprovato.

I rimborsi, le contestazioni e gli esiti successivi si riflettono sull’addebito. Tali eventi potrebbero modificare quanto vedi nella Dashboard, anche se il PaymentIntent rimane con lo stato `succeeded`. |
| `canceled` | **Annullato** | Si verifica in caso di annullamento del pagamento. Se il PaymentIntent è stato annullato come parte di un flusso di fatturazione non riuscito e se l’ultimo addebito non è andato a buon fine, lo stato potrebbe risultare **Non riuscito**. |

## Gestire le azioni successive

Alcuni metodi di pagamento richiedono, per poterne completare l’elaborazione, alcuni passaggi aggiuntivi come l’autenticazione. Stripe.js li gestisce automaticamente quando si conferma il PaymentIntent, ma nel caso di un’integrazione avanzata puoi gestirli manualmente.

La proprietà [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) del PaymentIntent espone il passaggio successivo che la tua integrazione deve gestire per completare il pagamento. Le azioni successive disponibili variano a seconda del metodo di pagamento. Per l’elenco completo, consulta la [documentazione di riferimento dell’API](https://docs.stripe.com/api.md#payment_intent_object-next_action-type).

Come [gestire le azioni successive richieste da un metodo di pagamento](https://docs.stripe.com/payments/payment-methods/overview.md).

## Controllare lo stato del PaymentIntent sul client

Quando completi un pagamento sul client con la funzione [confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment), puoi ispezionare il PaymentIntent restituito per determinarne lo stato corrente:

```javascript
(async () => {
  const {paymentIntent, error} = await stripe.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/complete',
    },
    redirect: 'if_required',
  });
  if (error) {
    // Handle error here
  } else if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  }
})();
```

Di seguito sono riportati i possibili risultati dell’utilizzo della funzione `confirmPayment`:

| **Evento** | **Che cosa è accaduto** | **Integrazione prevista** |
| --- | --- | --- |
| Si risolve con un PaymentIntent | Il cliente ha completato il pagamento sull’apposita pagina | Informa il cliente che il pagamento è riuscito |
| Si risolve con un errore | Il pagamento del cliente non è andato a buon fine sulla pagina di completamento della transazione | Visualizza un messaggio di errore e richiedi al cliente di effettuare un nuovo tentativo di pagamento |

La promessa restituita da `confirmPayment` si risolve quando la procedura di pagamento viene completata o fallisce con un errore. Quando viene completata con esito positivo e restituisce un PaymentIntent, lo stato è sempre `succeeded` (o `requires_capture` in caso di [acquisizione successiva](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)). Quando il pagamento richiede un passaggio aggiuntivo come l’autenticazione, la promessa non si risolve finché tale passaggio non viene completato o scade.

## Verifica lo stato del PaymentIntent sul client senza utilizzare confirmPayment

Per controllare lo stato di un PaymentIntent senza usare la funzione `confirmPayment`, recuperalo in modo indipendente usando la funzione [retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) e passando la *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)).

```javascript
(async () => {
  const {paymentIntent} = await stripe.retrievePaymentIntent(clientSecret);
  if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  } else {
    // Handle unsuccessful, processing, or canceled payments and API errors here
  }
})();
```

Di seguito sono riportati alcuni [stati possibili](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) del PaymentIntent successivi a una conferma:

| **Che cosa è accaduto** | **Stato PaymentIntent previsto** |
| --- | --- |
| Il cliente ha completato il pagamento sull’apposita pagina | `succeeded` |
| Il cliente non ha completato la procedura di pagamento | `requires_action` |
| Il pagamento del cliente non è andato a buon fine sulla pagina di completamento della transazione | `requires_payment_method` |

[Ulteriori informazioni sugli stati di PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md).

## Monitorare un PaymentIntent con i webhook

Stripe può inviare eventi *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) al tuo server per avvisarti quando lo stato di un PaymentIntent cambia, che potresti utilizzare per determinare il momento in cui evadere l’ordine di beni e servizi.

Non tentare di gestire l’'*evasione* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) ordini sul lato client perché i clienti possono abbandonare la pagina una volta completato il pagamento, ma prima dell’inizio della procedura di evasione. Utilizza invece i webhook per monitorare l’evento `payment_intent.succeeded` e gestirne il completamento in modo asincrono anziché tentare di avviare l’evasione ordini sul lato client.

> Da un punto di vista tecnico è possibile utilizzare il polling anziché i webhook per monitorare le modifiche generate dalle operazioni asincrone, recuperando ripetutamente un PaymentIntent in modo da controllarne lo stato, ma questo approccio è decisamente meno affidabile e potrebbe causare problemi di limitazione della velocità. Stripe applica [limiti di velocità](https://docs.stripe.com/testing.md#rate-limits) alle richieste API, pertanto si consiglia di prestare attenzione se si decide di utilizzare il polling.

Per gestire un evento webhook, crea un route sul server e configura un endpoint del webhook corrispondente [nella Dashboard](https://dashboard.stripe.com/account/webhooks). Stripe invia l’evento `payment_intent.succeeded` quando il pagamento riesce e l’evento `payment_intent.payment_failed` quando il pagamento non riesce.

Il payload del webhook include l’oggetto PaymentIntent. Il seguente esempio mostra come gestire entrambi gli eventi:

#### Ruby

```ruby
require 'sinatra'
require 'stripe'

post '/webhook' do
    payload = request.body.read
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    event = nil

    begin
        event = Stripe::Webhook.construct_event(
            payload, sig_header, endpoint_secret
        )
    rescue JSON::ParserError => e
        # Invalid payload
        status 400
        return
    rescue Stripe::SignatureVerificationError => e
        # Invalid signature
        status 400
        return
    end

    case event['type']
    when 'payment_intent.succeeded'
        intent = event['data']['object']
        puts "Succeeded:", intent['id']
        # Fulfill the customer's purchase
    when 'payment_intent.payment_failed'
        intent = event['data']['object']
        error_message = intent['last_payment_error'] && intent['last_payment_error']['message']
        puts "Failed:", intent['id'], error_message
        # Notify the customer that payment failed
    end

    status 200
end
```

Quando il pagamento non va a buon fine, puoi visualizzare maggiori dettagli ispezionando la proprietà `last_payment_error` del PaymentIntent. Puoi informare il cliente che il suo pagamento non è stato completato e invitarlo a riprovare con una modalità diversa. Riutilizza lo stesso PaymentIntent per continuare il monitoraggio dell’acquisto del cliente.

### Gestire eventi webhook specifici

La tabella seguente descrive come gestire gli eventi webhook:

| Evento | Descrizione | Passaggi successivi |
| --- | --- | --- |
| `processing` | Il pagamento del cliente è stato inviato a Stripe. Applicabile solo ai metodi di pagamento con [conferma di operazione riuscita posticipata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Attendi che il pagamento avviato vada o meno a buon fine |
| `succeeded` | Il pagamento del cliente è andato a buon fine. | Evadi l’ordine delle merci o dei servizi acquistati. |
| `amount_capturable_updated` | Il pagamento del cliente è stato autorizzato ed è pronto per essere addebitato. | Addebita i fondi disponibili per il pagamento. |
| `payment_failed` | Il pagamento del cliente è stato rifiutato dal circuito della carta o è scaduto. | Contatta il cliente tramite email o notifica push e chiedigli di fornire un’altra modalità di pagamento. |

Per verificare localmente i webhook puoi utilizzare la [CLI di Stripe](https://docs.stripe.com/stripe-cli.md). Dopo averla installata, puoi inoltrare gli eventi al server:

```bash
stripe listen --forward-to localhost:4242/webhook
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

Ulteriori informazioni sulla [configurazione dei webhook](https://docs.stripe.com/webhooks.md).

## Identificare gli addebiti in un PaymentIntent

Quando tenti di riscuotere un pagamento da un cliente, il PaymentIntent crea un [addebito](https://docs.stripe.com/api/charges.md). Per recuperare l’ID dell’addebito più recente, esamina la proprietà [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) di PaymentIntent:

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

intent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}')
latest_charge = intent.latest_charge
```

Per visualizzare tutti gli addebiti associati a un PaymentIntent, inclusi eventuali addebiti non riusciti, [elenca tutti gli addebiti](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent) e specifica il parametro `payment_intent​`.

```curl
curl -G https://api.stripe.com/v1/charges \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_intent={{PAYMENTINTENT_ID}}"
```