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.
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.
Técnica | Objetivo | Quando necessário |
---|---|---|
Usar valores de erro | Recuperar quando uma chamada de API não consegue continuar | Sempre |
Monitorar webhooks | Reagir a notificações da Stripe | Algumas vezes |
Obter informações armazenadas sobre falhas | Investigar problemas passados e apoiar outras técnicas | Algumas vezes |
Usar valores de erro
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.
, que tem campos que descrevem o problema. Use o campo Type para escolher uma resposta. Em alguns casos, você pode forçar a propriedade Err
a um tipo de erro mais específico com informações adicionais.
Depois de configurar o gerenciamento de exceções, teste-o com diversos dados, incluindo cartões de teste, para simular diversos resultados de pagamentos.
Monitorar webhooks
A Stripe notifica diversos tipos de problema usando webhooks, 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 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: 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:
- Obtenha o objeto afetado realizando um unmarshall dos dados de
event.
.Data. Raw - Use informações armazenadas no objeto afetado para obter contexto, incluindo um objeto de erro.
- Use seu tipo para escolher uma resposta.
Para testar como sua integração responde a eventos de webhook, você pode acionar eventos de webhook localmente. Depois de concluir as etapas de configuração nesse link, acione um pagamento com falha para ver a mensagem de erro resultante.
stripe trigger payment_intent.payment_failed
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.
Por exemplo:
- Recupere uma intenção de pagamento específica.
- Para saber se houve um erro de pagamento na intenção, verifique se last_payment_error está vazio.
- Se ocorreu, registre o erro, incluindo seu tipo e o objeto afetado.
Veja a seguir os objetos comuns que armazenam informações sobre falhas.
Objeto | Atributo | Valores |
---|---|---|
Payment Intent | last_ | Um objeto de erro |
Setup Intent | last_ | Um objeto de erro |
Invoice | last_ | Um objeto de erro |
Setup Attempt | setup_ | Um objeto de erro |
Payout | failure_ | Um código de falha de repasse |
Refund | failure_ | Um código de falha de reembolso |
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 ou números bancários de teste. Por exemplo:
- Simule um pagamento recusado para criar Charges, PaymentIntents, SetupIntents com falha, entre outros.
- Simule um repasse com falha.
- Simule um reembolso com falha.
Tipos de erro e respostas
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 | Ocorreu um erro durante um pagamento que envolve uma destas situações: | |
Erro de solicitação inválida | Você fez uma chamada de API de uma forma inválida no momento. Por exemplo: | |
Erro de API | Ocorreu um erro no lado da Stripe (raramente acontece). | |
Erro de idempotência | Você usou uma chave de idempotência para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. |
Erros de cartão
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:
Para distinguir essas categorias ou obter mais informações sobre como responder, consulte o código de erro, o código de recusa e o resultado da cobrança.
(Para encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o Payment Intent envolvido e a última cobrança criada. Veja uma demonstração no exemplo abaixo.)
Usuários na versão 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 e a última cobrança criada. Veja uma demonstração no exemplo abaixo.)
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
- Simulação de pagamentos recusados e outros erros de cartão
O código de teste abaixo demonstra algumas possibilidades.
Bloqueado por suspeita de fraude
Tipo |
|
Códigos |
|
Códigos |
|
Problema | O sistema de prevenção de fraudes da Stripe, o Radar, 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:
Os clientes do Radar for Fraud Teams têm estas opções adicionais:
Você pode testar as configurações da integração com cartões de teste que simulam fraudes. Se você tiver regras de Radar personalizadas, siga as orientações de teste da documentação de Radar. |
Recusado pelo emissor
Tipo |
|
Códigos |
|
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 para obter as respostas adequadas a cada código. Você também pode:
Teste como sua integração gerencia recusas com cartões de teste que simulam pagamentos bem-sucedidos e recusados. |
Outros erros de pagamento
Tipo |
|
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 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.
) e consulte a documentação do código de erro para encontrar uma solução. Alguns códigos de erro exigem uma resposta especial:
rate_
elimit lock_
indicam erros de limitação de fluxotimeout secret_
indica um erro de autenticaçãokey_ required - Outros códigos de erro indicam estado ou parâmetros inválidos
Erros de limitação de fluxo
Tipo |
|
Códigos | stripeErr. |
Problema | Você fez um número excessivo de chamadas de API em um período curto. |
Soluções |
|
Erros de autenticação
Tipo |
|
Códigos | stripeErr. |
Problema | A Stripe não consegue autenticar você com os dados informados. |
Soluções |
|
Estado ou parâmetros inválidos
Tipo |
|
Códigos | stripeErr. |
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.
|
Erros de API
Tipo |
|
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 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. |
Erros de idempotência
Tipo |
|
Problema | Você usou uma chave de idempotência para algo inesperado, como repetir uma solicitação passando parâmetros diferentes. |
Soluções |
|