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 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.
defexample_function(params)beginStripe::PaymentIntent.create(params)rescueStripe::CardError=> e
puts "A payment error occurred: #{e.error.message}"rescueStripe::InvalidRequestError=> e
puts "An invalid request occurred."rescueStripe::StripeError=> e
puts "Another problem occurred, maybe unrelated to Stripe."else
puts "No error."endend
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:
require'stripe'require'sinatra'
post '/webhook'do
payload = request.body.read
data =JSON.parse(payload, symbolize_names:true)# Get the event object
event =Stripe::Event.construct_from(data)# Use the event type to find out what happenedcase event.type
when'payment_intent.payment_failed'# Get the object affected
payment_intent = event.data.object
# Use stored information to get an error object
e = payment_intent.last_payment_error
# Use its type to choose a responsecase e.type
when'card_error'
puts "A payment error occurred: #{e.message}"when'invalid_request'
puts "An invalid request occurred."else
puts "Another problem occurred, maybe unrelated to Stripe."endend
content_type 'application/json'{
status:'success'}.to_json
end
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 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.
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:
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.
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
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.
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 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:
When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. Repeat the request with the same idempotency key until you receive a clear success or failure. For advanced advice on this strategy, see Low-level error handling.
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
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 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.
You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
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
Are you using a restricted API key for a service it doesn’t have access to?
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
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.
To handle rate-limiting automatically, retry the API call after a delay, and increase the delay exponentially if the error continues. See the documentation on rate limits for further advice.
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.
If you receive this error when you shouldn’t—for instance, with webhooks that you know originate with Stripe—then see the documentation on checking webhook signatures for further advice. In particular, make sure you’re using the correct endpoint secret. This is different from your API key.