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 | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
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:
To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Users on API version 2022-08-01 or older:
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Você pode acionar alguns tipos comuns de erro de pagamento com cartões de teste. Consulte estas listas para ver as opções:
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:
You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation. |
Recusado pelo emissor
Tipo |
|
Códigos |
|
Problema | O emissor do cartão recusou o pagamento. |
Soluções | This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action may be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code. Você também pode:
Test how your integration handles declines with test cards that simulate successful and declined payments. |
Outros erros de pagamento
Tipo |
|
Problema | Ocorreu outro erro de pagamento. |
Soluções | This error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code. |
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. To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors. |
Erros de idempotência
Tipo |
|
Problema | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Soluções |
|