# 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. ## Analizzare i dati degli errori Quando Stripe restituisce un errore alla tua richiesta API, ricevi i dettagli sull’errore che ti aiuteranno a capire come applicare le soluzioni suggerite in questa guida. Questi dettagli ti aiutano anche a fornire informazioni importanti all’assistenza Stripe, se necessario. | Proprietà | Descrizione | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Codice di errore. | | `doc_url` | Link alla documentazione Stripe per il codice di errore specifico. | | `message` | Descrizione del motivo dell’errore. | | `param` | Parametro della richiesta che ha causato l’errore. | | `request_log_url` | Link alla Dashboard Stripe dove puoi visualizzare log dettagliati relativi alla richiesta di origine e all’errore. | | ID richiesta | Identificativo univoco della richiesta di origine che ha generato errori. L’intestazione della risposta di errore include questo valore (stringa che inizia con `req`), ma è possibile specificare una stampa nella richiesta, come illustrato negli esempi di codice in questa guida. | | `type` | Riferimento alla categoria di errore a cui appartiene l’errore. | 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](https://docs.stripe.com/error-handling.md#error-types). | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Rilevare le eccezioni](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Rilevare le eccezioni Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce come eccezioni. Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a [Gestione delle eccezioni di basso livello](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). 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](https://docs.stripe.com/error-handling.md#error-types). | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Rilevare le eccezioni](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Rilevare le eccezioni Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce come eccezioni. Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a [Gestione delle eccezioni di basso livello](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). Se un problema immediato impedisce a una chiamata API di proseguire, la libreria Python di Stripe genera un’eccezione. La cosa migliore da fare è rilevare e gestire le eccezioni. Per rilevare un’eccezione, utilizza la sintassi `try`/`except` di Python. Rileva `stripe.StripeError` o le relative sottoclassi per gestire solo eccezioni specifiche di Stripe. Ogni sottoclasse rappresenta un diverso tipo di eccezione. Quando rilevi un’eccezione, puoi [usare la sua classe per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Rilevare le eccezioni](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Rilevare le eccezioni Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce come eccezioni. Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a [Gestione delle eccezioni di basso livello](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). Se un problema immediato impedisce a una chiamata API di proseguire, la libreria PHP di Stripe genera un’eccezione. La cosa migliore da fare è rilevare e gestire le eccezioni. Per rilevare un’eccezione, usa la sintassi `try`/`catch` di PHP. Stripe offre svariate classi di eccezioni che puoi rilevare e ciascuna rappresenta un tipo diverso di errore. Quando rilevi un’eccezione, puoi [usare la sua classe per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Rilevare le eccezioni](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Rilevare le eccezioni Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce come eccezioni. Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a [Gestione delle eccezioni di basso livello](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). Se un problema immediato impedisce a una chiamata API di proseguire, la libreria Java di Stripe genera un’eccezione. La cosa migliore da fare è rilevare e gestire le eccezioni. Per rilevare un’eccezione, usa la sintassi `try`/`catch` di Java. Rileva `StripeException` 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](https://docs.stripe.com/error-handling.md#error-types). | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Rilevare le eccezioni](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Rilevare le eccezioni Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce come eccezioni. Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a [Gestione delle eccezioni di basso livello](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). Se un problema immediato impedisce a una chiamata API di continuare, la libreria Node.js di Stripe può generare un’eccezione. È consigliabile sollevare e gestire le eccezioni. Per abilitare questa funzionalità, eseguire le operazioni seguenti: - Se effettui la chiamata API in una funzione, anteponi la parola chiave `async` alla definizione della funzione. - Anteponi la parola chiave `await` alla stessa chiamata API. - Inserisci la chiamata API in un blocco `try`/`catch`. Quando rilevi un’eccezione, puoi [usare il suo attributo Tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Usare valori di errore](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Usare valori di errore 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](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). 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](https://docs.stripe.com/error-handling.md#error-types). In alcuni casi, puoi assegnare la proprietà `Err` a un tipo di errore più specifico con informazioni aggiuntive. | Tecnica | Scopo | Quando è necessario | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------- | | [Rilevare le eccezioni](https://docs.stripe.com/error-handling.md#catch-exceptions) | Ripristino se una chiamata API non può proseguire | Sempre | | [Monitorare i webhook](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reazione alle notifiche da Stripe | A volte | | [Ottenere informazioni salvate sugli errori](https://docs.stripe.com/error-handling.md#use-stored-information) | Analisi di problemi passati e supporto di altre tecniche | A volte | ## Rilevare le eccezioni Con questa libreria, non è necessario che tu verifichi le risposte HTTP diverse da 200. La libreria le traduce in eccezioni. Qualora dovessi avere bisogno di dettagli HTTP (caso raro), fai riferimento a [Gestione delle eccezioni di basso livello](https://docs.stripe.com/error-low-level.md) e all’oggetto [errore](https://docs.stripe.com/api/errors.md). Se un problema immediato impedisce alla chiamata API di proseguire, la libreria .NET di Stripe genera un’eccezione. La cosa migliore da fare è rilevare e gestire le eccezioni. Per rilevare un’eccezione, usa la sintassi `try`/`catch` di .NET. Rileva una `StripeException`, quindi [usa il suo attributo Tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); error_log("No error."); } catch(\Stripe\Exception\CardException $e) { error_log("A payment error occurred: {$e->getError()->message}. (request id: {$e->getRequestId()})"); } catch (\Stripe\Exception\InvalidRequestException $e) { error_log("An invalid request occurred. (request id: {$e->getRequestId()})"); // Add additional catch cases for other Stripe exception types as needed. // See all exception types at https://docs.stripe.com/api/errors/handling?lang=php } catch (\Stripe\Exception\ApiErrorException $e) { // All other Stripe API errors error_log("Status: " . $e->getHttpStatus() . ", Code: " . $e->getStripeCode() . ", Message: " . $e->getMessage() . ", Request ID: " . $e->getRequestId()); } catch (Exception $e) { error_log("Another problem occurred, maybe unrelated to Stripe."); } } ``` Dopo aver configurato la gestione delle eccezioni, testala con dati diversi, tra cui le [carte di test](https://docs.stripe.com/testing.md), per simulare diversi esiti di pagamento. #### Errore da attivare - Richiesta non valida #### PHP ```php example_function([ // The required parameter currency is missing 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Questa è una carta di test che dà sempre esito positivo quando usata in ambienti di test. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` An invalid request occurred. ``` #### Errore da attivare - Errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedFraudulent', // Questa è una carta di test che produce sempre un errore di pagamento per addebito fraudolento. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti una modalità di pagamento reale. ]); ``` ``` A payment error occurred: Your card was declined. ``` #### Errore da attivare - Nessun errore #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Questa è una carta di test che dà sempre esito positivo quando usata in ambienti di test. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` No error. ``` ## Monitorare i webhook Stripe utilizza i *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) 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](https://docs.stripe.com/webhooks/quickstart.md): 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](https://docs.stripe.com/api/events/object.md#event_object-data-object) per recuperare l’oggetto interessato. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). 1. Accedi a [event[‘data’][‘object’]](https://docs.stripe.com/api/events/object.md#event_object-data-object) per recuperare l’oggetto interessato. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). 1. Accedi a [event->data->object](https://docs.stripe.com/api/events/object.md#event_object-data-object) per recuperare l’oggetto interessato. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). 1. Ottieni l’oggetto interessato usando un `EventDataObjectDeserializer` e trasmettendone l’esito al tipo appropriato. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). 1. Accedi a [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) per recuperare l’oggetto interessato. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). 1. Ottieni l’oggetto interessato effettuando l’unmarshalling dei dati da `event.Data.Raw`. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). 1. Ottieni l’oggetto interessato trasmettendo [stripeEvent.Data.Object](https://docs.stripe.com/api/events/object.md#event_object-data-object) al tipo appropriato. 1. [Usa le informazioni salvate](https://docs.stripe.com/error-handling.md#use-stored-information) sull’oggetto interessato per capirne il contesto, compreso un oggetto errore. 1. [Usa il suo tipo per scegliere una risposta](https://docs.stripe.com/error-handling.md#error-types). #### PHP ```php >'); $payload = @file_get_contents('php://input'); $event = null; // Get the event object try { $event = \Stripe\Event::constructFrom( json_decode($payload, true) ); } catch(\UnexpectedValueException $e) { echo '⚠️ Webhook error while parsing basic request.'; http_response_code(400); exit(); } // Use the event type to find out what happened if ($event->type == 'payment_intent.payment_failed') { // Get the object affected $paymentIntent = $event->data->object; // Use stored information to get an error object $e = $paymentIntent->last_payment_error; // Use its type to choose a response switch ($e->type) { case \Stripe\Exception\CardException: error_log("A payment error occurred: {$e->getError()->message}"); break; case \Stripe\Exception\InvalidRequestException: error_log("An invalid request occurred."); if (isset($e->getError()->param)) { error_log("The parameter {$e->getError()->param} is invalid or missing."); } break; default: error_log("Another problem occurred, maybe unrelated to Stripe."); } } http_response_code(200); ``` Per testare il modo in cui l’integrazione risponde agli eventi webhook, puoi [attivare eventi webhook in locale](https://docs.stripe.com/webhooks.md#test-webhook). Una volta completata la procedura di configurazione a quel link, attiva un pagamento non riuscito per vedere il messaggio di errore che ne risulta. ```bash stripe trigger payment_intent.payment_failed ``` ```bash 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](https://docs.stripe.com/error-handling.md#error-types). Ad esempio: 1. Recuperare un Payment Intent specifico. 1. Controllare se si è verificato un errore legato al pagamento determinando se il campo [last_payment_error](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error) è vuoto. 1. Se si è verificato, registrare l’errore, compreso il tipo e l’oggetto interessato. #### PHP ```php >'); $payment_intent = $stripe->paymentIntents->retrieve(% identifier type="paymentIntent" /%}); $e = $payment_intent->last_payment_error; if (isset($e)) { error_log("PaymentIntent {$payment_intent->id} experienced a {$e->getError()->type} error."); } ``` Ecco alcuni oggetti comuni che salvano informazioni sugli errori. | Oggetto | Attributo | Valori | | ---------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | | [Payment Intent](https://docs.stripe.com/api/payment_intents.md) | `last_payment_error` | [Un oggetto errore](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Intent](https://docs.stripe.com/api/setup_intents.md) | `last_setup_error` | [Un oggetto errore](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Fattura](https://docs.stripe.com/api/invoices.md) | `last_finalization_error` | [Un oggetto errore](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Attempt](https://docs.stripe.com/api/setup_attempts.md) | `setup_error` | [Un oggetto errore](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Payout](https://docs.stripe.com/api/payouts.md) | `failure_code` | [Un codice di bonifico non riuscito](https://docs.stripe.com/api/payouts/failures.md) | | [Rimborso](https://docs.stripe.com/api/refunds.md) | `failure_reason` | [Un codice di rimborso non riuscito](https://docs.stripe.com/api/refunds/object.md#refund_object-failure_reason) | 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](https://docs.stripe.com/testing.md) o i numeri di conto bancario di test. Ad esempio: - [Simula un pagamento rifiutato](https://docs.stripe.com/testing.md#declined-payments), per creare addebiti, PaymentIntent, SetupIntent, ecc. non andati a buon fine. - [Simula un bonifico non riuscito](https://docs.stripe.com/connect/testing.md#account-numbers). - [Simula un rimborso non riuscito](https://docs.stripe.com/testing.md#refunds). ## 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](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [Stripe::InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido. | | Errore di connessione | [Stripe::APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Si è verificato un problema di rete tra il tuo server e Stripe. | | Errore API | [Stripe::APIError](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di autenticazione | [Stripe::AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe non può autenticarti con le informazioni fornite. | | Errore di idempotenza | [Stripe::IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | | Errore di autorizzazione | [Stripe::PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | Errore di limitazione della velocità | [Stripe::RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hai effettuato troppe chiamate API in troppo poco tempo. | | Errore di verifica di firma | [Stripe::SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e non abbiamo potuto verificare l’autenticità di un evento webhook. | ## Errori legati al pagamento Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo [Stripe::CardError](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Pagamento bloccato per sospetta frode | | | | | **Tipo** | `Stripe::CardError` | | **Codici** | ```ruby charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento rifiutato dalla società emittente | | | | | **Tipo** | `Stripe::CardError` | | **Codici** | `e.error.code == "card_declined"` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `Stripe::CardError` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) 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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) per ulteriori informazioni sul problema. - 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. Cioè, non dare per scontato che sia andato o meno a buon fine. 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 aiutare a risolvere gli errori di connessione, puoi: - Quando crei o aggiorni un oggetto, utilizza una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md). Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza 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](https://docs.stripe.com/error-low-level.md#idempotency). - Attiva la [ripetizione automatica dei tentativi](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di autenticazione | | | | | **Tipo** | `Stripe::AuthenticationError` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ## Errori di idempotenza | | | | | **Tipo** | `Stripe::IdempotencyError` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errori di autorizzazione | | | | | **Tipo** | `Stripe::PermissionError` | | **Problema** | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | **Soluzioni** | - Assicurati di non utilizzare una [chiave API con limitazioni](https://docs.stripe.com/keys-best-practices.md#limit-access) per un servizio a cui questa non può accedere. - Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un [ruolo utente](https://docs.stripe.com/get-started/account/teams/roles.md) non autorizzato. | ## 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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ## Errori di verifica di firma | | | | | **Tipo** | `Stripe::SignatureVerificationError` | | **Problema** | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md#verify-events) in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API. | Nella libreria Python di Stripe, gli oggetti errore appartengono a `stripe.StripeError` e alle relative sottoclassi. Per una corretta gestione, verifica le istruzioni contenute nella documentazione di ogni classe. | Nome | Classe | Descrizione | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Errore legato al pagamento | [stripe.CardError](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [stripe.InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido. | | Errore di connessione | [stripe.APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Si è verificato un problema di rete tra il tuo server e Stripe. | | Errore API | [stripe.APIError](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di autenticazione | [stripe.AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe non può autenticarti con le informazioni fornite. | | Errore di idempotenza | [stripe.IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | | Errore di autorizzazione | [stripe.PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | Errore di limitazione della velocità | [stripe.RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hai effettuato troppe chiamate API in troppo poco tempo. | | Errore di verifica di firma | [stripe.SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e non abbiamo potuto verificare l’autenticità di un evento webhook. | ## Errori legati al pagamento Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo [stripe.CardError](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Pagamento bloccato per sospetta frode | | | | | **Tipo** | `stripe.CardError` | | **Codici** | ```python charge = stripe.Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento rifiutato dalla società emittente | | | | | **Tipo** | `stripe.CardError` | | **Codici** | `e.code == "card_declined"` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `stripe.CardError` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) 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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) per ulteriori informazioni sul problema. - Per comodità, segui il link a `e.doc_url` in cui troverai della documentazione sul codice di errore. - Se l’errore riguarda un parametro specifico, usa `e.param` 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. Cioè, non dare per scontato che sia andato o meno a buon fine. 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 aiutare a risolvere gli errori di connessione, puoi: - Quando crei o aggiorni un oggetto, utilizza una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md). Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza 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](https://docs.stripe.com/error-low-level.md#idempotency). - Attiva la [ripetizione automatica dei tentativi](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di autenticazione | | | | | **Tipo** | `stripe.AuthenticationError` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ## Errori di idempotenza | | | | | **Tipo** | `stripe.IdempotencyError` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errori di autorizzazione | | | | | **Tipo** | `stripe.PermissionError` | | **Problema** | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | **Soluzioni** | - Assicurati di non utilizzare una [chiave API con limitazioni](https://docs.stripe.com/keys-best-practices.md#limit-access) per un servizio a cui questa non può accedere. - Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un [ruolo utente](https://docs.stripe.com/get-started/account/teams/roles.md) non autorizzato. | ## 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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ## Errori di verifica di firma | | | | | **Tipo** | `stripe.SignatureVerificationError` | | **Problema** | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md#verify-events) in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API. | Nella libreria PHP di Stripe, ogni tipo di errore appartiene alla sua classe. Leggi la documentazione relativa a ciascuna classe per sapere come rispondere. | Nome | Classe | Descrizione | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Errore legato al pagamento | [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [Stripe\Exception\InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido. | | Errore di connessione | [Stripe\Exception\ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Si è verificato un problema di rete tra il tuo server e Stripe. | | Errore API | [Stripe\Exception\ApiErrorException](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di autenticazione | [Stripe\Exception\AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe non può autenticarti con le informazioni fornite. | | Errore di idempotenza | [Stripe\Exception\IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | | Errore di autorizzazione | [Stripe\Exception\PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | Errore di limitazione della velocità | [Stripe\Exception\RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hai effettuato troppe chiamate API in troppo poco tempo. | | Errore di verifica di firma | [Stripe\Exception\SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e non abbiamo potuto verificare l’autenticità di un evento webhook. | ## Errori legati al pagamento Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Pagamento bloccato per sospetta frode | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Codici** | ```php $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); $charge->outcome->type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento rifiutato dalla società emittente | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Codici** | `$e->getError()->code == "card_declined"` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) per sapere come rispondere in modo appropriato a ciascun codice. | ## Errori di richiesta non valida | | | | | **Tipo** | `Stripe\Exception\InvalidRequestException` | | **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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) per ulteriori informazioni sul problema. - Per comodità, segui il link a `e->getError()->doc_url` in cui troverai della documentazione sul codice di errore. - Se l’errore riguarda un parametro specifico, usa `e->getError()->param` per stabilire quale. | ## Errori di connessione | | | | | **Tipo** | `Stripe\Exception\ApiConnectionException` | | **Problema** | Si è verificato un problema di rete tra il tuo server e Stripe. | | **Soluzioni** | Tratta il risultato della chiamata API come indeterminato. Cioè, non dare per scontato che sia andato o meno a buon fine. 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 aiutare a risolvere gli errori di connessione, puoi: - Quando crei o aggiorni un oggetto, utilizza una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md). Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza 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](https://docs.stripe.com/error-low-level.md#idempotency). - Attiva la [ripetizione automatica dei tentativi](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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\Exception\APIException` | | **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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di autenticazione | | | | | **Tipo** | `Stripe\Exception\AuthenticationException` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ## Errori di idempotenza | | | | | **Tipo** | `Stripe\Exception\IdempotencyException` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errori di autorizzazione | | | | | **Tipo** | `Stripe\Exception\PermissionException` | | **Problema** | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | **Soluzioni** | - Assicurati di non utilizzare una [chiave API con limitazioni](https://docs.stripe.com/keys-best-practices.md#limit-access) per un servizio a cui questa non può accedere. - Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un [ruolo utente](https://docs.stripe.com/get-started/account/teams/roles.md) non autorizzato. | ## Errori di limitazione della velocità | | | | | **Tipo** | `Stripe\Exception\RateLimitException` | | **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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ## Errori di verifica di firma | | | | | **Tipo** | `Stripe\Exception\SignatureVerificationException` | | **Problema** | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md#verify-events) in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API. | Nella libreria Java di Stripe, ogni tipo di errore appartiene alla sua classe. Leggi la documentazione relativa a ciascuna classe per sapere come rispondere. | Nome | Classe | Descrizione | | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Errore legato al pagamento | [CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido. | | Errore di connessione | [ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Si è verificato un problema di rete tra il tuo server e Stripe. | | Errore API | [APIException](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di autenticazione | [AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe non può autenticarti con le informazioni fornite. | | Errore di idempotenza | [IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | | Errore di autorizzazione | [PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | Errore di limitazione della velocità | [RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hai effettuato troppe chiamate API in troppo poco tempo. | | Errore di verifica di firma | [SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e non abbiamo potuto verificare l’autenticità di un evento webhook. | ## Errori legati al pagamento Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo [CardException](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Pagamento bloccato per sospetta frode | | | | | **Tipo** | `CardException` | | **Codici** | ```java Charge charge = Charge.retrieve(ex.getStripeError() .getPaymentIntent() .getLatestCharge()); charge.getOutcome().getType() == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `ex.getStripeError().getPaymentIntent().getCharges().getData().get(0).getOutcome().getType() == "blocked"` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento rifiutato dalla società emittente | | | | | **Tipo** | `CardException` | | **Codici** | `e.getCode() == "card_declined"` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `CardException` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) per sapere come rispondere in modo appropriato a ciascun codice. | ## Errori di richiesta non valida | | | | | **Tipo** | `InvalidRequestException` | | **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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) per ulteriori informazioni sul problema. - Per comodità, segui il link a `e.getDocUrl()` in cui troverai della documentazione sul codice di errore. - Se l’errore riguarda un parametro specifico, usa `e.getParam()` per stabilire quale. | ## Errori di connessione | | | | | **Tipo** | `APIConnectionException` | | **Problema** | Si è verificato un problema di rete tra il tuo server e Stripe. | | **Soluzioni** | Tratta il risultato della chiamata API come indeterminato. Cioè, non dare per scontato che sia andato o meno a buon fine. 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 aiutare a risolvere gli errori di connessione, puoi: - Quando crei o aggiorni un oggetto, utilizza una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md). Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza 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](https://docs.stripe.com/error-low-level.md#idempotency). - Attiva la [ripetizione automatica dei tentativi](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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** | `APIException` | | **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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di autenticazione | | | | | **Tipo** | `AuthenticationException` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ## Errori di idempotenza | | | | | **Tipo** | `IdempotencyException` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errori di autorizzazione | | | | | **Tipo** | `PermissionException` | | **Problema** | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | **Soluzioni** | - Assicurati di non utilizzare una [chiave API con limitazioni](https://docs.stripe.com/keys-best-practices.md#limit-access) per un servizio a cui questa non può accedere. - Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un [ruolo utente](https://docs.stripe.com/get-started/account/teams/roles.md) non autorizzato. | ## Errori di limitazione della velocità | | | | | **Tipo** | `RateLimitException` | | **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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ## Errori di verifica di firma | | | | | **Tipo** | `SignatureVerificationException` | | **Problema** | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md#verify-events) in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API. | Nella libreria Node.js 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 | [StripeCardError](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [StripeInvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido. | | Errore di connessione | [StripeConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Si è verificato un problema di rete tra il tuo server e Stripe. | | Errore API | [StripeAPIError](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di autenticazione | [StripeAuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe non può autenticarti con le informazioni fornite. | | Errore di idempotenza | [StripeIdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | | Errore di autorizzazione | [StripePermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | Errore di limitazione della velocità | [StripeRateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hai effettuato troppe chiamate API in troppo poco tempo. | | Errore di verifica di firma | [StripeSignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e non abbiamo potuto verificare l’autenticità di un evento webhook. | ## Errori legati al pagamento Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo [StripeCardError](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Pagamento bloccato per sospetta frode | | | | | **Tipo** | `StripeCardError` | | **Codici** | ```javascript const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge) charge.outcome.type === 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `e.payment_intent.charges.data[0].outcome.type === 'blocked'` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento rifiutato dalla società emittente | | | | | **Tipo** | `StripeCardError` | | **Codici** | `e.code === 'card_declined'` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `StripeCardError` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) per sapere come rispondere in modo appropriato a ciascun codice. | ## Errori di richiesta non valida | | | | | **Tipo** | `StripeInvalidRequestError` | | **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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) per ulteriori informazioni sul problema. - Per comodità, segui il link a `e.doc_url` in cui troverai della documentazione sul codice di errore. - Se l’errore riguarda un parametro specifico, usa `e.param` per stabilire quale. | ## Errori di connessione | | | | | **Tipo** | `StripeAPIConnectionError` | | **Problema** | Si è verificato un problema di rete tra il tuo server e Stripe. | | **Soluzioni** | Tratta il risultato della chiamata API come indeterminato. Cioè, non dare per scontato che sia andato o meno a buon fine. 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 aiutare a risolvere gli errori di connessione, puoi: - Quando crei o aggiorni un oggetto, utilizza una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md). Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza 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](https://docs.stripe.com/error-low-level.md#idempotency). - Attiva la [ripetizione automatica dei tentativi](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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** | `StripeAPIError` | | **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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di autenticazione | | | | | **Tipo** | `StripeAuthenticationError` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ## Errori di idempotenza | | | | | **Tipo** | `StripeIdempotencyError` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errori di autorizzazione | | | | | **Tipo** | `StripePermissionError` | | **Problema** | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | **Soluzioni** | - Assicurati di non utilizzare una [chiave API con limitazioni](https://docs.stripe.com/keys-best-practices.md#limit-access) per un servizio a cui questa non può accedere. - Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un [ruolo utente](https://docs.stripe.com/get-started/account/teams/roles.md) non autorizzato. | ## Errori di limitazione della velocità | | | | | **Tipo** | `StripeRateLimitError` | | **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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ## Errori di verifica di firma | | | | | **Tipo** | `StripeSignatureVerificationError` | | **Problema** | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md#verify-events) in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API. | 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](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [stripe.ErrorTypeInvalidRequest](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API in una modalità al momento non valida. Sono inclusi i seguenti casi: - [Errore di limitazione della velocità](https://docs.stripe.com/error-handling.md#rate-limiting) - [Errore di autenticazione](https://docs.stripe.com/error-handling.md#authentication-errors) - [Stato o parametri non validi](https://docs.stripe.com/error-handling.md#invalid-parameters-or-state) | | Errore API | [stripe.ErrorTypeAPI](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di idempotenza | [stripe.ErrorTypeIdempotency](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | ## Errori carte 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](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Blocco per sospetta frode | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Codici** | ```go charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Rifiuto da parte della società emittente | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Codici** | `cardErr.Error.Code == stripe.ErrorCodeCardDeclined` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) 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](https://docs.stripe.com/error-codes.md) per trovare una soluzione. Alcuni codici richiedono una risposta particolare: - `rate_limit` e `lock_timeout` rappresentano [errori di limitazione della velocità](https://docs.stripe.com/error-handling.md#rate-limit-errors) - `secret_key_required` rappresenta un [errore di autenticazione](https://docs.stripe.com/error-handling.md#authentication-errors) - Altri codici di errore rappresentano [uno stato o parametri non validi](https://docs.stripe.com/error-handling.md#other-invalid-request-errors) ### Errori di limitazione della velocità | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Codici** | `stripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout` | | **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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ### Errori di autenticazione | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Codici** | `stripeErr.Code == stripe.ErrorCodeSecretKeyRequired` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ### Stato o parametri non validi | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Codici** | `stripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired` | | **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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) 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` | | **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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di idempotenza | | | | | **Tipo** | `stripe.ErrorTypeIdempotency` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | Nella libreria .NET 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 | [card_error](https://docs.stripe.com/error-handling.md#payment-errors) | Si è verificato un errore durante un pagamento, che riguarda una delle seguenti situazioni: - [Pagamento bloccato per sospetta frode](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined). - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errore di richiesta non valida | [invalid_request_error](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hai effettuato una chiamata API con parametri errati, nello stato errato o in un modo non valido. | | Errore di connessione | [api_connection_error](https://docs.stripe.com/error-handling.md#connection-errors) | Si è verificato un problema di rete tra il tuo server e Stripe. | | Errore API | [api_error](https://docs.stripe.com/error-handling.md#api-errors) | Si è verificato un problema lato Stripe (questi casi sono rari). | | Errore di autenticazione | [authentication_error](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe non può autenticarti con le informazioni fornite. | | Errore di idempotenza | [idempotency_error](https://docs.stripe.com/error-handling.md#idempotency-errors) | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) per qualcosa di imprevisto, come la ripetizione di una richiesta ma specificando parametri diversi. | | Errore di autorizzazione | [permission_error](https://docs.stripe.com/error-handling.md#permission-errors) | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | Errore di limitazione della velocità | [rate_limit_error](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hai effettuato troppe chiamate API in troppo poco tempo. | | Errore di verifica di firma | [signature_verification_error](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e non abbiamo potuto verificare l’autenticità di un evento webhook. | ## Errori legati al pagamento Tutto quanto contenuto in questa sezione si applica anche ai pagamenti senza carta. Per motivi storici, gli errori di pagamento sono del tipo [card_error](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento rifiutato dalla società emittente](https://docs.stripe.com/error-handling.md#payment-declined) - [Altri errori legati al pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Per distinguere queste categorie o per ottenere maggiori informazioni su come rispondere, verifica il [codice di errore](https://docs.stripe.com/error-codes.md), il [codice di rifiuto](https://docs.stripe.com/declines/codes.md) e l’[esito dell’addebito](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Utenti con versione API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o precedente: (Per trovare l’esito dell’addebito a partire da un oggetto errore, individua prima il [Payment Intent coinvolto](https://docs.stripe.com/api/errors.md#errors-payment_intent) e l’[ultimo addebito che ha creato](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Vedi l’esempio che segue per una dimostrazione.) #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulazione di pagamenti rifiutati e altri errori delle carte](https://docs.stripe.com/testing.md#declined-payments) Il codice di test che segue mostra alcune possibilità. #### Errore da attivare - Blocco per sospetta frode #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Questa è una carta di test che viene sempre bloccata per frode sospetta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Errore da attivare - Rifiuto da parte della società emittente #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Questa è una carta di test che viene sempre rifiutata dalla società emittente quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Payment declined by the issuer ``` #### Errore da attivare - Carta scaduta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Questa è una carta di test che dà sempre esito negativo in quanto scaduta quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Card expired. ``` #### Errore da attivare - Altro errore carta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Questa è una carta di test che dà sempre esito negativo a causa di un errore di elaborazione quando usata in una sandbox. Usala insieme ad altre carte di test per verificare come la tua integrazione gestisce gli errori. Nel codice di produzione, qui useresti un metodo di pagamento reale. ]); ``` ``` Other payment error. ``` ### Pagamento bloccato per sospetta frode | | | | | **Tipo** | `card_error` | | **Codici** | ```dotnet var chargeService = new ChargeService(); var options = new ChargeGetOptions(); var charge = chargeService.Get(e.StripeError.PaymentIntent.LatestChargeId, options); charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Codici** | `e.StripeError.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | Il sistema di prevenzione delle frodi di Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la tua integrazione Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) per raccogliere informazioni più dettagliate. - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) per creare moduli con elementi ottimizzati e preintegrati. I clienti che usano *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Per modificare i criteri per bloccare un pagamento, usa le [regole personalizzate](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puoi testare le impostazioni della tua integrazione con le [carte di test che simulano le frodi](https://docs.stripe.com/radar/testing.md). Se utilizzi regole Radar personalizzate, segui i consigli sui test contenuti nella [documentazione di Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento rifiutato dalla società emittente | | | | | **Tipo** | `card_error` | | **Codici** | `e.StripeError.Code == "card_declined"` | | **Problema** | La 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](https://docs.stripe.com/declines/codes.md) per sapere come rispondere in modo appropriato a ciascun codice. Puoi anche: - [Segui le raccomandazioni per ridurre i rifiuti delle società emittenti](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Utilizza [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Altri errori legati al pagamento | | | | | **Tipo** | `card_error` | | **Problema** | 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](https://docs.stripe.com/error-codes.md) per sapere come rispondere in modo appropriato a ciascun codice. | ## Errori di richiesta non valida | | | | | **Tipo** | `invalid_request_error` | | **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. - Consulta la [documentazione sui codici di errore](https://docs.stripe.com/error-codes.md) per ulteriori informazioni sul problema. - 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** | `api_connection_error` | | **Problema** | Si è verificato un problema di rete tra il tuo server e Stripe. | | **Soluzioni** | Tratta il risultato della chiamata API come indeterminato. Cioè, non dare per scontato che sia andato o meno a buon fine. 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 aiutare a risolvere gli errori di connessione, puoi: - Quando crei o aggiorni un oggetto, utilizza una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md). Poi, se si verifica un errore di connessione, puoi ripetere tranquillamente la richiesta senza 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](https://docs.stripe.com/error-low-level.md#idempotency). - Attiva la [ripetizione automatica dei tentativi](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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** | `api_error` | | **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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errori di autenticazione | | | | | **Tipo** | `authentication_error` | | **Problema** | Stripe non può autenticarti con le informazioni fornite. | | **Soluzioni** | - Usa la [chiave API](https://docs.stripe.com/keys.md) corretta. - Assicurati di non usare una chiave che hai [“ruotato” o revocato](https://docs.stripe.com/keys.md#rolling-keys). | ## Errori di idempotenza | | | | | **Tipo** | `idempotency_error` | | **Problema** | Hai usato una [chiave di idempotenza](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errori di autorizzazione | | | | | **Tipo** | `permission_error` | | **Problema** | La chiave API utilizzata per questa richiesta non dispone delle autorizzazioni necessarie. | | **Soluzioni** | - Assicurati di non utilizzare una [chiave API con limitazioni](https://docs.stripe.com/keys-best-practices.md#limit-access) per un servizio a cui questa non può accedere. - Non eseguire azioni nella Dashboard se hai effettuato l’accesso con un [ruolo utente](https://docs.stripe.com/get-started/account/teams/roles.md) non autorizzato. | ## Errori di limitazione della velocità | | | | | **Tipo** | `rate_limit_error` | | **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 ulteriori informazioni, consulta la documentazione sui [limiti di frequenza](https://docs.stripe.com/rate-limits.md). - Se prevedi un forte aumento del traffico e desideri richiedere un limite di frequenza maggiore, [contatta l’assistenza](https://support.stripe.com/) in anticipo. | ## Errori di verifica di firma | | | | | **Tipo** | `signature_verification_error` | | **Problema** | Stai usando la [verifica della firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/webhooks.md#verify-events) in cui troverai ulteriori informazioni. In particolare, assicurati di usare la chiave privata dell’endpoint corretta. Questa chiave è diversa dalla tua chiave API. |