Aggiornamenti di stato dei pagamenti

I PaymentIntent 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 nelle impostazioni utente.

Controllare lo stato del PaymentIntent sul client

Quando completi un pagamento sul client con la funzione confirmCardPayment, puoi ispezionare il PaymentIntent restituito per determinarne lo stato corrente:

(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:

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). 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 e passando la chiave privata client.

Di seguito sono riportati alcuni stati possibili del PaymentIntent successivi a una conferma:

Ulteriori informazioni sugli stati di PaymentIntent.

(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
  }
})();

Monitorare un PaymentIntent con i webhook

Stripe può inviare eventi webhook 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 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.

Per gestire un evento webhook, crea un route sul server e configura un endpoint del webhook corrispondente nella Dashboard. 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:

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:

Per verificare localmente i webhook puoi utilizzare la CLI di Stripe. Dopo averla installata, puoi inoltrare gli eventi al server:

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.

Identificare gli addebiti in un PaymentIntent

Quando tenti di riscuotere un pagamento da un cliente, il PaymentIntent crea un addebito. Per recuperare l’ID dell’addebito più recente, esamina la proprietà latest_charge di PaymentIntent:

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

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 e specifica il parametro payment_intent​.

curl -G https://api.stripe.com/v1/charges \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=
{{PAYMENT_INTENT_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 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 della modalità di pagamento. Puoi trovare un elenco delle azioni successive possibili nella documentazione API.

Consulta la documentazione relativa alle modalità di pagamento per ulteriori dettagli su come gestire le azioni successive necessarie.