Gestione degli errori
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.
Tecnica | Scopo | Quando è necessario |
---|---|---|
Usare valori di errore | Ripristino se una chiamata API non può proseguire | Sempre |
Monitorare i webhook | Reazione alle notifiche da Stripe | A volte |
Ottenere informazioni salvate sugli errori | Analisi di problemi passati e supporto di altre tecniche | A volte |
Usare valori di 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.
, 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.
Dopo aver configurato la gestione delle eccezioni, testala con dati diversi, tra cui le carte di test, per simulare diversi esiti di pagamento.
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:
- Ottieni l’oggetto interessato effettuando l’unmarshalling dei dati da
event.
.Data. Raw - Usa le informazioni salvate sull’oggetto interessato per capirne il contesto, compreso un oggetto errore.
- Usa il suo tipo per scegliere una risposta.
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.
stripe trigger payment_intent.payment_failed
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.
Ecco alcuni oggetti comuni che salvano informazioni sugli errori.
Oggetto | Attributo | Valori |
---|---|---|
Payment Intent | last_ | Un oggetto errore |
Setup Intent | last_ | Un oggetto errore |
Fattura | last_ | Un oggetto errore |
Setup Attempt | setup_ | Un oggetto errore |
Payout | failure_ | Un codice di bonifico non riuscito |
Rimborso | failure_ | Un 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 | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: | |
Errore di richiesta non valida | Hai effettuato una chiamata API in una modalità al momento non valida. Sono inclusi i seguenti casi: | |
Errore API | Si è verificato un problema lato Stripe (questi casi sono rari). | |
Errore di idempotenza | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Errori carte
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
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.)
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.)
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à.
Blocco per sospetta frode
Tipo |
|
Codici |
|
Codici |
|
Problema | Il 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:
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. |
Rifiuto da parte della società emittente
Tipo |
|
Codici |
|
Problema | La 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 may 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 |
|
Problema | Si è verificato un altro errore legato al pagamento. |
Soluzioni | This 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
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.
) e consulta la documentazione sui codici di errore per trovare una soluzione. Alcuni codici richiedono una risposta particolare:
rate_
elimit lock_
rappresentano errori di limitazione della velocitàtimeout secret_
rappresenta un errore di autenticazionekey_ required - Altri codici di errore rappresentano uno stato o parametri non validi
Errori di limitazione della velocità
Tipo |
|
Codici | stripeErr. |
Problema | Hai effettuato troppe chiamate API in troppo poco tempo. |
Soluzioni |
|
Errori di autenticazione
Tipo |
|
Codici | stripeErr. |
Problema | Stripe non può autenticarti con le informazioni fornite. |
Soluzioni |
|
Stato o parametri non validi
Tipo |
|
Codici | stripeErr. |
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.
|
Errori API
Tipo |
|
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. To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors. |
Errori di idempotenza
Tipo |
|
Problema | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Soluzioni |
|