Rilevare o rispondere a rifiuti, dati non validi, problemi di rete e molto altro ancora
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.
Analisi di problemi passati e supporto di altre tecniche
A 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.
defexample_function(params)beginStripe::PaymentIntent.create(params)rescueStripe::CardError=> e
puts "A payment error occurred: #{e.error.message}"rescueStripe::InvalidRequestError=> e
puts "An invalid request occurred."rescueStripe::StripeError=> e
puts "Another problem occurred, maybe unrelated to Stripe."else
puts "No error."endend
Dopo aver configurato la gestione delle eccezioni, testala con dati diversi, tra cui le carte di test, per simulare diversi esiti di pagamento.
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:
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 happenedcase 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 responsecase 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."endend
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:
Recuperare un Payment Intent specifico.
Controllare se si è verificato un errore legato al pagamento determinando se il campo last_payment_error è vuoto.
Se si è verificato, registrare l’errore, compreso il tipo e l’oggetto interessato.
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:
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.
Stai usando la verifica della firma del webhook e non abbiamo potuto verificare l’autenticità di un evento webhook.
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:
La società emittente della carta ha rifiutato il pagamento.
Soluzioni
Questo errore può verificarsi quando la tua integrazione funziona correttamente. Riflette un’azione della società emittente, che potrebbe essere legittima. Usa il codice di rifiuto per stabilire quali siano i passaggi successivi più appropriati. Consulta la documentazione sui codici di rifiuto per sapere come rispondere in modo appropriato a ciascun codice.
Si è verificato un altro errore legato al pagamento.
Soluzioni
Questo errore può verificarsi quando l’integrazione funziona correttamente. Usa il codice di errore per stabilire quali siano i passaggi successivi più appropriati. Consulta la documentazione sui codici di errore per sapere come rispondere in modo appropriato a ciascun codice.
Errori di richiesta non valida
Tipo
Stripe::InvalidRequestError
Problema
Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido.
Soluzioni
Nella 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.
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
Problema
Si è verificato un problema di rete tra il tuo server e Stripe.
Soluzioni
Tratta il risultato della chiamata API come indeterminato, ovvero non supporre che abbia avuto esito positivo o negativo.
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.
Per semplificare il recupero dagli errori di connessione, puoi:
Quando crei o aggiorni un oggetto, utilizza una chiave di idempotenza. Quindi, se si verifica un errore di connessione, puoi ripetere la richiesta senza correre il rischio di creare un secondo oggetto o di eseguire l’aggiornamento due volte. Ripeti la richiesta con la stessa chiave di idempotenza fino a quando non riceverai un esito positivo o negativo chiaro. Per informazioni dettagliate su questa strategia, consulta Gestione degli errori di basso livello.
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
Problema
Si è 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.
Are you performing an action in the Dashboard while logged in as a user role that lacks permission?
Errori di limitazione della velocità
Tipo
Stripe::RateLimitError
Problema
Hai effettuato troppe chiamate API in troppo poco tempo.
Soluzioni
Se una sola chiamata API attiva questo errore, attendi e riprova.
Per gestire la limitazione di frequenza in automatico, ritenta la chiamata API dopo un ritardo e, se l’errore persiste, aumenta il ritardo in modo esponenziale. Per saperne di più, consulta la documentazione sui limiti di velocità.
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
Problema
Stai usando la verifica della firma del webhook e non abbiamo potuto verificare l’autenticità di un evento webhook.
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.
Se ricevi questo errore quando non dovresti (ad esempio, con webhook che sai che provengono da Stripe) consulta la documentazione relativa alla verifica delle firme dei webhook in cui troverai ulteriori informazioni uliti. In particolare, assicurati di usare la chiave privata dell’endpoint corretta, che è diversa dalla tua chiave API.
Welcome to the Stripe Shell!
Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.
- View supported Stripe commands:
- Find webhook events:
- Listen for webhook events:
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
La shell di Stripe offre prestazioni ottimali in versione desktop.