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
By default, all accounts have a total of four API keys, two in a sandbox and two in live mode:
- Sandbox secret key: Use this key to authenticate requests on your server when you’re testing in a sandbox. By default, you can use this key to perform any API request without restriction. Reserve this key for testing and development to make sure that you don’t accidentally modify your live customers or charges.
- Sandbox publishable key: Use this key for testing purposes in your web or mobile app’s client-side code. Reserve this key for testing and development to make sure that you don’t accidentally modify your live customers or charges.
- 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.
Your secret and publishable keys are in the Dashboard in the API keys tab. If you can’t view your API keys, ask the owner of your Stripe account to add you to their team with the proper permissions.
Chaves de API restritas
You can generate restricted API keys in the Dashboard to enable customizable and limited access to the API. However, Stripe doesn’t offer any restricted keys by default.
When you’re logged in to Stripe, our documentation automatically populates code examples with your test API keys. Only you can see these values. If you’re not logged in, our code examples include randomly generated API keys. You can replace them with your own test keys or log in to see the code examples populated with your test API keys.
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_ | On the client side: Can be publicly accessible in your web or mobile app’s client-side code (such as checkout.js) to securely collect payment information, such as with Stripe Elements. By default, Stripe Checkout securely collects payment information. |
| 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 |
|---|---|---|---|---|
| sandboxes | Use a sandbox, and its associated test API keys, as you build your integration. In a sandbox, card networks and payment providers don’t process payments. | 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 test credit cards and accounts. You can’t accept real payment methods or work with real accounts. | Identity doesn’t perform any verification checks. Also, Connect account objects don’t return sensitive fields. |
| 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. | Disputes have a more nuanced flow and a simpler testing process. Also, some payment methods have a more nuanced flow and require more steps. |
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.