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.

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.

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`	No lado do servidor: deve ser secreta e estar armazenada com segurança no código do lado do servidor do seu aplicativo web ou móvel (como em uma variável de ambiente ou sistema de gerenciamento de credenciais) para chamar as APIs da Stripe. Não exponha essa chave em um site nem a incorpore em um aplicativo móvel.
Publicável	`pk_test_TYooMQauvdEDq54NiTphI7jx`	Do lado cliente: pode ser acessível publicamente no código do lado do cliente do seu aplicativo web ou móvel (como checkout.js) para recolher informações de pagamento de forma segura (como com o Stripe Elements). Por padrão, o Stripe Checkout coleta informações de pagamento de forma segura.
Restritas	Uma string que começa com `rk_test_`	Em microsserviços: deve ser secreta e estar armazenada com segurança no seu código de microsserviço para chamar as APIs da Stripe. Não exponha essa chave em um site nem a incorpore em um aplicativo móvel.

Proteja suas chaves

Qualquer pessoa pode usar sua chave secreta no modo de produção para criar um chamada da API em nome da seu conta, como criar um cobrança ou realizar um reembolso. Siga estas práticas recomendadas para manter suas chaves API secretas seguras.

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

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.

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 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 API secreta ou uma chave API restrita a uma faixa de endereços IP, ou a um ou mais endereços IP específicos.

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.

Excluir uma chave API

Se você deletar uma chave API secreta ou uma chave API restrita, deve criar uma nova e atualizar qualquer código que use a chave deletada. Qualquer código que use a chave deletada não pode mais fazer chamadas de API.

Nota

Não é possível excluir uma chave publicável.

Na aba chaves API , na lista Chaves padrão ou Chaves restritas, clique no menu overflow () para a chave que você deseja deletar.
Selecione Excluir chave.
No diálogo, clique em Excluir chave. Se você não quiser mais deletar 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 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.

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.