Passa al contenuto
Crea account
o
Accedi
Il logo della documentazione Stripe
/
Chiedi all'IA
Crea un account
Accedi
Inizia
Pagamenti
Ricavi
Per piattaforme e marketplace
Gestione del denaro
Strumenti di sviluppo
Panoramica
Controllo delle versioni
Log modifiche
Aggiorna la tua versione API
Aggiornare la versione dell'SDK
Strumenti di sviluppo
SDK
API
    API v2
    Chiavi API
    Intestazione Stripe-Context
    Log delle modifiche giornaliero
    Limiti di frequenza
    Test automatici
    Metadati
    Ampliare le risposte
    Paginazione
    Domini e indirizzi IP
    Cerca
    Localizzazione
    Gestione degli errori
      Gestione avanzata degli errori
    Codici di errore
Test
Workbench
Destinazioni degli eventi
Flussi di lavoro
CLI di Stripe
Shell di Stripe
Dashboard per sviluppatori
Toolkit agente
Sviluppare con gli LLMStripe per Visual Studio CodeAvvisi sullo stato di StripeCaricamenti file
Sicurezza e privacy
Sicurezza
Privacy
Estendi Stripe
Stripe Apps
Connettori Stripe
Partner
Partner Ecosystem
Certificazione di partner
Pagina inizialeStrumenti di sviluppoAPI

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
Usare valori di erroreRipristino 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

Usare valori di errore

Errori e HTTP

Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce in valori di errore.

Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a Gestione delle eccezioni di basso livello e all’oggetto errore.

Le chiamate API nella libreria Go di Stripe restituiscono un valore di risultato e un valore di errore. Usa le assegnazioni multiple per acquisirli entrambi. Se il valore di errore è diverso da nil, significa che un problema immediato ha impedito alla chiamata API di proseguire.

Se il valore di errore è correlato a Stripe, puoi trasmetterlo a un oggetto stripe.Error, che dispone di campi che descrivono il problema. Usa il campo Tipo per scegliere una risposta. In alcuni casi, puoi assegnare la proprietà Err a un tipo di errore più specifico con informazioni aggiuntive.

Go
package main import ( "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/paymentintent" "log" ) func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { switch stripeErr.Type { case stripe.ErrorTypeCard: log.Println("A payment error occurred:", stripeErr.Msg) case stripe.ErrorTypeInvalidRequest: log.Println("An invalid request occurred.") default: log.Println("Another Stripe error occurred.") } } else { log.Println("An error occurred that was unrelated to Stripe.") } } }

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

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), // The required parameter currency is missing Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_visa"
), } example_function(params)
console
Go
1749848100 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. Ottieni l’oggetto interessato effettuando l’unmarshalling dei dati da event.Data.Raw.
  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.
Go
package main import ( "encoding/json" "io/ioutil" "log" "net/http" "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/webhook" ) func main() { http.HandleFunc("/webhook", handleWebhook) addr := "localhost:4242" log.Printf("Listening on %s", addr) log.Fatal(http.ListenAndServe(addr, nil)) } func handleWebhook(w http.ResponseWriter, req *http.Request) { const MaxBodyBytes = int64(65536) req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes) payload, err := ioutil.ReadAll(req.Body) if err != nil { log.Printf("Error reading request body: %v\n", err) w.WriteHeader(http.StatusServiceUnavailable) return } // Replace this endpoint secret with your endpoint's unique secret // If you are testing with the CLI, find the secret by running 'stripe listen' // If you are using an endpoint defined with the API or dashboard, look in your webhook settings // at https://dashboard.stripe.com/webhooks endpointSecret := "whsec_..." signatureHeader := req.Header.Get("Stripe-Signature") // Get an event object event, err := webhook.ConstructEvent(payload, signatureHeader, endpointSecret) if err != nil { log.Printf("⚠️ Webhook signature verification failed. %v\n", err) w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature return } // Use its type to find out what happened switch event.Type { case "payment_intent.payment_failed": // Get the object affected by unmarshalling event data into // the appropriate struct for the event type var paymentIntent stripe.PaymentIntent err := json.Unmarshal(event.Data.Raw, &paymentIntent) if err != nil { log.Printf("Error parsing webhook JSON: %v\n", err) w.WriteHeader(http.StatusBadRequest) return } // Use stored data to get an error object e := paymentIntent.LastPaymentError // Use its type to choose a response switch e.Type { case "card_error": log.Println("A payment error occurred: ", e.Msg) case "invalid_request": log.Println("An invalid request occurred.") default: log.Println("Another problem occurred, maybe unrelated to Stripe.") } default: log.Println("Unhandled event type: ", event.Type) } w.WriteHeader(http.StatusOK) }

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.
Go
stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
pi, _ := paymentintent.Get(
"{{PAYMENT_INTENT_ID}}"
, nil, ) paymentErr := pi.LastPaymentError if paymentErr != nil { log.Printf("PaymentIntent %s experienced a %s error.", pi.ID, paymentErr.Type) }

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:

  • Simula un pagamento rifiutato, per creare addebiti, PaymentIntent, SetupIntent, ecc. non andati a buon fine.
  • Simula un bonifico non riuscito.
  • Simula un rimborso non riuscito.

Tipi di errori e risposte

Nella libreria Go di Stripe, ogni oggetto errore ha un attributo Type. Leggi la documentazione relativa a ciascun tipo per sapere come rispondere.

Nome

Tipo

Descrizione
Errore legato al pagamento

stripe.ErrorTypeCard

Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni:
  • Pagamento bloccato per sospetta frode
  • Pagamento rifiutato dalla società emittente.
  • Altri errori legati al pagamento.
Errore di richiesta non valida

stripe.ErrorTypeInvalidRequest

Hai effettuato una chiamata API in una modalità al momento non valida. Sono inclusi i seguenti casi:

  • Errore di limitazione della velocità
  • Errore di autenticazione
  • Stato o parametri non validi
Errore API

stripe.ErrorTypeAPI

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

stripe.ErrorTypeIdempotency

Hai usato una chiave di idempotenza per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi.

Errori carte

Errori legati al pagamento senza carta

Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo stripe.ErrorTypeCard. In realtà, possono rappresentare un problema con qualsiasi pagamento, indipendentemente dal metodo di 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:

  • Pagamento bloccato per sospetta frode
  • Pagamento rifiutato dalla società emittente
  • Altri errori legati al pagamento

Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il codice di errore, il codice di rifiuto e l’esito dell’addebito.

(Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il Payment Intent coinvolto e l’ultimo addebito che ha creato. Vedi l’esempio che segue per una dimostrazione.)

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) if charge.Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

Utenti con versione API 2022-08-01 o precedente:

(Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il Payment Intent coinvolto e l’ultimo addebito che ha creato. Vedi l’esempio che segue per una dimostrazione.)

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { if stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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

  • Simulazione di pagamenti bloccati per rischio di frode
  • Simulazione di pagamenti rifiutati e altri errori delle carte

Il codice di test che segue mostra alcune possibilità.

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), Currency: stripe.String(string(stripe.CurrencyUSD)), Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_radarBlock"
), } example_function(params)
console
Go
1749848100 Payment blocked for suspected fraud.

Blocco per sospetta frode

Tipo

stripe.ErrorTypeCard

Codici
charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked"
Codici

stripeErr.PaymentIntent.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:

  • Ottimizza l’integrazione Radar per raccogliere informazioni più dettagliate.
  • Utilizza Payment Links, Checkout o Stripe Elements per creare moduli con elementi ottimizzati e preintegrati.

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
  • Per modificare la tolleranza al rischio, regola le tue impostazioni di rischio. Radar for Fraud Teams
  • Per modificare i criteri per bloccare un pagamento, usa le regole personalizzate. Radar for Fraud Teams

Puoi testare le impostazioni della tua integrazione con le carte di test che simulano le frodi. Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella documentazione di Radar.

Rifiuto da parte della società emittente

Tipo

stripe.ErrorTypeCard

Codici

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

ProblemaLa società emittente della carta ha rifiutato il pagamento.

Soluzioni

Questo errore può verificarsi quando l’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.

Puoi anche:

  • Segui le raccomandazioni per ridurre i rifiuti delle società emittenti.
  • Utilizza Payment Links, Checkout o Stripe Elements per creare moduli con elementi preintegrati che implementino tali raccomandazioni.

Verifica il modo in cui la tua integrazione gestisce i rifiuti con le carte di test che simulano pagamenti andati a buon fine e rifiutati.

Altri errori legati al pagamento

Tipo

stripe.ErrorTypeCard

ProblemaSi è verificato un altro errore legato al pagamento.
SoluzioniQuesto 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

Gli errori di richiesta non valida interessano una serie di situazioni. La più comune è quella in cui la richiesta API ha parametri non validi o non è consentita nello stato attuale della tua integrazione. Usa il codice di errore (stripeErr.Code) e consulta la documentazione sui codici di errore per trovare una soluzione. Alcuni codici richiedono una risposta particolare:

  • rate_limit e lock_timeout rappresentano errori di limitazione della velocità
  • secret_key_required rappresenta un errore di autenticazione
  • Altri codici di errore rappresentano uno stato o parametri non validi

Errori di limitazione della velocità

Tipo

stripe.ErrorTypeInvalidRequest

CodicistripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
ProblemaHai 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 ulteriori informazioni, consulta la documentazione sui limiti di frequenza.
  • Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, contatta l’assistenza in anticipo.

Errori di autenticazione

Tipo

stripe.ErrorTypeInvalidRequest

CodicistripeErr.Code == stripe.ErrorCodeSecretKeyRequired
ProblemaStripe non può autenticarti con le informazioni fornite.
Soluzioni
  • Usa la chiave API corretta.
  • Assicurati di non usare una chiave che hai “ruotato” o revocato.

Stato o parametri non validi

Tipo

stripe.ErrorTypeInvalidRequest

CodicistripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired
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.
  • Consulta la documentazione sui codici di errore per ulteriori informazioni sul problema.
  • Per comodità, segui il link a stripeErr.DocURL in cui troverai della documentazione sul codice di errore.
  • Se l’errore riguarda un parametro specifico, usa stripeErr.Param per stabilire quale.

Errori API

Tipo

stripe.ErrorTypeAPI

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.

Affinché la tua integrazione sia il più robusta possibile in situazioni insolite, consulta questa discussione avanzata sugli errori del server.

Errori di idempotenza

Tipo

stripe.ErrorTypeIdempotency

ProblemaHai usato una chiave di idempotenza per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi.
Soluzioni
  • Una volta utilizzata, la chiave di idempotenza può essere riutilizzata per chiamate API identiche.
  • Usa chiavi di idempotenza inferiori a 255 caratteri.
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