# Tratamento de erros Capture e responda a recusas, dados inválidos, problemas de rede e outras ocorrências. A Stripe oferece vários tipos de erro. Eles podem indicar eventos externos, como pagamentos recusados e interrupções de erro, ou problemas de programação, como chamadas de API inválidas. ## Analisar dados de erro Quando a Stripe retorna um erro à sua solicitação de API, você recebe detalhes sobre o erro que ajudam a entender como aplicar as sugestões de tratamento neste guia. Esses detalhes também ajudam a fornecer informações importantes para o suporte da Stripe, se necessário. | Propriedade | Descrição | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | O código de erro. | | `doc_url` | Um link para a documentação da Stripe para o código de erro específico. | | `message` | Uma descrição do motivo do erro. | | `param` | O parâmetro da solicitação que causou o erro. | | `request_log_url` | Um link para o Stripe Dashboard onde você verá logs detalhados sobre a solicitação de origem e o erro. | | ID da solicitação | Um identificador exclusivo para a solicitação de origem com erro. O cabeçalho de resposta a erro inclui esse valor (cadeia de caracteres que começa com `req`), mas você pode especificar uma impressão em sua solicitação, como mostrado nos exemplos de código deste guia. | | `type` | Uma referência à categoria de erro à qual esse erro pertence. | Para gerenciar os erros, use algumas ou todas as técnicas da tabela abaixo. Qualquer que seja a técnica usada, você pode complementá-las com nossas [respostas recomendadas para cada tipo de erro](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Capturar exceções](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Capturar exceções Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em exceções pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). Se um problema imediato evita a continuidade de uma chamada de API, a biblioteca Ruby da Stripe gera uma exceção. Capturar e gerenciar exceções é uma prática recomendada. Para capturar uma exceção, use a palavra-chave `rescue` do Ruby. Capture `Stripe::StripeError` ou suas subclasses para gerenciar apenas exceções específicas da Stripe. Cada subclasse representa um tipo diferente de exceção. Quando captura uma exceção, você pode [usar suas classes para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Capturar exceções](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Capturar exceções Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em exceções pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). Se um problema imediato impedir que uma chamada de API continue, a biblioteca Python da Stripe gera uma exceção. É uma prática recomendada capturar e gerenciar exceções. Para capturar uma exceção, use a sintaxe `try`/`except` do Python. Captura `stripe.StripeError` ou suas subclasses para gerenciar apenas exceções específicas da Stripe. Cada subclasse representa um tipo diferente de exceção. Quando captura uma exceção, você pode [usar sua classe para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Capturar exceções](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Capturar exceções Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em exceções pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). Se um problema imediato impedir que uma chamada de API continue, a biblioteca PHP da Stripe gera uma exceção. É uma prática recomendada capturar e gerenciar exceções. Para capturar uma exceção, use a sintaxe `try`/`catch` do PHP. A Stripe oferece várias classes de exceção que você pode capturar. Cada uma representa um tipo diferente de erro. Quando você captura uma exceção, pode [usar sua classe para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Capturar exceções](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Capturar exceções Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em exceções pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). Se um problema imediato impedir que uma chamada de API continue, a biblioteca Java da Stripe gera uma exceção. É uma prática recomendada capturar e gerenciar exceções. Para capturar uma exceção, use a sintaxe `try`/`catch` do Java. Capture `StripeException` ou suas subclasses para processar somente exceções específicas da Stripe. Cada subclasse representa um tipo diferente de exceção. Quando você captura uma exceção, pode [usar sua classe para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Capturar exceções](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Capturar exceções Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em exceções pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). Se um problema imediato impedir que uma chamada API continue, a biblioteca Node.js da Stripe pode gerar uma exceção. É uma prática recomendada capturar e gerenciar exceções. Para habilitar a geração da exceção e capturá-la, faça o seguinte: - Se a chamada de API é feita em uma função, acrescente a palavra-chave `async` ao início da definição da função. - Acrescente a palavra-chave `await` ao início da própria chamada de API. - Encapsule a chamada de API em um bloco `try`/`catch`. Quando captura uma exceção, você pode [usar o atributo de tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Usar valores de erro](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Usar valores de erro Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em valores de erro pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). As chamadas de API na biblioteca Go da Stripe retornam um valor de resultado e um valor de erro. Use várias atribuições para capturar ambos. Se o valor do erro não for `nil`, isso significa que um problema imediato impediu a chamada da API de continuar. Se o valor do erro estiver relacionado à Stripe, será possível convertê-lo em um objeto `stripe.Error`, que tem campos que descrevem o problema. [Use o campo Type para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). Em alguns casos, você pode forçar a propriedade `Err` a um tipo de erro mais específico com informações adicionais. | Técnica | Objetivo | Quando necessário | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------- | | [Capturar exceções](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar quando uma chamada de API não consegue continuar | Sempre | | [Monitorar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reagir a notificações da Stripe | Algumas vezes | | [Obter informações armazenadas sobre falhas](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas passados e apoiar outras técnicas | Algumas vezes | ## Capturar exceções Com esta biblioteca, você não precisa verificar as respostas HTTP diferentes de 200. Elas são convertidas em exceções pela biblioteca. No caso raro de necessidade de detalhes do HTTP, consulte o [gerenciamento de exceções de baixo nível](https://docs.stripe.com/error-low-level.md) e o objeto [Error](https://docs.stripe.com/api/errors.md). Se um problema imediato impedir que uma chamada de API continue, a biblioteca .NET da Stripe gera uma exceção. É uma prática recomendada capturar e gerenciar exceções. Para capturar uma exceção, use a sintaxe `try`/`catch` do .NET. Capture uma `StripeException` e [use seu atributo Type para escolher uma resposta](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."); } } ``` Depois de configurar o gerenciamento de exceções, teste-o com diversos dados, incluindo [cartões de teste](https://docs.stripe.com/testing.md), para simular diversos resultados de pagamentos. #### Erro a ser acionado - Solicitação inválida #### PHP ```php example_function([ // The required parameter currency is missing 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Este cartão de teste sempre é bem-sucedido quando usado nos ambientes de teste. Use este e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` An invalid request occurred. ``` #### Erro a ser acionado - Erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedFraudulent', // Este cartão de teste sempre gera um erro de pagamento de fraude de cobrança. Use este e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` A payment error occurred: Your card was declined. ``` #### Erro a ser acionado - Sem erro #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Este cartão de teste sempre é bem-sucedido quando usado nos ambientes de teste. Use este e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` No error. ``` ## Monitorar webhooks A Stripe notifica diversos tipos de problema usando *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests), inclusive problemas que não ocorrem imediatamente após uma chamada de API. Por exemplo: - Você perde uma contestação. - Um pagamento recorrente falha após vários pagamentos mensais bem-sucedidos. - O front-end *confirma* (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) um pagamento, mas fica offline antes de saber que o pagamento falhou (o back-end recebe a notificação do webhook, embora não tenha feito a chamada de API). Você não precisa gerenciar todos os tipos de evento de webhook. Na verdade, algumas integrações não gerenciam nenhum deles. No gerenciador de webhooks, comece com as etapas básicas do [criador de webhooks](https://docs.stripe.com/webhooks/quickstart.md): obtenha um objeto de evento e use o tipo do evento para descobrir o que ocorreu. Se o tipo de evento indicar um erro, siga estas etapas adicionais: 1. Acesse [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar o objeto afetado. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). 1. Acesse [event[‘data’][‘object’]](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar o objeto afetado. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). 1. Acesse [event->data->object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar o objeto afetado. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtenha o objeto afetado usando um `EventDataObjectDeserializer` e convertendo a saída no tipo adequado. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). 1. Acesse [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar o objeto afetado. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtenha o objeto afetado realizando um unmarshall dos dados de `event.Data.Raw`. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtenha o objeto afetado convertendo [stripeEvent.Data.Object](https://docs.stripe.com/api/events/object.md#event_object-data-object) no tipo adequado. 1. [Use informações armazenadas](https://docs.stripe.com/error-handling.md#use-stored-information) no objeto afetado para obter contexto, incluindo um objeto de erro. 1. [Use seu tipo para escolher uma resposta](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); ``` Para testar como sua integração responde a eventos de webhook, você pode [acionar eventos de webhook localmente](https://docs.stripe.com/webhooks.md#test-webhook). Depois de concluir as etapas de configuração nesse link, acione um pagamento com falha para ver a mensagem de erro resultante. ```bash stripe trigger payment_intent.payment_failed ``` ```bash A payment error occurred: Your card was declined. ``` ## Obter informações armazenadas sobre falhas Muitos objetos armazenam informações sobre falhas. Isso significa que, se algo já deu errado, você pode recuperar o objeto e examiná-lo para saber mais. Em muitos casos, as informações armazenadas estão na forma de um objeto de erro e você pode [usar seu tipo para escolher uma resposta](https://docs.stripe.com/error-handling.md#error-types). Por exemplo: 1. Recupere uma intenção de pagamento específica. 1. Para saber se houve um erro de pagamento na intenção, verifique se [last_payment_error](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error) está vazio. 1. Se ocorreu, registre o erro, incluindo seu tipo e o objeto afetado. #### 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."); } ``` Veja a seguir os objetos comuns que armazenam informações sobre falhas. | Objeto | Atributo | Valores | | ---------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | [Payment Intent](https://docs.stripe.com/api/payment_intents.md) | `last_payment_error` | [Um objeto de erro](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Intent](https://docs.stripe.com/api/setup_intents.md) | `last_setup_error` | [Um objeto de erro](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Invoice](https://docs.stripe.com/api/invoices.md) | `last_finalization_error` | [Um objeto de erro](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Attempt](https://docs.stripe.com/api/setup_attempts.md) | `setup_error` | [Um objeto de erro](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Payout](https://docs.stripe.com/api/payouts.md) | `failure_code` | [Um código de falha de repasse](https://docs.stripe.com/api/payouts/failures.md) | | [Refund](https://docs.stripe.com/api/refunds.md) | `failure_reason` | [Um código de falha de reembolso](https://docs.stripe.com/api/refunds/object.md#refund_object-failure_reason) | Muitas vezes, para testar uma programação que usa dados armazenados sobre falhas, você precisa simular falhas em transações. Normalmente, isso pode ser feito usando [cartões de teste](https://docs.stripe.com/testing.md) ou números bancários de teste. Por exemplo: - [Simule um pagamento recusado](https://docs.stripe.com/testing.md#declined-payments) para criar Charges, PaymentIntents, SetupIntents com falha, entre outros. - [Simule um repasse com falha](https://docs.stripe.com/connect/testing.md#account-numbers). - [Simule um reembolso com falha](https://docs.stripe.com/testing.md#refunds). ## Tipos de erro e respostas Na biblioteca Ruby da Stripe, os objetos de erro pertencem a `stripe.error.StripeError` e suas subclasses. Use a documentação de cada classe para saber como responder. | Nome | Classe | Descrição | | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [Stripe::CardError](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [Stripe::InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | Erro de conexão | [Stripe::APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | Erro de API | [Stripe::APIError](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de autenticação | [Stripe::AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | A Stripe não consegue autenticar você com os dados informados. | | Erro de idempotência | [Stripe::IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | Erro de permissão | [Stripe::PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | A chave de API usada para esta solicitação não tem as permissões necessárias. | | Erro de limitação de fluxo | [Stripe::RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Você fez um número excessivo de chamadas de API em um período curto demais. | | Erro de verificação de assinatura | [Stripe::SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | ## Erros de pagamento Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [Stripe::CardError](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Pagamento bloqueado por suspeita de fraude | | | | | **Tipo** | `Stripe::CardError` | | **Códigos** | ```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: | **Códigos** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento recusado pelo emissor | | | | | **Tipo** | `Stripe::CardError` | | **Códigos** | `e.error.code == "card_declined"` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `Stripe::CardError` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida | | | | | **Tipo** | `Stripe::InvalidRequestError` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use para determinar qual deles. | ## Erros de conexão | | | | | **Tipo** | `Stripe::APIConnectionError` | | **Problema** | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | **Soluções** | Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou. Para descobrir se deu certo: - Recupere o objeto relevante da Stripe e verifique seu status. - Ouça a notificação de webhook sobre o sucesso ou falha da operação. Para recuperar-se de erros de conexão, você pode tentar: - Ao criar ou atualizar um objeto, use uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md). Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte [Tratamento de erros em nível inferior](https://docs.stripe.com/error-low-level.md#idempotency). - Ative [novas tentativas automáticas](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Em seguida, a Stripe gera chaves de idempotência para você e repete as solicitações para você quando for seguro. Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original. | ## Erros de API | | | | | **Tipo** | `Stripe::APIError` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de autenticação | | | | | **Tipo** | `Stripe::AuthenticationError` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ## Erros de idempotência | | | | | **Tipo** | `Stripe::IdempotencyError` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | ## Erros de permissão | | | | | **Tipo** | `Stripe::PermissionError` | | **Problema** | A chave de API usada para esta solicitação não tem as permissões necessárias. | | **Soluções** | - Verifique se você não está usando uma [chave de API restrita](https://docs.stripe.com/keys-best-practices.md#limit-access) para um serviço ao qual ela não tem acesso. - Não execute ações no Dashboard enquanto estiver conectado como uma [função de usuário](https://docs.stripe.com/get-started/account/teams/roles.md) que não tenha permissão. | ## Erros de limitação de fluxo | | | | | **Tipo** | `Stripe::RateLimitError` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ## Erros de verificação de assinatura | | | | | **Tipo** | `Stripe::SignatureVerificationError` | | **Problema** | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status `400 Bad Request`. Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre [verificação de assinaturas de webhooks](https://docs.stripe.com/webhooks.md#verify-events) para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API. | Na biblioteca Python da Stripe, os objetos de erro pertencem a `stripe.StripeError` e suas subclasses. Use a documentação de cada classe para obter orientações sobre como responder. | Nome | Classe | Descrição | | --------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [stripe.CardError](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [stripe.InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | Erro de conexão | [stripe.APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | Erro de API | [stripe.APIError](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de autenticação | [stripe.AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | A Stripe não consegue autenticar você com os dados informados. | | Erro de idempotência | [stripe.IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | Erro de permissão | [stripe.PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | A chave de API usada para esta solicitação não tem as permissões necessárias. | | Erro de limitação de fluxo | [stripe.RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Você fez um número excessivo de chamadas de API em um período curto demais. | | Erro de verificação de assinatura | [stripe.SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | ## Erros de pagamento Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [stripe.CardError](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Pagamento bloqueado por suspeita de fraude | | | | | **Tipo** | `stripe.CardError` | | **Códigos** | ```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: | **Códigos** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento recusado pelo emissor | | | | | **Tipo** | `stripe.CardError` | | **Códigos** | `e.code == "card_declined"` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `stripe.CardError` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida | | | | | **Tipo** | `stripe.InvalidRequestError` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em `e.doc_url` para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use `e.param` para determinar qual deles. | ## Erros de conexão | | | | | **Tipo** | `stripe.APIConnectionError` | | **Problema** | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | **Soluções** | Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou. Para descobrir se deu certo: - Recupere o objeto relevante da Stripe e verifique seu status. - Ouça a notificação de webhook sobre o sucesso ou falha da operação. Para recuperar-se de erros de conexão, você pode tentar: - Ao criar ou atualizar um objeto, use uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md). Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte [Tratamento de erros em nível inferior](https://docs.stripe.com/error-low-level.md#idempotency). - Ative [novas tentativas automáticas](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Em seguida, a Stripe gera chaves de idempotência para você e repete as solicitações para você quando for seguro. Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original. | ## Erros de API | | | | | **Tipo** | `stripe.APIError` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de autenticação | | | | | **Tipo** | `stripe.AuthenticationError` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ## Erros de idempotência | | | | | **Tipo** | `stripe.IdempotencyError` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | ## Erros de permissão | | | | | **Tipo** | `stripe.PermissionError` | | **Problema** | A chave de API usada para esta solicitação não tem as permissões necessárias. | | **Soluções** | - Verifique se você não está usando uma [chave de API restrita](https://docs.stripe.com/keys-best-practices.md#limit-access) para um serviço ao qual ela não tem acesso. - Não execute ações no Dashboard enquanto estiver conectado como uma [função de usuário](https://docs.stripe.com/get-started/account/teams/roles.md) que não tenha permissão. | ## Erros de limitação de fluxo | | | | | **Tipo** | `stripe.RateLimitError` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ## Erros de verificação de assinatura | | | | | **Tipo** | `stripe.SignatureVerificationError` | | **Problema** | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status `400 Bad Request`. Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre [verificação de assinaturas de webhooks](https://docs.stripe.com/webhooks.md#verify-events) para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API. | Na biblioteca PHP da Stripe, cada tipo de erro pertence à própria classe. Use a documentação de cada classe para obter orientações sobre como responder. | Nome | Classe | Descrição | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [Stripe\Exception\InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | Erro de conexão | [Stripe\Exception\ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | Erro de API | [Stripe\Exception\ApiErrorException](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de autenticação | [Stripe\Exception\AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | A Stripe não consegue autenticar você com os dados informados. | | Erro de idempotência | [Stripe\Exception\IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | Erro de permissão | [Stripe\Exception\PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | A chave de API usada para esta solicitação não tem as permissões necessárias. | | Erro de limitação de fluxo | [Stripe\Exception\RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Você fez um número excessivo de chamadas de API em um período curto demais. | | Erro de verificação de assinatura | [Stripe\Exception\SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | ## Erros de pagamento Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Pagamento bloqueado por suspeita de fraude | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Códigos** | ```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: | **Códigos** | `$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento recusado pelo emissor | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Códigos** | `$e->getError()->code == "card_declined"` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida | | | | | **Tipo** | `Stripe\Exception\InvalidRequestException` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em `e->getError()->doc_url` para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use `e->getError()->param` para determinar qual deles. | ## Erros de conexão | | | | | **Tipo** | `Stripe\Exception\ApiConnectionException` | | **Problema** | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | **Soluções** | Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou. Para descobrir se deu certo: - Recupere o objeto relevante da Stripe e verifique seu status. - Ouça a notificação de webhook sobre o sucesso ou falha da operação. Para recuperar-se de erros de conexão, você pode tentar: - Ao criar ou atualizar um objeto, use uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md). Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte [Tratamento de erros em nível inferior](https://docs.stripe.com/error-low-level.md#idempotency). - Ative [novas tentativas automáticas](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Em seguida, a Stripe gera chaves de idempotência para você e repete as solicitações para você quando for seguro. Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original. | ## Erros de API | | | | | **Tipo** | `Stripe\Exception\APIException` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de autenticação | | | | | **Tipo** | `Stripe\Exception\AuthenticationException` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ## Erros de idempotência | | | | | **Tipo** | `Stripe\Exception\IdempotencyException` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | ## Erros de permissão | | | | | **Tipo** | `Stripe\Exception\PermissionException` | | **Problema** | A chave de API usada para esta solicitação não tem as permissões necessárias. | | **Soluções** | - Verifique se você não está usando uma [chave de API restrita](https://docs.stripe.com/keys-best-practices.md#limit-access) para um serviço ao qual ela não tem acesso. - Não execute ações no Dashboard enquanto estiver conectado como uma [função de usuário](https://docs.stripe.com/get-started/account/teams/roles.md) que não tenha permissão. | ## Erros de limitação de fluxo | | | | | **Tipo** | `Stripe\Exception\RateLimitException` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ## Erros de verificação de assinatura | | | | | **Tipo** | `Stripe\Exception\SignatureVerificationException` | | **Problema** | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status `400 Bad Request`. Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre [verificação de assinaturas de webhooks](https://docs.stripe.com/webhooks.md#verify-events) para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API. | Na biblioteca Java da Stripe, cada tipo de erro pertence à própria classe. Use a documentação de cada classe para obter orientações sobre como responder. | Nome | Classe | Descrição | | --------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | Erro de conexão | [ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | Erro de API | [APIException](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de autenticação | [AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | A Stripe não consegue autenticar você com os dados informados. | | Erro de idempotência | [IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | Erro de permissão | [PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | A chave de API usada para esta solicitação não tem as permissões necessárias. | | Erro de limitação de fluxo | [RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Você fez um número excessivo de chamadas de API em um período curto demais. | | Erro de verificação de assinatura | [SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | ## Erros de pagamento Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [CardException](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Pagamento bloqueado por suspeita de fraude | | | | | **Tipo** | `CardException` | | **Códigos** | ```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: | **Códigos** | `ex.getStripeError().getPaymentIntent().getCharges().getData().get(0).getOutcome().getType() == "blocked"` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento recusado pelo emissor | | | | | **Tipo** | `CardException` | | **Códigos** | `e.getCode() == "card_declined"` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `CardException` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida | | | | | **Tipo** | `InvalidRequestException` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em `e.getDocUrl()` para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use `e.getParam()` para determinar qual deles. | ## Erros de conexão | | | | | **Tipo** | `APIConnectionException` | | **Problema** | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | **Soluções** | Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou. Para descobrir se deu certo: - Recupere o objeto relevante da Stripe e verifique seu status. - Ouça a notificação de webhook sobre o sucesso ou falha da operação. Para recuperar-se de erros de conexão, você pode tentar: - Ao criar ou atualizar um objeto, use uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md). Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte [Tratamento de erros em nível inferior](https://docs.stripe.com/error-low-level.md#idempotency). - Ative [novas tentativas automáticas](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Em seguida, a Stripe gera chaves de idempotência para você e repete as solicitações para você quando for seguro. Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original. | ## Erros de API | | | | | **Tipo** | `APIException` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de autenticação | | | | | **Tipo** | `AuthenticationException` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ## Erros de idempotência | | | | | **Tipo** | `IdempotencyException` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | ## Erros de permissão | | | | | **Tipo** | `PermissionException` | | **Problema** | A chave de API usada para esta solicitação não tem as permissões necessárias. | | **Soluções** | - Verifique se você não está usando uma [chave de API restrita](https://docs.stripe.com/keys-best-practices.md#limit-access) para um serviço ao qual ela não tem acesso. - Não execute ações no Dashboard enquanto estiver conectado como uma [função de usuário](https://docs.stripe.com/get-started/account/teams/roles.md) que não tenha permissão. | ## Erros de limitação de fluxo | | | | | **Tipo** | `RateLimitException` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ## Erros de verificação de assinatura | | | | | **Tipo** | `SignatureVerificationException` | | **Problema** | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status `400 Bad Request`. Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre [verificação de assinaturas de webhooks](https://docs.stripe.com/webhooks.md#verify-events) para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API. | Na biblioteca Node.js da Stripe, cada objeto de erro tem um atributo `type`. Use a documentação de cada tipo para obter orientações sobre como responder. | Nome | Tipo | Descrição | | --------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [StripeCardError](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [StripeInvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | Erro de conexão | [StripeConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | Erro de API | [StripeAPIError](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de autenticação | [StripeAuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | A Stripe não consegue autenticar você com os dados informados. | | Erro de idempotência | [StripeIdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | Erro de permissão | [StripePermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | A chave de API usada para esta solicitação não tem as permissões necessárias. | | Erro de limitação de fluxo | [StripeRateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Você fez um número excessivo de chamadas de API em um período curto demais. | | Erro de verificação de assinatura | [StripeSignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | ## Erros de pagamento Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [StripeCardError](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Pagamento bloqueado por suspeita de fraude | | | | | **Tipo** | `StripeCardError` | | **Códigos** | ```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: | **Códigos** | `e.payment_intent.charges.data[0].outcome.type === 'blocked'` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento recusado pelo emissor | | | | | **Tipo** | `StripeCardError` | | **Códigos** | `e.code === 'card_declined'` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `StripeCardError` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida | | | | | **Tipo** | `StripeInvalidRequestError` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em `e.doc_url` para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use `e.param` para determinar qual deles. | ## Erros de conexão | | | | | **Tipo** | `StripeAPIConnectionError` | | **Problema** | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | **Soluções** | Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou. Para descobrir se deu certo: - Recupere o objeto relevante da Stripe e verifique seu status. - Ouça a notificação de webhook sobre o sucesso ou falha da operação. Para recuperar-se de erros de conexão, você pode tentar: - Ao criar ou atualizar um objeto, use uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md). Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte [Tratamento de erros em nível inferior](https://docs.stripe.com/error-low-level.md#idempotency). - Ative [novas tentativas automáticas](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Em seguida, a Stripe gera chaves de idempotência para você e repete as solicitações para você quando for seguro. Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original. | ## Erros de API | | | | | **Tipo** | `StripeAPIError` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de autenticação | | | | | **Tipo** | `StripeAuthenticationError` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ## Erros de idempotência | | | | | **Tipo** | `StripeIdempotencyError` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | ## Erros de permissão | | | | | **Tipo** | `StripePermissionError` | | **Problema** | A chave de API usada para esta solicitação não tem as permissões necessárias. | | **Soluções** | - Verifique se você não está usando uma [chave de API restrita](https://docs.stripe.com/keys-best-practices.md#limit-access) para um serviço ao qual ela não tem acesso. - Não execute ações no Dashboard enquanto estiver conectado como uma [função de usuário](https://docs.stripe.com/get-started/account/teams/roles.md) que não tenha permissão. | ## Erros de limitação de fluxo | | | | | **Tipo** | `StripeRateLimitError` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ## Erros de verificação de assinatura | | | | | **Tipo** | `StripeSignatureVerificationError` | | **Problema** | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status `400 Bad Request`. Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre [verificação de assinaturas de webhooks](https://docs.stripe.com/webhooks.md#verify-events) para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API. | Na biblioteca Go da Stripe, cada objeto de erro tem um atributo `Type`. Use a documentação de cada tipo para obter orientações sobre como responder. | Nome | Tipo | Descrição | | ---------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [stripe.ErrorTypeCard](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [stripe.ErrorTypeInvalidRequest](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API de uma forma inválida no momento. Por exemplo: - [Erro de limitação de fluxo](https://docs.stripe.com/error-handling.md#rate-limiting) - [Erro de autenticação](https://docs.stripe.com/error-handling.md#authentication-errors) - [Parâmetros ou estado inválidos](https://docs.stripe.com/error-handling.md#invalid-parameters-or-state) | | Erro de API | [stripe.ErrorTypeAPI](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de idempotência | [stripe.ErrorTypeIdempotency](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | ## Erros de cartão Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [stripe.ErrorTypeCard](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Bloqueado por suspeita de fraude | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Códigos** | ```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: | **Códigos** | `stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Recusado pelo emissor | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Códigos** | `cardErr.Error.Code == stripe.ErrorCodeCardDeclined` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida Os erros de solicitação inválida abrangem diferentes situações. A mais comum é quando a solicitação de API tem parâmetros inválidos ou não é permitida no estado atual da sua integração. Use o código de erro (`stripeErr.Code`) e consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para encontrar uma solução. Alguns códigos de erro exigem uma resposta especial: - `rate_limit` e `lock_timeout` indicam [erros de limitação de fluxo](https://docs.stripe.com/error-handling.md#rate-limit-errors) - `secret_key_required` indica um [erro de autenticação](https://docs.stripe.com/error-handling.md#authentication-errors) - Outros códigos de erro indicam [estado ou parâmetros inválidos](https://docs.stripe.com/error-handling.md#other-invalid-request-errors) ### Erros de limitação de fluxo | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ### Erros de autenticação | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code == stripe.ErrorCodeSecretKeyRequired` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ### Estado ou parâmetros inválidos | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em `stripeErr.DocURL` para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use `stripeErr.Param` para determinar qual deles. | ## Erros de API | | | | | **Tipo** | `stripe.ErrorTypeAPI` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de idempotência | | | | | **Tipo** | `stripe.ErrorTypeIdempotency` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | Na biblioteca .NET da Stripe, cada objeto de erro tem um atributo `type`. Use a documentação de cada tipo para obter orientações sobre como responder. | Nome | Tipo | Descrição | | --------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Erro de pagamento | [card_error](https://docs.stripe.com/error-handling.md#payment-errors) | Ocorreu um erro durante um pagamento que envolve uma destas situações: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) | | Erro de solicitação inválida | [invalid_request_error](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | Erro de conexão | [api_connection_error](https://docs.stripe.com/error-handling.md#connection-errors) | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | Erro de API | [api_error](https://docs.stripe.com/error-handling.md#api-errors) | Ocorreu um erro no lado da Stripe (raramente acontece). | | Erro de autenticação | [authentication_error](https://docs.stripe.com/error-handling.md#authentication-errors) | A Stripe não consegue autenticar você com os dados informados. | | Erro de idempotência | [idempotency_error](https://docs.stripe.com/error-handling.md#idempotency-errors) | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | Erro de permissão | [permission_error](https://docs.stripe.com/error-handling.md#permission-errors) | A chave de API usada para esta solicitação não tem as permissões necessárias. | | Erro de limitação de fluxo | [rate_limit_error](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Você fez um número excessivo de chamadas de API em um período curto demais. | | Erro de verificação de assinatura | [signature_verification_error](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | ## Erros de pagamento Tudo nesta seção também se aplica a pagamentos sem cartão. Por motivos históricos, o tipo dos erros de pagamento é [card_error](https://docs.stripe.com/error-handling.md#card-error). Mas, na verdade, eles podem representar um problema com qualquer pagamento, independentemente da forma de pagamento. Os erros de pagamento (chamados às vezes de “erros de cartão” por motivos históricos) abrangem uma grande variedade de problemas comuns. Eles pertencem a três categorias: - [Pagamento bloqueado por suspeita de fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pagamento recusado pelo emissor](https://docs.stripe.com/error-handling.md#payment-declined) - [Outros erros de pagamento](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o [código de erro](https://docs.stripe.com/error-codes.md), o [código de recusa](https://docs.stripe.com/declines/codes.md) e o [resultado da cobrança](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Usuários na versão [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) da API ou mais antiga: (Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o [Payment Intent envolvido](https://docs.stripe.com/api/errors.md#errors-payment_intent) e a [última cobrança criada](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Veja uma demonstração no exemplo abaixo.) #### 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.'); } } } ``` Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções: - [Simulação de pagamentos bloqueados por risco de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulação de pagamentos recusados e outros erros de cartão](https://docs.stripe.com/testing.md#declined-payments) O código de teste abaixo demonstra algumas possibilidades. #### Erro a ser acionado - Bloqueado por suspeita de fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esse cartão de teste é sempre bloqueado por suspeita de fraude quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Erro a ser acionado - Recusado pelo emissor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esse cartão de teste é sempre recusado pelo emissor quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Payment declined by the issuer ``` #### Erro a ser acionado - Cartão vencido #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esse cartão de teste sempre falha por estar vencido quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Card expired. ``` #### Erro a ser acionado - Outro erro de cartão #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esse cartão de teste sempre falha por erro de processamento quando usado em uma área restrita. Use esse e outros cartões de teste para testar o gerenciamento de erros na integração. No ambiente de produção, você usaria uma forma de pagamento real. ]); ``` ``` Other payment error. ``` ### Pagamento bloqueado por suspeita de fraude | | | | | **Tipo** | `card_error` | | **Códigos** | ```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: | **Códigos** | `e.StripeError.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | O sistema de prevenção de fraudes da Stripe, o *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), bloqueou o pagamento | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Capture o erro e solicite outra forma de pagamento do cliente. Para bloquear menos pagamentos legítimos, experimente: - [Otimize sua integração com o Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recolher informações mais detalhadas. - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados e otimizados. Os clientes do *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) têm estas opções adicionais: - Para isentar um pagamento específico, adicione-o à lista de permissões. (Radar for Fraud Teams) - Para alterar a tolerância ao risco, ajuste as [configurações de risco](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para alterar os critérios de bloqueio de um pagamento, use [regras personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Você pode testar as configurações da integração com [cartões de teste que simulam fraudes](https://docs.stripe.com/radar/testing.md). Se você tiver regras de Radar personalizadas, siga as orientações de teste da [documentação de Radar](https://docs.stripe.com/radar/testing.md). | ### Pagamento recusado pelo emissor | | | | | **Tipo** | `card_error` | | **Códigos** | `e.StripeError.Code == "card_declined"` | | **Problema** | O emissor do cartão recusou o pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Ela reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a [documentação sobre códigos de recusa](https://docs.stripe.com/declines/codes.md) para obter as respostas adequadas a cada código. Você também pode: - [Siga as recomendações para reduzir recusas do emissor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Use [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formulário pré-integrados que implementam essas recomendações. Teste como sua integração gerencia recusas com [cartões de teste que simulam pagamentos bem-sucedidos e recusados](https://docs.stripe.com/radar/testing.md). | ### Outros erros de pagamento | | | | | **Tipo** | `card_error` | | **Problema** | Ocorreu outro erro de pagamento. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de erro para determinar quais são as próximas etapas apropriadas. Consulte a [documentação sobre códigos de erro](https://docs.stripe.com/error-codes.md) para obter as respostas adequadas para cada código. | ## Erros de solicitação inválida | | | | | **Tipo** | `invalid_request_error` | | **Problema** | Você fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida. | | **Soluções** | Na maioria dos casos, o problema é da própria solicitação. Os parâmetros são inválidos ou não podem ser executados no estado atual da integração. - Consulte a [documentação do código de erro](https://docs.stripe.com/error-codes.md) para obter detalhes sobre o problema. - Para sua conveniência, acesse o link em para ver a documentação sobre o código de erro. - Se o erro envolver um parâmetro específico, use para determinar qual deles. | ## Erros de conexão | | | | | **Tipo** | `api_connection_error` | | **Problema** | Ocorreu um problema de rede entre o seu servidor e a Stripe. | | **Soluções** | Trate o resultado da chamada da API como indeterminado. Ou seja, não assuma que deu certo ou que falhou. Para descobrir se deu certo: - Recupere o objeto relevante da Stripe e verifique seu status. - Ouça a notificação de webhook sobre o sucesso ou falha da operação. Para recuperar-se de erros de conexão, você pode tentar: - Ao criar ou atualizar um objeto, use uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md). Em seguida, se ocorrer um erro de conexão, você poderá repetir a solicitação com segurança sem risco de criar um segundo objeto ou executar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para obter orientações avançadas sobre essa estratégia, consulte [Tratamento de erros em nível inferior](https://docs.stripe.com/error-low-level.md#idempotency). - Ative [novas tentativas automáticas](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Em seguida, a Stripe gera chaves de idempotência para você e repete as solicitações para você quando for seguro. Esse erro pode mascarar outros. Pode ser que outro erro se torne aparente quando o erro de conexão for resolvido. Verifique a ocorrência de erros em todas essas soluções da mesma forma que faria na solicitação original. | ## Erros de API | | | | | **Tipo** | `api_error` | | **Problema** | Ocorreu um erro no lado da Stripe (raramente acontece). | | **Soluções** | Trate o resultado da chamada de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido. Use *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obter informações sobre o resultado. Sempre que possível, a Stripe aciona webhooks para todos os objetos que criamos durante a solução de um problema. Para configurar a integração com o máximo de robustez em situações incomuns, consulte [discussão avançada sobre erros de servido.](https://docs.stripe.com/error-low-level.md#server-errors) | ## Erros de autenticação | | | | | **Tipo** | `authentication_error` | | **Problema** | A Stripe não consegue autenticar você com os dados informados. | | **Soluções** | - Use a [chave de API](https://docs.stripe.com/keys.md) correta. - Verifique se não está usando uma chave [“alternada” ou revogada](https://docs.stripe.com/keys.md#rolling-keys). | ## Erros de idempotência | | | | | **Tipo** | `idempotency_error` | | **Problema** | Você usou uma [chave de idempotência](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. | | **Soluções** | - Depois de usar uma chave de idempotência, reutilize-a apenas em chamadas de API idênticas. - Use chaves de idempotência respeitando o limite de 255 caracteres. | ## Erros de permissão | | | | | **Tipo** | `permission_error` | | **Problema** | A chave de API usada para esta solicitação não tem as permissões necessárias. | | **Soluções** | - Verifique se você não está usando uma [chave de API restrita](https://docs.stripe.com/keys-best-practices.md#limit-access) para um serviço ao qual ela não tem acesso. - Não execute ações no Dashboard enquanto estiver conectado como uma [função de usuário](https://docs.stripe.com/get-started/account/teams/roles.md) que não tenha permissão. | ## Erros de limitação de fluxo | | | | | **Tipo** | `rate_limit_error` | | **Problema** | Você fez um número excessivo de chamadas de API em um período curto. | | **Soluções** | - Se uma única chamada de API acionar esse erro, aguarde e tente novamente. - Para gerenciar automaticamente a limitação de taxa, repita a chamada da API após um intervalo e aumente exponencialmente esse atraso se o erro continuar. Consulte a documentação sobre [limitações de taxa](https://docs.stripe.com/rate-limits.md) para obter mais orientações. - Se você espera um grande aumento de tráfego e quer solicitar uma limitação de fluxo maior, [fale antecipadamente com o suporte](https://support.stripe.com/). | ## Erros de verificação de assinatura | | | | | **Tipo** | `signature_verification_error` | | **Problema** | Você está usando [verificação de assinatura](https://docs.stripe.com/webhooks.md#verify-events) de *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) e não conseguiu verificar a autenticidade de um evento de webhook. | | **Soluções** | Este erro pode ocorrer quando a integração está funcionando corretamente. Se você usa verificação de assinatura de webhooks e um terceiro tenta enviar um webhook falso ou mal-intencionado, a verificação falha e gera este erro. Capture o erro e responda com um código de status `400 Bad Request`. Se este erro ocorrer de forma inesperada (por exemplo, com webhooks que você sabe que são originados com Stripe), consulte a documentação sobre [verificação de assinaturas de webhooks](https://docs.stripe.com/webhooks.md#verify-events) para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Isso é diferente da sua chave da API. |