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 Dashboard de desenvolvedores para criar, revelar, excluir e girar chaves de API. Para acessar suas chaves de API v1, selecione a guia Chaves de API no Dashboard.
Tipos de chave
Por padrão, todas as contas têm um total de quatro chaves API, duas em uma área restrita e duas no modo de produção:
- Chave secreta da área restrita: use essa chave para autenticar 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ção. Reserve esta chave para testes e desenvolvimento para garantir que você não modifique acidentalmente seus clientes ou cobranças do modo de produção.
- Chave publicável da área restrita: use essa chave para fins de teste no código do lado do cliente do aplicativo móvel. Reserve esta chave para testes e desenvolvimento para garantir que você não modifique acidentalmente seus clientes ou cobranças do modo de produção.
- Chave secreta do modo de produção: use essa chave para autenticar 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ção.
- Chave publicável no modo de produção: use esta chave quando estiver pronto para lançar seu aplicativo, no código do lado do cliente do seu aplicativo móvel ou web.
Suas chaves secretas e publicáveis estão no Dashboard na guia Chaves de API. Se você não conseguir visualizar suas chaves de API, peça ao titular da sua conta Stripe para adicionar você à 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.
Quando você está conectado à Stripe, nossa documentação preenche automaticamente os exemplos de código com suas chaves de API de teste. Só você pode ver esses valores. Se você não estiver conectado, nossos exemplos de código incluem chaves de API geradas aleatoriamente. Você pode substituí-las por suas próprias chaves de teste ou fazer login para ver os exemplos de código preenchidos com suas chaves de API de teste.
A tabela a seguir mostra exemplos gerados aleatoriamente de chaves de API secretas e publicáveis:
| Tipo | Valor | Quando usar |
|---|---|---|
| Secreta | sk_ | 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_ | No lado do cliente: pode ser acessada publicamente no código do lado do cliente do seu aplicativo móvel (como checkout.js) para coletar informações de pagamento com segurança, por exemplo, usando o Stripe Elements. Por padrão, o Stripe Checkout coleta dados de pagamento com segurança. |
| Restritas | Uma string que começa com rk_ | 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. |
Área restrita e modo de produção
Todas as solicitações de API da Stripe ocorrem em uma área restrita ou modo de produção. Use 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 de API. Os objetos em um modo não são acessíveis no outro. Por exemplo, um objeto de produto de á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 um segredo do modo de produção ou uma chave de API restrita uma vez. Se você perdê-la, não será possível recuperá-la no Dashboard. Nesse caso, gire-a 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. |
Girar uma chave de API
Girar uma chave a revoga e gera uma chave de substituição. Você pode girar uma chave imediatamente ou agendar uma chave para girar após um determinado tempo. Gire uma chave em cenários como os seguintes:
- Se você estiver no modo de produção e perder uma chave secreta ou restrita, não será possível recuperá-la do Dashboard e será preciso substituí-la.
- Se uma chave secreta ou restrita for comprometida, você precisará revogá-la para bloquear qualquer solicitação de API mal-intencionada que possa usá-la.
- Sua política exige o rodízio de chaves em determinados intervalos.
Para girar uma chave de API:
- Abra a página de chaves de API.
- Na linha da chave que você deseja girar, clique no menu de navegação () e selecione Girar chave.
- Escolha uma data de validade no menu suspenso Validade.
- Clique em Girar chave de API.
- A caixa de diálogo exibe o novo valor da chave. Clique aqui para copiá-lo.
- Salve o valor da chave. Não é possível recuperá-lo mais tarde.
- No campo Adicionar uma observação, insira o local onde você salvou a chave e clique em Concluído ou Salvar.
Se você escolheu Agora para a Validade, nós excluiremos a chave antiga. Se tiver selecionado um tempo diferente, você verá o tempo restante até a chave vencer abaixo do nome dela.
Independentemente do prazo de validade da chave antiga, a nova chave fica pronta para uso imediatamente.
Quando você gira uma chave publicável, o nome da chave de substituição é sempre Publishable key. Quando você gira uma chave secreta, o nome da chave de substituição é sempre Secret key. Quando você gira uma chave restrita, o nome da chave de substituição é o mesmo da chave girada. Para renomear uma chave secreta ou restrita, clique no menu flutuante e selecione Editar chave.
Veja os logs de solicitação de API
Para abrir os logs de solicitação de API, clique no menu de navegação () de qualquer chave e selecione Ver logs de solicitação. Abrir os logs redireciona você ao Stripe Dashboard principal.
Chaves secretas e restritas
Use o Dashboard para criar, excluir, revelar e modificar chaves secretas e restritas.
Crie uma chave de API secreta
Para criar uma chave de API secreta:
- Abra a página de chaves de API.
- Clique em Criar chave secreta.
- A Stripe envia um código de verificação para o seu endereço de e-mail ou em uma mensagem de texto. (Como acontece com qualquer e-mail, ele pode não chegar imediatamente.) Insira o código na caixa de diálogo. Se a caixa de diálogo não continuar automaticamente, clique em Continuar.
- Insira um nome no campo Nome da chave.
- Clique em Criar.
- A caixa de diálogo exibe o novo valor da chave. Clique aqui para copiá-lo.
- Salve o valor da chave. Não é possível recuperá-lo mais tarde.
- No campo Adicionar uma observação, insira o local onde você salvou a chave e clique em Concluído.
Crie uma chave de API restrita
Uma chave de API restrita só permite o nível de acesso que você especificar.
Para criar uma chave de API restrita:
- Abra a página de chaves de API.
- Você pode criar uma chave restrita do zero ou clonar uma chave restrita existente.
- Para criar uma chave restrita do zero, clique em Criar chave restrita. Nesse caso, o valor padrão para todas as permissões é Nenhum.
- Para clonar uma chave existente, clique no menu de navegação () e selecione Duplicar chave na linha da chave que deseja clonar. Nesse caso, o valor padrão de cada permissão é seu valor na chave clonada.
- No campo Nome da chave, insira um nome. 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 que deseja permitir para a chave. Se você usa o Connect, também pode selecionar a permissão para essa chave ao acessar contas conectadas. As permissões disponíveis são Nenhuma, Leitura e Gravação.
- Clique em Criar chave.
- A Stripe envia um código de verificação para o seu endereço de e-mail ou em uma mensagem de texto. (Como acontece com qualquer e-mail, ele pode não chegar imediatamente.) Insira o código na caixa de diálogo. Se a caixa de diálogo não continuar automaticamente, clique em Continuar.
- A caixa de diálogo exibe o novo valor da chave. Clique aqui para copiá-lo.
- Salve o valor da chave. Não é possível recuperá-lo mais tarde.
- No campo Adicionar uma observação, insira o local onde você salvou a chave e clique em Concluído.
Exclua uma chave de API secreta ou restrita
Se você excluir uma chave, qualquer código que use essa chave não poderá mais fazer chamadas de API. Depois de excluir uma chave, crie uma nova e atualize o código para usá-la.
Observação
Não é possível excluir uma chave publicável.
Para excluir uma chave:
- No Dashboard do desenvolvedor, selecione a guia chaves de API.
- Localize a chave que você deseja excluir na lista Chaves padrão ou Chaves restritas. Clique no menu de navegação () na linha dessa chave e selecione Excluir chave.
- Se tiver certeza de que deseja excluir a chave, clique em Excluir chave na caixa de diálogo Excluir chave de API. Caso contrário, clique em Cancelar.
Revelar uma chave API secreta em uma área restrita
Com áreas restritas, você pode revelar uma chave de API secreta quantas vezes quiser.
Para revelar uma chave secreta em uma área restrita:
- No Dashboard do desenvolvedor, selecione a guia chaves de API.
- Na lista Chaves padrão, clique em Revelar chave de teste na linha Chave secreta.
- Copie o valor da chave clicando nele.
- Salve o valor da chave.
- Clique em Ocultar chave de teste.
Revelar um segredo ou chave de API restrita para o modo de produção
No modo de produção, a Stripe só mostra uma chave de API secreta ou restrita uma vez (para fins de segurança). Guarde a chave em um local onde você não a perderá. Para se lembrar de onde você a armazenou, pode deixar uma anotação na chave no Dashboard. Se você perder a chave, poderá girá-la ou excluí-la e criar outra.
Você não pode revelar uma chave secreta do modo de produção que criou
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 secreta ou restrita no modo de produção e anexar uma observação:
Observação
O link “Chaves de API” aqui é aberto no modo de produção.
- No Dashboard do desenvolvedor, selecione a guia chaves de API.
- Clique em Revelar chave em modo de produção na lista Chaves padrão ou na lista Chaves restritas na linha da chave que você deseja revelar.
- Copie o valor da chave clicando nele.
- Salve o valor da chave.
- Clique em Ocultar chave de teste.
- Clique no menu de navegação () ao lado da chave e selecione Editar chave.
- No campo Observação, insira o local onde você salvou a chave e clique em Salvar.
- Se você criou a chave antes de a Stripe introduzir esse recurso, clique em Ocultar chave em modo de produção.
Observação
As chaves que você criou antes de a Stripe introduzir esse recurso não são ocultadas automaticamente quando são reveladas. Você deve ocultá-las manualmente.
Limitar chaves secretas ou restritas a uma lista ou intervalo de endereços IP
Para limitar solicitações de API usando uma chave a um ou mais endereços IP específicos ou a um intervalo de endereços IP:
Intervalos de endereços IP válidos
Você pode especificar qualquer intervalo CIDR válido. Por exemplo, um intervalo válido pode ser 100., especificado como 100.. Todos os endereços no intervalo devem começar com 100..
- Abra a página de chaves de API.
- Clique no menu de navegação () na lista Chaves padrão ou Chaves restritas na linha da chave que você deseja revelar e selecione Gerenciar restrições de IP.
- Clique em Limitar uso a um conjunto de endereços IP.
- Insira um endereço IP ou um intervalo de endereços IP:
- Para um endereço IP individual, insira-o no campo Endereço IP.
- Para um intervalo de endereços IP, insira o intervalo na notação Classless Inter-Domain Routing (CIDR). No campo Endereço IP, insira o primeiro endereço no intervalo. No campo CIDR, insira o tamanho do prefixo de rede.
- Você também pode selecionar a guia Gerenciamento em massa e inserir endereços IP e intervalos individuais, separados por espaços. As alterações feitas em uma guia aparecem na outra guia.
- Para adicionar outro endereço ou intervalo, clique em + Adicionar.
- Clique em Salvar.
Alterar um nome ou observação de chave de API secreta ou restrita
Para alterar o nome ou o texto da observação de uma chave secreta ou restrita:
- Abra a página de chaves de API.
- Clique no menu de navegação () na linha da chave que você deseja alterar e selecione Editar chave.
- Se quiser alterar o nome, insira o novo nome em Nome da chave.
- Se quiser alterar o texto da observação, insira o novo texto em Observação.
- Clique em Salvar.
Mantenha suas chaves seguras
Qualquer pessoa pode usar a chave de API secreta do modo de produção para fazer chamadas de API em nome da sua conta, como criar uma cobrança ou realizar um reembolso. Mantenha suas chaves seguras seguindo as práticas recomendadas para chaves de API secretas.