Chaves de API

Use chaves de API para autenticar solicitações de API.

A Stripe autentica suas solicitações de API usando as chaves de API da sua conta. Se uma solicitação não incluir uma chave válida, a Stripe retorna um erro de solicitação inválida. Se uma solicitação incluir uma chave excluída ou expirada, a Stripe retorna um erro de autenticação.

Use o Painel de Desenvolvedores para criar, revelar, excluir e girar chaves API. Você pode acessar suas chaves API v1 na aba API.

Novo na Stripe?

Criando e testando? Use suas chaves da área restrita (modo de teste). Chaves da área restrita começam com pk_test_ (publicável) e sk_test_ (chave secreta). Elas permitem testar sem afetar dados de produção.
Pronto para aceitar pagamentos reais? Mude para suas chaves do modo de produção, que começam com pk_live_ e sk_live_. Consulte Mudar para modo de produção para ver instruções.
Procurando seu segredo de assinatura de Webhook? Segredos de assinatura de Webhook são separados de chaves de API. Encontre-os na seção Webhooks do Dashboard em cada endpoint de Webhook.

Tipos de chave

Por padrão, todas as contas possuem um total de quatro chaves API:

Tipo	Descrição
Chave secreta na área restrita	Autentique as solicitações no seu servidor quando estiver testando em uma área restrita. Por padrão, você pode usar essa chave para realizar qualquer solicitação de API sem restrições. Reserve essa chave para testes e desenvolvimento, para garantir que você não altere acidentalmente seus clientes ou cobranças.
Chave publicável na área restrita	Teste as solicitações no código do lado do cliente do seu aplicativo web ou dispositivos móveis. Reserve essa chave para testes e desenvolvimento, para garantir que você não altere acidentalmente seus clientes ou cobranças.
Chave secreta no modo de produção	Autentique as solicitações no seu servidor quando estiver no modo de produção. Por padrão, você pode usar essa chave para realizar qualquer solicitação de API sem restrições.
Chave publicável no modo de produção	Quando estiver pronto para lançar seu aplicativo, use esta chave no código do lado do cliente do seu aplicativo web ou dispositivos móveis.

Suas chaves secretas e publicáveis estão na aba Chaves API no Dashboard. Se você não puder visualizar suas chaves API, peça ao proprietário da sua conta Stripe para adicioná-lona equipe com as permissões adequadas.

Chaves de API restritas

Você pode gerar chaves de API restritas no Dashboard para habilitar acesso personalizável e limitado à API. No entanto, a Stripe não oferece chaves restritas por padrão.

Procurando seu segredo de assinatura de Webhook?

Segredos de assinatura de Webhook não são chaves de API. Você pode encontrar o segredo de assinatura para cada endpoint de Webhook na seção Webhooks do Dashboard. Selec a um endpoint e expanda a seção Segredo de assinatura.

Se você está logado na Stripe, nossa documentação preenche exemplos de código com suas chaves API de teste. Só você pode ver esses valores. Se você não estiver logado, nossos exemplos de código incluem chaves API geradas aleatoriamente que você pode substituir pelas suas chaves de teste. Ou você pode login para ver os exemplos de código preenchidos com suas chaves API de teste.

Exemplos de chaves API

A tabela a seguir mostra exemplos de chaves secretas e publicáveis geradas aleatoriamente :

Tipo	Valor	Quando usar
Secreta	`sk_test_BQokikJOvBiI2HlWgH4olfQ2`	Somente do lado do servidor. Use esta chave no seu código de back-end, por exemplo, em uma variável de ambiente, para fazer chamada da API para a Stripe. Mantenha ela privada: nunca compartilhe, faça commit em controle de versão nem exponha em um navegador ou app para dispositivos móveis. Qualquer pessoa com essa chave pode fazer chamada da API como sua conta.
Publicável	`pk_test_TYooMQauvdEDq54NiTphI7jx`	Do lado do cliente (navegador ou app para dispositivos móveis). Use esta chave no seu código de front-end para recolher dados de pagamento com segurança com ferramentas como Stripe Elements ou Stripe Checkout. Esta chave pode ser pública.
Restritas	Uma string que começa com `rk_test_`	Somente do lado do servidor, com permissões limitadas. Como uma chave secreta, mas você escolhe exatamente a quais recursos da API da Stripe ela pode acessar. Use chaves restritas em vez de chaves secretas quando você quiser limitar o que um sistema ou terceiro pode fazer. Consulte chaves de API restritas.

Proteja suas chaves

Qualquer pessoa pode usar sua chave secreta do modo de produção para fazer qualquer chamada da API em nome da sua conta, como criar uma cobrança ou processar um reembolso. Proteja suas chaves seguindo estas práticas recomendadas:

Armazene chaves secretas em um cofre de segredos ou em variáveis de ambiente criptografadas. Não armazene chaves no código-fonte ou em arquivos de configuração registrados no controle de versão.
Use chaves de API restritas em vez de chaves secretas sempre que possível. Chaves restritas limitam o acesso apenas aos recursos da API específicos de que sua integração precisa, reduzindo o impacto de uma chave comprometida.
Limite chaves a endereços IP específicos para que elas só possam ser usadas a partir dos seus servidores conhecidos.
Faça a rotação de chaves quando membros da equipe com acesso às chaves saírem da sua organização.
Não compartilhe chaves por e-mail, conversar ou outros canais não criptografados.

Para mais detalhes, consulte práticas recomendadas para gerenciar chaves secretas de API.

Área restrita e modo de produção

Todas as solicitações de API da Stripe ocorrem em uma área restrita ou no modo de produção. Você pode usar uma área restrita para acessar dados de teste e o modo de produção para acessar dados reais da conta. Cada modo tem seu próprio conjunto de chaves API, e objetos em um modo não são acessíveis ao outro. Por exemplo, um produto objeto em área restrita não pode fazer parte de um pagamento em modo de produção .

Modo	Prefixo da chave	Finalidade
Área restrita (teste)	`pk_test_`, `sk_test_`	Criar e testar sua integração com segurança. Nenhuma cobrança real é feita.
Produção	`pk_live_`, `sk_live_`	Aceitar pagamentos reais de clientes reais.

Chave de acesso em modo de produção

Você só pode revelar uma chave secreta do modo ao vivo ou uma chave API restrita uma vez. Se você a perder, não poderá recuperá-la no Painel. Nesse caso, alterne ou exclua-a e crie uma nova.

Tipo	Quando usar	Objetos	Como usar	Considerações
Áreas restritas	Use uma área restrita e as chaves de API de teste associadas enquanto cria sua integração. Em uma área restrita, as bandeiras de cartão e os provedores de pagamento não processam pagamentos.	As chamadas de API retornam objetos simulados. Por exemplo, você pode recuperar e usar os objetos de teste `account`, `payment`, `customer`, `charge`, `refund`, `transfer`, `balance` e `subscription`.	Use cartões de crédito e contas de teste. Não é possível aceitar formas de pagamento reais ou trabalhar com contas reais.	O Identity não realiza nenhuma verificação. Além disso, os objetos de conta do Connect não retornam campos confidenciais.
Modo de produção	Use o modo de produção e as chaves de API de produção quando estiver pronto para lançar sua integração e aceitar dinheiro de verdade. No modo de produção, as bandeiras de cartão e os provedores de pagamento processam pagamentos.	As chamadas de API retornam objetos reais. Por exemplo, você pode recuperar e usar objetos reais `account`, `payment`, `customer`, `charge`, `refund`, `transfer`, `balance` e `subscription`.	Aceite cartões de crédito reais e trabalhe com contas de clientes. É possível aceitar autorizações de pagamento, cobranças e capturas de cartões de crédito e contas.	Contestações têm um fluxo mais detalhado e um processo de testes mais simples. Além disso, algumas formas de pagamento têm um fluxo mais detalhado e exigem mais etapas.

Mudar para modo de produção

Quando você estiver pronto para aceitar pagamentos reais, substitua suas chaves de API da área restrita (modo de teste) pelas suas chaves de modo de produção. Esta é a mesma página de chaves no Dashboard: você alterna entre modo de teste e modo de produção usando o seletor no canto superior direito do Dashboard de desenvolvedores.

No Dashboard de desenvolvedores, desative modo de teste usando o seletor de modo no canto superior direito. A página agora mostra suas chaves de API do modo de produção.
Copie sua chave publicável do modo de produção (começa com pk_live_) e substitua a chave pk_test_ no seu código do lado do cliente.
Revele e copie sua chave secreta do modo de produção (começa com sk_live_) e substitua a chave sk_test_ no seu código do servidor. Armazene-a com segurança: você só pode vê-la uma vez.
Se você usar Webhooks, atualize o URL de cada endpoint de Webhook e copie o novo segredo de assinatura na seção Webhooks do Dashboard.

Conclua checklist de lançamento

Mudar chaves de API é só uma etapa. Revise o checklist de lançamento completo para garantir que sua integração está pronta para produção.

Chaves de API da organização

Se você tiver várias contas empresariais Stripe em uma organização, poderá configurar uma única chave de API no nível da organização. As chaves de API no nível da organização fornecem a seguinte funcionalidade:

Acesse qualquer conta: use chaves API da organização para acessar os recursos de qualquer conta dentro da organização.

Permissões granulares: restrinja as chaves API da organização para conceder permissão de leitura ou de edição apenas a recursos específicos.
Gestão centralizada: crie e gerencie chaves API organizacionais na aba chaves API no Dashboard da sua organização.

Comportamento

As chaves de API da organização se comportam de forma diferente das chaves de API de conta, incluindo:

Eles não têm uma chave publicável. Trate todas as chaves de API da organização como chaves secretas.
Todos eles têm o mesmo prefixo sk_org, independentemente de seus níveis de permissão.
Todas as solicitações de API feitas com uma chave de API da organização devem incluir o cabeçalho Stripe-Context para identificar a conta afetada.
Todas as solicitações de API feitas com uma chave de API da organização devem incluir o cabeçalho Stripe-Version para garantir consistência e previsibilidade entre as integrações da organização.

Usar chaves de API da organização

Quando você usa uma chave de API da organização, também deve:

Especifique uma versão da API incluindo um cabeçalho Stripe-Version. Ao usar um SDK da Stripe, o SDK define automaticamente a versão da API.
Identifique a conta afetada pela solicitação de API incluindo o cabeçalho Stripe-Context.

Por exemplo, considerando a seguinte estrutura organizacional:

Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
  ├── Platform account  (acct_1R3fqDP6919yCiFv)
  |   └── Connected account (acct_1032D82eZvKYlo2C)
  └── Standalone account (acct_1aTnTtAAB0hHJ26p)

Você pode usar a chave de API da organização para acessar o saldo da conta autônoma. Também é possível usar a mesma chave para fazer a mesma chamada para a conta conectada da plataforma.

No exemplo do código anterior, substitua {{CONTEXT}} com o valor relevante:

Para a conta autônoma, use acct_1aTnTtAAB0hHJ26p.
Para a conta conectada, use um caminho que identifique tanto a plataforma quanto a conta conectada, seguindo o formato acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

Você deve especificar a conta relevante usando o contexto e a versão da API em qualquer solicitação de API usando uma chave da organização.

Organizações não têm chaves de API publicáveis porque não podem aceitar pagamentos. Você pode usar a chave API da sua organização para criar um PaymentIntent para qualquer conta da sua organização, mas deve usar chaves publicáveis específicas de conta existentes para as operações com o cliente.

Chaves de API gerenciadas

Algumas plataformas de terceiros, como Vercel, podem criar e gerenciar chaves de API em seu nome quando você instala a integração delas. Essas chaves são chamadas de chaves de API gerenciadas, e a plataforma as cria automaticamente em vez de você criá-las manualmente no Dashboard.

Chaves de API gerenciadas aparecem ao lado das outras chaves na aba Chaves de API, identificadas com o nome da plataforma que faz o gerenciamento.

A tabela a seguir resume as diferenças entre chaves não gerenciadas e chaves gerenciadas.

	Chaves não gerenciadas	Chaves gerenciadas
Criação de chave	Você cria chaves no Dashboard	A plataforma cria chaves usando a API
Interação do usuário	Você copia chaves do Dashboard e as configura na plataforma	A plataforma cuida da configuração de chaves automaticamente
Entrega de chaves	Exibida para você no Dashboard	Entregue diretamente à plataforma
Gestão de chaves	Você controla rotação e validade	A plataforma gerencia o ciclo de vida da chave; você pode expirar as chaves a qualquer momento

Revogar acesso de chave de API gerenciada

Você pode revogar uma chave de API gerenciada a qualquer momento fazendo um dos seguintes:

Expirar a chave: Na aba Chaves de API, clique no menu de overflow () da chave gerenciada e expire-a. Isso revoga imediatamente o acesso da plataforma sem remover a integração.
Desinstalar a integração: Desinstale o app da plataforma na sua conta Stripe. Ao desinstalar um app, você pode escolher expirar as chaves gerenciadas imediatamente ou mantê-las ativas.

Chaves secretas e restritas

Use o Dashboard para criar, revelar, modificar, excluir e girar chaves secretas e restritas.

Criar uma chave API

Você pode criar uma chave API secreta ou uma chave API restrita. Uma chave API restrita só permite o nível de acesso que você especificar.

Para criar uma chave API secreta

Na aba chaves API, clique em Criar chave secreta.
Na caixa de diálogo, insira o código de verificação que a Stripe envia por e-mail ou por mensagem de texto. Se o diálogo não continuar automaticamente, clique em Continuar.
Insira um nome no campo Nome da chave e clique em Criar.
Clique no valor-chave para copiá-lo.
Salve o valor da chave. Não é possível recuperá-lo mais tarde.
No campo Adicionar uma nota, insira a localização onde salvou a chave e clique em Concluído.

Para criar uma chave API restrita

Na aba chaves API, siga de uma das seguintes formas:
- Para criar uma nova chave restrita, clique em Criar chave restrita. O valor padrão para todas as permissões é Nenhum.
- Para clonar uma chave existente, clique no menu overflow (), depois selecione Duplicar chave para a chave que você deseja clonar. O valor padrão para cada permissão é o valor da chave clonada.
Insira um nome no campo Nome de chave. Se você clonou uma chave existente, o nome padrão é o nome da chave clonada.
Para cada recurso que você deseja que a nova chave acesse, selecione a permissão apropriada: Nenhum, Ler ou Editar. Se você usar o Connect, também pode selecionar a permissão para permitir essa chave acesse contas conectadas.
Clique em Criar chave.
Na caixa de diálogo, insira o código de verificação que a Stripe envia por e-mail ou por mensagem de texto. Se o diálogo não continuar automaticamente, clique em Continuar.
Clique no valor-chave para copiá-lo.
Salve o valor da chave. Não é possível recuperá-lo mais tarde.
No campo Adicionar uma nota, insira a localização onde salvou a chave e clique em Concluído.

Revelar uma chave API

Você pode revelar uma chave API secreta ou uma chave API restrita em um área restrita ou modo de produção.

No modo de produção, a Stripe só mostra a chave API uma vez (por questões de segurança). Guarde a chave em um lugar onde você não a perca. Para se lembrar onde você a armazenou, você pode adicionar uma nota no Dashboard. Se você perder a chave, pode girá-la ou excluí-la e criar outra.

Revelar chaves secretas no modo de produção

Depois que você cria uma chave de API secreta ou restrita no modo de produção, nós a exibimos antes de você salvá-la. Você precisa copiar a chave antes de salvá-la, pois não é possível copiá-la depois. Só é possível revelar uma chave secreta padrão ou uma chave gerada por uma rotação agendada.

Para revelar uma chave API secreta em uma área restrita

Na aba chaves API, na lista de Chaves padrão, clique em Revelar chave de teste na linha Chave secreta. Você pode revelar a chave API secreta quantas vezes quiser.
Clique no valor-chave para copiá-lo.
Salve o valor da chave.
Clique em Ocultar chave de teste.

Revelar uma chave API secreta ou restrita em modo de produção

No modo de produção de chaves API, na lista Chaves padrão ou Chaves restritas, clique em Revelar chave de produção para a chave que você quer revelar.
Clique no valor-chave para copiá-lo.
Salve o valor da chave.
Clique em Ocultar chave de teste.
Clique no menu de overflow (), depois selecione Editar chave para a chave à qual você quer adicionar uma nota.
No campo Notas, insira o local onde você salvou a chave e clique em Salvar.

Nota

Chaves que você criou antes da Stripe introduzir esse recurso não são automaticamente ocultas quando são reveladas. Você deve ocultá-las manualmente clicando em Ocultar chave de produção.

Limite uma chave API a certos endereços IP

Você pode limitar uma chave secreta de API ou uma chave de API restrita a um intervalo de endereços IP, ou a um ou mais endereços IP específicos. A Stripe recomenda habilitar restrições de IP em todas as chaves do modo de produção para impedir o uso a partir de localizações não autorizadas. Use listas de permissão de IP separadas para chaves separadas quando aplicável (por exemplo, para diferenciar entre ambientes de preparo e de produção).

Endereços IP devem usar o protocolo IPv4, e você pode especificar qualquer faixa CIDR válida. Por exemplo, você pode especificar o alcance 100.10.38.0 - 100.10.38.255 como100.10.38.0/24. Todos os endereços IP nesse alcance devem começar por 100.10.38.

Na aba chaves API, na lista chaves padrão ou chaves restritas, clique no menu de overflow () para a chave que você deseja revelar.
Selecione Gerenciar restrições de IP > Limitar o uso a um conjunto de endereços IP.
Siga de uma das seguintes formas:
- Insira um endereço IP de pessoa física no campo endereço IP.
- Para um intervalo de endereços IP, insira o primeiro endereço do intervalo (usando a notação Classless Inter-Domain Routing (CIDR)) no campo Endereço IP. Insira o tamanho do prefixo de rede no campo CIDR.
Você também pode inserir endereços IP e intervalos individuais (separados por espaços) na aba Gerenciar em massa. As alterações feitas em uma aba aparecerão na outra.
Para adicionar outro endereço IP ou intervalo, clique em Adicionar mais.
Clique em Salvar.

Alterar o nome ou nota de uma chave API

Na aba chaves API, clique no menu () para a chave que você quer mudar.
Selecione a Editar chave.
Faça o seguinte:
- Para mudar o nome, insira um novo nome no campo Nome da chave.
- Para alterar o texto da nota, insira o novo texto no campo Nota.
Clique em Salvar.

Expirar uma chave de API

Se você expirar uma chave de API secreta ou uma chave de API restrita, você precisa criar uma nova e atualizar qualquer código que use a chave expirada. Qualquer código que use a chave expirada não pode mais fazer chamada da API.

Nota

Você não pode expirar uma chave publicável.

Na aba Chaves de API, na lista Chaves Standard ou Chaves restritas, clique no menu de overflow () da chave que você quer expirar.
Selecione Expirar chave.
No diálogo, clique em Expirar chave. Se você não quiser mais expirar a chave, clique em Cancelar.

Girar uma chave de API

Girar uma chave API revoga e gera uma chave de substituição pronta para uso imediatamente. Você também pode programar uma chave API para girar após um certo tempo. A chave de substituição é nomeada da seguinte forma:

O nome de chave publicável de substituição é sempre Chave publicável.
O nome da chave secreta de substituição é sempre Chave secreta.
O nome da chave restrita de substituição é o mesmo da chave rotacionada.

Renomear uma chave API secreta ou restrita editando-a.

Gire uma chave API em cenários como:

Se você perder uma chave API secreta ou restrita no modo ativo e não conseguir recuperá-la no Dashboard.
Se uma chave API secreta ou restrita for comprometida e você precisar revogá-la para bloquear quaisquer solicitações API potencialmente maliciosas que possam usar a chave.
Se um membro da equipe com acesso à chave sair da sua organização ou mudar de função.
Se a sua política exigir a rotação de chaves em determinados intervalos.

Para girar uma chave API

Na aba de chaves API, clique no menu de overflow () para girar a chave que você escolheu.
Selecione Girar chave.
Selecione uma data de validade no menu suspenso Expiração. Se você escolher Agora, a chave antiga é excluída. Se você especificar um tempo, o tempo restante até a chave expirar aparece abaixo do nome da chave.
Clique em Girar chave de API.
Clique no valor-chave para copiá-lo.
Salve o valor da chave. Não é possível recuperá-lo mais tarde.
No campo Adicionar uma nota, insira a localização onde salvou a chave e clique em Salvar ou Pronto.

Restaurar o acesso de uma chave de API

Uma chave de API pode ter acesso limitado se não tiver sido usada para criar transferências, repasses ou atualizações de destinos de repasse por mais de 180 dias. Você não pode usar uma chave de acesso limitado para criar repasses e transferências ou para criar destinos de repasse. Você pode restaurar o acesso para usar a chave normalmente ou para realizar uma ação bloqueada.

Para restaurar o acesso de uma chave de API

Na aba Chaves API, clique no menu de mais opções () da chave que você deseja restaurar.
Selecione Restaurar acesso.
Clique em Restaurar.

Ver logs de solicitações de API

Para abrir os logs de solicitações de API , clique no menu de overflow () para qualquer tecla, depois selecione Ver logs de solicitação. Abrir logs redireciona você para o Stripe Dashboard.