# 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).

## Controllare lo stato del PaymentIntent sul client

Quando completi un pagamento sul client con la funzione [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment), puoi ispezionare il PaymentIntent restituito per determinarne lo stato corrente:

```javascript
(async () => {
  const {paymentIntent, error} = await stripe.confirmCardPayment(clientSecret);
  if (error) {
    // Handle error here
  } else if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  }
})();
```

Di seguito sono riportati i possibili effetti dell’uso della funzione `confirmCardPayment`:

| **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 `confirmCardPayment` si risolve quando la procedura di pagamento è stata completata o non è andata a buon fine con un errore. Se la procedura viene completata correttamente e restituisce un PaymentIntent, lo stato è sempre `succeeded` (o `requires_capture` in caso di [addebito successivo](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)). Se il pagamento richiede un passaggio aggiuntivo come l’autenticazione, la promessa non si risolve finché tale passaggio non è stato completato o è scaduto.

## Controllare lo stato del PaymentIntent sul client senza utilizzare confirmCardPayment

Per controllare lo stato di un PaymentIntent senza la funzione `confirmCardPayment`, recupera il PaymentIntent in modo indipendente utilizzando 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`                | The customer’s payment was submitted to Stripe successfully. Only applicable to payment methods with [delayed success confirmation](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Attendi che il pagamento avviato vada o meno a buon fine                                                         |
| `succeeded`                 | The customer’s payment succeeded.                                                                                                                                                                              | Fulfill the purchased goods or services.                                                                         |
| `amount_capturable_updated` | The customer’s payment is authorized and ready for capture.                                                                                                                                                    | Capture the funds that are available for payment.                                                                |
| `payment_failed`            | The customer’s payment was declined by a card network or otherwise expired.                                                                                                                                    | Reach out to your customer through email or push notification and prompt them to provide another payment method. |

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.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

intent = Stripe::PaymentIntent.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}}"
```

## Gestire le azioni successive

Alcune modalità di pagamento prevedono passaggi aggiuntivi, come l’autenticazione, per completare la procedura di pagamento. Stripe.js gestisce queste operazioni automaticamente alla conferma del PaymentIntent ma, se hai un’integrazione avanzata, potresti preferire la gestione manuale.

La proprietà [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) del PaymentIntent visualizza il passaggio successivo che l’integrazione deve gestire per completare il pagamento. Il tipo di azioni successive possibili può variare a seconda del metodo di pagamento. Puoi trovare un elenco delle azioni successive possibili nella [documentazione API](https://docs.stripe.com/api.md#payment_intent_object-next_action-type).

Consulta la [documentazione relativa ai metodi di pagamento](https://docs.stripe.com/payments/payment-methods/overview.md) per ulteriori dettagli su come gestire le azioni successive necessarie.