Pular para o conteúdo
Criar conta
ou
Entrar
O logotipo da documentação da Stripe
/
Pergunte à IA
Criar conta
Login
Comece já
Pagamentos
Receita
Plataformas e marketplaces
Gestão de valores
Ferramentas para desenvolvedores
Visão geral
Controle de versão
Changelog
Atualize sua versão da API
Faça upgrade da sua versão do SDK
Ferramentas para desenvolvedores
SDKs
API
    API v2
    Chaves de API
    Cabeçalho do Stripe-Context
    Changelog diário
    Limitações de fluxo
    Testes automáticos
    Metadados
    Expandir respostas
    Paginação
    Domínios e endereços IP
    Pesquisar
    Localização
    Tratamento de erros
      Tratamento de erros avançado
    Códigos de erro
Testes
Workbench
Destinos de evento
Fluxos de trabalho
Stripe CLI
Stripe Shell
Dashboard de desenvolvedores
Kit de ferramentas para agentes
Desenvolver com LLMsStripe para Visual Studio CodeAlertas de integridade da StripeCarregamento de arquivos
Segurança e privacidade
Segurança
Privacidade
Extend Stripe
Stripe Apps
Stripe Connectors
Parceiros
Ecossistema de parceiros
Certificação de parceiro
Página inicialFerramentas para desenvolvedoresAPI

Tratamento de erros

Capture e responda a recusas, dados inválidos, problemas de rede e outras ocorrências.

Copiar página

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écnicaObjetivoQuando necessário
Usar valores de erroRecuperar quando uma chamada de API não consegue continuarSempre
Monitorar webhooksReagir a notificações da StripeAlgumas vezes
Obter informações armazenadas sobre falhasInvestigar problemas passados e apoiar outras técnicasAlgumas vezes

Usar valores de erro

Erros e HTTP

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 e o objeto Error.

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. Em alguns casos, você pode forçar a propriedade Err a um tipo de erro mais específico com informações adicionais.

Ir
package main import ( "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/paymentintent" "log" ) func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { switch stripeErr.Type { case stripe.ErrorTypeCard: log.Println("A payment error occurred:", stripeErr.Msg) case stripe.ErrorTypeInvalidRequest: log.Println("An invalid request occurred.") default: log.Println("Another Stripe error occurred.") } } else { log.Println("An error occurred that was unrelated to Stripe.") } } }

Depois de configurar o gerenciamento de exceções, teste-o com diversos dados, incluindo cartões de teste, para simular diversos resultados de pagamentos.

Ir
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), // The required parameter currency is missing Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_visa"
), } example_function(params)
console
Ir
1749848212 An invalid request occurred.

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:

  1. Obtenha o objeto afetado realizando um unmarshall dos dados de event.Data.Raw.
  2. Use informações armazenadas no objeto afetado para obter contexto, incluindo um objeto de erro.
  3. Use seu tipo para escolher uma resposta.
Ir
package main import ( "encoding/json" "io/ioutil" "log" "net/http" "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/webhook" ) func main() { http.HandleFunc("/webhook", handleWebhook) addr := "localhost:4242" log.Printf("Listening on %s", addr) log.Fatal(http.ListenAndServe(addr, nil)) } func handleWebhook(w http.ResponseWriter, req *http.Request) { const MaxBodyBytes = int64(65536) req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes) payload, err := ioutil.ReadAll(req.Body) if err != nil { log.Printf("Error reading request body: %v\n", err) w.WriteHeader(http.StatusServiceUnavailable) return } // Replace this endpoint secret with your endpoint's unique secret // If you are testing with the CLI, find the secret by running 'stripe listen' // If you are using an endpoint defined with the API or dashboard, look in your webhook settings // at https://dashboard.stripe.com/webhooks endpointSecret := "whsec_..." signatureHeader := req.Header.Get("Stripe-Signature") // Get an event object event, err := webhook.ConstructEvent(payload, signatureHeader, endpointSecret) if err != nil { log.Printf("⚠️ Webhook signature verification failed. %v\n", err) w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature return } // Use its type to find out what happened switch event.Type { case "payment_intent.payment_failed": // Get the object affected by unmarshalling event data into // the appropriate struct for the event type var paymentIntent stripe.PaymentIntent err := json.Unmarshal(event.Data.Raw, &paymentIntent) if err != nil { log.Printf("Error parsing webhook JSON: %v\n", err) w.WriteHeader(http.StatusBadRequest) return } // Use stored data to get an error object e := paymentIntent.LastPaymentError // Use its type to choose a response switch e.Type { case "card_error": log.Println("A payment error occurred: ", e.Msg) case "invalid_request": log.Println("An invalid request occurred.") default: log.Println("Another problem occurred, maybe unrelated to Stripe.") } default: log.Println("Unhandled event type: ", event.Type) } w.WriteHeader(http.StatusOK) }

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:

  1. Recupere uma intenção de pagamento específica.
  2. Para saber se houve um erro de pagamento na intenção, verifique se last_payment_error está vazio.
  3. Se ocorreu, registre o erro, incluindo seu tipo e o objeto afetado.
Ir
stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
pi, _ := paymentintent.Get(
"{{PAYMENT_INTENT_ID}}"
, nil, ) paymentErr := pi.LastPaymentError if paymentErr != nil { log.Printf("PaymentIntent %s experienced a %s error.", pi.ID, paymentErr.Type) }

Veja a seguir os objetos comuns que armazenam informações sobre falhas.

ObjetoAtributoValores
Payment Intentlast_payment_errorUm objeto de erro
Setup Intentlast_setup_errorUm objeto de erro
Invoicelast_finalization_errorUm objeto de erro
Setup Attemptsetup_errorUm objeto de erro
Payoutfailure_codeUm código de falha de repasse
Refundfailure_reasonUm 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

stripe.ErrorTypeCard

Ocorreu um erro durante um pagamento que envolve uma destas situações:
  • Pagamento bloqueado por suspeita de fraude
  • Pagamento recusado pelo emissor
  • Outros erros de pagamento
Erro de solicitação inválida

stripe.ErrorTypeInvalidRequest

Você fez uma chamada de API de uma forma inválida no momento. Por exemplo:

  • Erro de limitação de fluxo
  • Erro de autenticação
  • Parâmetros ou estado inválidos
Erro de API

stripe.ErrorTypeAPI

Ocorreu um erro no lado da Stripe (raramente acontece).
Erro de idempotência

stripe.ErrorTypeIdempotency

Você usou uma chave de idempotência para algo inesperado, como repetir uma solicitação passando parâmetros diferentes.

Erros de cartão

Erros de pagamento não relacionados a 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. 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
  • Pagamento recusado pelo emissor
  • Outros erros de pagamento

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.)

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) if charge.Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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.)

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { if stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("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
  • Simulação de pagamentos recusados e outros erros de cartão

O código de teste abaixo demonstra algumas possibilidades.

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), Currency: stripe.String(string(stripe.CurrencyUSD)), Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_radarBlock"
), } example_function(params)
console
Go
1749848212 Payment blocked for suspected fraud.

Bloqueado por suspeita de fraude

Tipo

stripe.ErrorTypeCard

Códigos
charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked"
Códigos

stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"

ProblemaO 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:

  • Otimize sua integração do Radar para coletar dados mais detalhados.
  • Use Payment Links, Checkout ou Stripe Elements para elementos de formulário pré-integrados e otimizados.

Os clientes do Radar for Fraud Teams 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. Radar for Fraud Teams
  • Para alterar os critérios de bloqueio de um pagamento, use regras personalizadas. Radar for Fraud Teams

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

stripe.ErrorTypeCard

Códigos

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

ProblemaO 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:

  • Siga as recomendações para reduzir recusas do emissor.
  • Use Payment Links, Checkout ou Stripe Elements 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.

Outros erros de pagamento

Tipo

stripe.ErrorTypeCard

ProblemaOcorreu outro erro de pagamento.
SoluçõesEste 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.Code) 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_limit e lock_timeout indicam erros de limitação de fluxo
  • secret_key_required indica um erro de autenticação
  • Outros códigos de erro indicam estado ou parâmetros inválidos

Erros de limitação de fluxo

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
ProblemaVocê 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 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.

Erros de autenticação

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code == stripe.ErrorCodeSecretKeyRequired
ProblemaA Stripe não consegue autenticar você com os dados informados.
Soluções
  • Use a chave de API correta.
  • Verifique se não está usando uma chave “alternada” ou revogada.

Estado ou parâmetros inválidos

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired
ProblemaVocê fez uma chamada de API com parâmetros errados, no estado errado ou de forma inválida.
SoluçõesNa 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 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

ProblemaOcorreu 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

stripe.ErrorTypeIdempotency

ProblemaVocê 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.
Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc