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.
Investigar problemas passados e apoiar outras técnicas
Algumas vezes
Capturar exceções
Se um problema imediato impedir que uma chamada de API continue, a biblioteca Node.js do 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.
Depois de configurar o gerenciamento de exceções, teste-o com diversos dados, incluindo cartões de teste, para simular diversos resultados de pagamentos.
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:
);const express =require('express');const app =express();
app.post('/webhook', express.json({type:'application/json'}),(request, response)=>{// Get an event objectconst event = request.body;// Use its type to find out what happenedif(event.type=='payment_intent.payment_failed'){// Get the object affectedconst paymentIntent = event.data.object;// Use stored information to get an error objectconst error = paymentIntent.error;// Use its type to choose a responseswitch(error.type){case'StripeCardError':
console.log(`A payment error occurred: ${error.message}`);break;case'StripeInvalidRequestError':
console.log('An invalid request occurred.');if(error.param){
console.log(`The parameter ${error.param} is invalid or missing.`);}break;default:
console.log('Another problem occurred, maybe unrelated to Stripe.');break;}}
response.send();});
app.listen(4242,()=> console.log('Running on port 4242'));
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.
Command Line
stripe trigger payment_intent.payment_failed
Output
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.
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:
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.
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 encontrar o resultado da cobrança de um objeto de erro, obtenha primeiro o Payment Intent envolvido e a última cobrança criada. Confira o exemplo abaixo para ver uma demonstração.
Esse erro pode ocorrer quando sua integração está funcionando corretamente. Ele reflete uma ação do emissor, que pode ser legítima. Use o código de recusa para determinar quais são as próximas etapas adequadas. Consulte a documentação sobre códigos de recusa para obter as respostas adequadas a cada código.
Este erro pode ocorrer quando a integração está funcionando corretamente. Use o código de recusa para determinar as próximas etapas adequadas. Consulte a documentação sobre códigos de erro para ver 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.
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 de API como indeterminado. Ou seja, não suponha que foi bem ou malsucedido.
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 facilitar a recuperação de erros de conexão:
Ao criar ou atualizar um objeto, use uma chave de idempotência. 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 realizar a atualização duas vezes. Repita a solicitação com a mesma chave de idempotência até receber claramente um êxito ou falha. Para ver orientações avançadas sobre essa estratégia, consulte Tratamento de erros em nível inferior.
Ative as tentativas automáticas. Dessa forma, a Stripe gera chaves de idempotência para você e repete as solicitações quando for seguro fazer isso.
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 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.
Você usou uma chave de idempotência 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
Você está usando uma chave de API restrita para um serviço ao qual ela não tem acesso?
Are you performing an action in the Dashboard while logged in as a user role that lacks permission?
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 de API após um intervalo e aumente exponencialmente esse intervalo caso o erro persista. Veja a documentação sobre limitações de fluxo para obter mais orientaçõ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 na Stripe), consulte a documentação sobre verificação de assinaturas de webhooks para obter mais orientações. Especificamente, verifique se está usando o segredo de endpoint correto. Ele é diferente da chave de API.
Welcome to the Stripe Shell!
Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.
- View supported Stripe commands:
- Find webhook events:
- Listen for webhook events:
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
O Stripe Shell oferece uma melhor experiência em desktops.