Passa al contenuto
Crea account
 o
Accedi
Il logo della documentazione Stripe
/
Crea un account
Accedi

Gestione degli errori

Rilevare o rispondere a rifiuti, dati non validi, problemi di rete e molto altro ancora

Copia pagina

Stripe offre svariate tipologie di errori, i quali possono rappresentare eventi esterni, come i pagamenti rifiutati e le interruzioni di rete, oppure problemi legati al codice, come le chiamate API non valide.

Per gestire gli errori, usa alcune delle o tutte le tecniche riportate nella tabella che segue. Indipendentemente dalla tecnica che scegli, puoi monitorare la situazione con le nostre risposte consigliate per ciascun tipo di errore.

TecnicaScopoQuando è necessario
Rilevare le eccezioniRipristino se una chiamata API non può proseguireSempre
Monitorare i webhookReazione alle notifiche da StripeA volte
Ottenere informazioni salvate sugli erroriAnalisi di problemi passati e supporto di altre tecnicheA volte

Rilevare le eccezioni

Se un problema immediato impedisce a una chiamata API di proseguire, la libreria Ruby di Stripe genera un’eccezione. La cosa migliore da fare è rilevare e gestire le eccezioni.

Per rilevare un’eccezione, usa la parola chiave rescue di Ruby. Rileva Stripe::StripeError o le relative sottoclassi solo per gestire eccezioni specifiche di Stripe. Ogni sottoclasse rappresenta un tipo diverso di eccezione. Quando rilevi un’eccezione, puoi usare la sua classe per scegliere una risposta.

require 'stripe'

Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

Dopo aver configurato la gestione delle eccezioni, testala con dati diversi, tra cui le carte di test, per simulare diversi esiti di pagamento.

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
An invalid request occurred.

Monitorare i webhook

Stripe utilizza i webhook per informarti in merito a svariate tipologie di problemi, tra cui quelli che non seguono immediatamente le chiamate API. Ad esempio:

  • Perdi una contestazione.
  • Un pagamento ricorrente dà esito negativo dopo mesi di esiti positivi.
  • Il tuo front-end conferma un pagamento ma va offline prima di scoprire che il pagamento non è andato a buon fine (il back-end riceve comunque la notifica del webhook, anche se non è stato lui a effettuare la chiamata API).

Non occorre che tu gestisca ogni tipo di evento webhook. Infatti, alcune integrazioni non li gestiscono affatto.

Nel tuo gestore di webhook, inizia dai passagggi base previsti nello sviluppatore dei webhook: ottieni un oggetto evento e usa il tipo di evento per scoprire cos’è successo. Quindi, se il tipo di evento indica un errore, attieniti a questi ulteriori passaggi:

  1. Accedi a event.data.object per recuperare l’oggetto interessato.
  2. Usa le informazioni salvate sull’oggetto interessato per capirne il contesto, compreso un oggetto errore.
  3. Usa il suo tipo per scegliere una risposta.
require 'stripe'
require 'sinatra'
post '/webhook' do
  payload = request.body.read
  data = JSON.parse(payload, symbolize_names: true)

  # Get the event object
  event = Stripe::Event.construct_from(data)

  # Use the event type to find out what happened
  case event.type
  when 'payment_intent.payment_failed'

    # Get the object affected
    payment_intent = event.data.object

    # Use stored information to get an error object
    e = payment_intent.last_payment_error

    # Use its type to choose a response
    case e.type
    when 'card_error'
      puts "A payment error occurred: #{e.message}"
    when 'invalid_request'
      puts "An invalid request occurred."
    else
      puts "Another problem occurred, maybe unrelated to Stripe."
    end
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

Per testare il modo in cui l’integrazione risponde agli eventi webhook, puoi attivare eventi webhook in locale. Una volta completata la procedura di configurazione a quel link, attiva un pagamento non riuscito per vedere il messaggio di errore che ne risulta.

Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.

Ottenere informazioni salvate sugli errori

Molti oggetti salvano informazioni sugli errori. Ciò significa che, se qualcosa era già andato storto, puoi recuperare l’oggetto ed esaminarlo per saperne di più. In molti casi, le informazioni salvate hanno la forma di un oggetto errore, e potrai usarne il tipo per scegliere una risposta.

Ad esempio:

  1. Recuperare un Payment Intent specifico.
  2. Controllare se si è verificato un errore legato al pagamento determinando se il campo last_payment_error è vuoto.
  3. Se si è verificato, registrare l’errore, compreso il tipo e l’oggetto interessato.
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

Ecco alcuni oggetti comuni che salvano informazioni sugli errori.

OggettoAttributoValori
Payment Intentlast_payment_errorUn oggetto errore
Setup Intentlast_setup_errorUn oggetto errore
Fatturalast_finalization_errorUn oggetto errore
Setup Attemptsetup_errorUn oggetto errore
Payoutfailure_codeUn codice di bonifico non riuscito
Rimborsofailure_reasonUn codice di rimborso non riuscito

Per testare il codice che utilizza le informazioni salvate sugli errori, spesso è necessario simulare le transazioni non riuscite. Per farlo, nella gran parte dei casi puoi utilizzare le carte di test o i numeri di conto bancario di test. Ad esempio:

Tipi di errori e risposte

Nella libreria Ruby di Stripe, gli oggetti errore appartengono a stripe.error.StripeError e alle relative sottoclassi. Leggi la documentazione relativa a ciascuna classe per sapere come rispondere.

Nome

Classe

Descrizione
Errore legato al pagamento

Stripe::CardError

Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni:
Errore di richiesta non valida

Stripe::InvalidRequestError

Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido.

Errore di connessione

Stripe::APIConnectionError

Si è verificato un problema di rete tra il tuo server e Stripe.
Errore API

Stripe::APIError

Si è verificato un problema lato Stripe (questi casi sono rari).
Errore di autenticazione

Stripe::AuthenticationError

Stripe non può autenticarti con le informazioni fornite.
Errore di idempotenza

Stripe::IdempotencyError

You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Errore di autorizzazione

Stripe::PermissionError

La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie.
Errore di limitazione della velocità

Stripe::RateLimitError

Hai effettuato troppe chiamate API in troppo poco tempo.
Errore di verifica di firma

Stripe::SignatureVerificationError

You’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

Errori legati al pagamento

Gli errori legati al pagamento (a volte definiti anche “errori carte” per motivi storici) abbracciano un’ampia gamma di problemi comuni, suddivisibili in tre categorie:

To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Users on API version 2022-08-01 or older:

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Puoi attivare alcuni tipi comuni di errori legati al pagamento con le carte di test. Consulta questi elenchi di opzioni:

Il codice di test che segue mostra alcune possibilità.

example_function(
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
)
console
Payment blocked for suspected fraud.

Pagamento bloccato per sospetta frode

Tipo

Stripe::CardError

Codici
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
Codici

e.error.payment_intent.charges.data[0].outcome.type == 'blocked'

ProblemaIl sistema di prevenzione delle frodi di Stripe, Radar, ha bloccato il pagamento

Soluzioni

Questo errore può verificarsi quando l’integrazione funziona correttamente. Rilevalo e suggerisci al cliente una modalità di pagamento diversa.

Per bloccare un numero inferiore di pagamenti legittimi, prova queste soluzioni:

I clienti che usano Radar for Fraud Teams hanno a disposizione queste opzioni aggiuntive:

  • Per esentare un pagamento in particolare, aggiungilo al tuo elenco di consenso. Radar for Fraud Teams
  • To change your risk tolerance, adjust your risk settings. Radar for Fraud Teams
  • To change the criteria for blocking a payment, use custom rules. Radar for Fraud Teams

You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation.

Pagamento rifiutato dalla società emittente

Tipo

Stripe::CardError

Codici

e.error.code == "card_declined"

ProblemaLa società emittente della carta ha rifiutato il pagamento.

Soluzioni

This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action might be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code.

Puoi anche:

Test how your integration handles declines with test cards that simulate successful and declined payments.

Altri errori legati al pagamento

Tipo

Stripe::CardError

ProblemaSi è verificato un altro errore legato al pagamento.
SoluzioniThis error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code.

Errori di richiesta non valida

Tipo

Stripe::InvalidRequestError

ProblemaHai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido.
SoluzioniNella maggior parte dei casi, il problema riguarda la richiesta stessa: i suoi parametri non sono validi oppure non può essere effettuata nello stato attuale in cui si trova la tua integrazione.
  • Consult the error code documentation for details on the problem.
  • Per comodità, segui il link a in cui troverai della documentazione sul codice di errore.
  • Se l’errore riguarda un parametro specifico, usa per stabilire quale.

Errori di connessione

Tipo

Stripe::APIConnectionError

ProblemaSi è verificato un problema di rete tra il tuo server e Stripe.

Soluzioni

Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that it failed.

Per verificare se ha avuto esito positivo, puoi:

  • Recuperare l’oggetto pertinente da Stripe e verificarne lo stato.
  • Ascoltare la notifica del webhook che indica se l’operazione ha avuto esito positivo o negativo.

To help recover from connection errors, you can:

  • When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. Repeat the request with the same idempotency key until you receive a clear success or failure. For advanced advice on this strategy, see Low-level error handling.
  • Attivare la ripetizione automatica dei tentativi. Quindi, Stripe genera per te le chiavi di idempotenza e ripete le richieste quando è sicuro farlo.

Questo errore può celarne altri, per cui è possibile che una volta risolto l’errore di connessione, ne compaiano altri. Verifica la presenza di errori in tutte queste soluzioni, proprio come faresti nella richiesta originale.

Errori API

Tipo

Stripe::APIError

ProblemaSi è verificato un problema lato Stripe (questi casi sono rari).

Soluzioni

Tratta il risultato della chiamata API come indeterminato, ovvero non supporre che abbia avuto esito positivo o negativo.

Usa i webhook per ricavare informazioni sull’esito. Quando possibile, Stripe genera dei webhook per tutti gli oggetti nuovi creati man mano che risolviamo un problema.

To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors.

Errori di autenticazione

Tipo

Stripe::AuthenticationError

ProblemaStripe non può autenticarti con le informazioni fornite.
Soluzioni

Errori di idempotenza

Tipo

Stripe::IdempotencyError

ProblemaYou used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Soluzioni
  • Una volta utilizzata, la chiave di idempotenza può essere riutilizzata per chiamate API identiche.
  • Usa chiavi di idempotenza inferiori a 255 caratteri.

Errori di autorizzazione

Tipo

Stripe::PermissionError

ProblemaThe API key used for this request doesn’t have the necessary permissions.
Soluzioni
  • Make sure you aren’t using a restricted API key for a service it doesn’t have access to.
  • Don’t perform actions in the Dashboard while logged in as a user role that lacks permission.

Errori di limitazione della velocità

Tipo

Stripe::RateLimitError

ProblemaHai effettuato troppe chiamate API in troppo poco tempo.
Soluzioni
  • Se una sola chiamata API attiva questo errore, attendi e riprova.
  • To handle rate-limiting automatically, retry the API call after a delay, and increase the delay exponentially if the error continues. See the documentation on rate limits for further advice.
  • Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, contatta l’assistenza in anticipo.

Errori di verifica di firma

Tipo

Stripe::SignatureVerificationError

ProblemaYou’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

Soluzioni

Questo errore può verificarsi quando la tua integrazione funziona correttamente. Se usi la verifica di firma del webhook e una terza parte tenta di inviarti un webhook falso o dannoso, la verifica ha esito negativo e questo errore è il risultato. Rilevalo e rispondi con un codice stato 400 Bad Request.

If you receive this error when you shouldn’t—for instance, with webhooks that you know originate with Stripe—then see the documentation on checking webhook signatures for further advice. In particular, make sure you’re using the correct endpoint secret. This is different from your API key.

Questa pagina è stata utile?
SìNo
Hai bisogno di aiuto? Contatta l'assistenza clienti.
Partecipa al nostro programma di accesso anticipato.
Dai un'occhiata al nostro registro delle modifiche.
Domande? Contattaci.
LLM? Leggi llms.txt.
Realizzato da Markdoc