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 lançar chaves de API. Para acessar suas chaves de API v1, selecione a guia Chaves de API no Dashboard.
Modo de teste e modo de produção
Todas as solicitações de API da Stripe ocorrem no modo de teste ou modo de produção. Use o modo de teste para acessar dados de teste e o modo de produção para acessar dados reais da conta. Os objetos em um modo não são acessíveis no outro. Por exemplo, um objeto de produto no modo de teste não pode fazer parte de um pagamento no modo de produção.
Chave de acesso em modo de produção
Você só pode revelar um segredo do modo de produção ou chave de API restrita uma vez. Se perdê-lo, não será possível recuperá-lo no Dashboard. Nesse caso, lance-o ou exclua-o e crie outro.
| Tipo | Quando usar | Objetos | Como usar | Considerações |
|---|---|---|---|---|
| modo de teste | Use o modo de teste e as chaves de API de teste associadas enquanto cria sua integração. No modo de teste, 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 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. |
Chaves secretas e publicáveis
Todas as contas têm um total de quatro chaves de API por padrão, duas para o modo de teste e duas para o modo de produção:
- Chave secreta do modo de teste: use essa chave para autenticar solicitações no seu servidor quando estiver no modo de teste. Por padrão, você pode usar essa chave para realizar qualquer solicitação de API sem restrição.
- Chave publicável do modo de teste: use essa chave para fins de teste no código do lado do cliente do seu aplicativo móvel.
- 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.
Testes e desenvolvimento
Use apenas suas chaves de API de teste para teste e desenvolvimento. Isso garante que você não modifique acidentalmente seus clientes ou cobranças em tempo real.
You can find your secret and publishable keys in API keys. When you’re logged in, Stripe’s documentation automatically populates code examples with your test mode 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. 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.
A tabela a seguir mostra exemplos gerados aleatoriamente de chaves de API secretas e publicáveis:
Chaves de API restritas
The Dashboard can also generate restricted API keys, enabling customizable and limited access to the API. However, Stripe doesn’t offer any restricted keys by default.
| 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. |
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.
Personalize o acesso à API com chaves de API restritas
Para fornecer acesso limitado à API, crie chaves de API restritas. Você pode configurar uma chave de API restrita para permitir acesso de leitura ou gravação a recursos da API específicos. Ao usar microsserviços que interagem com a API em seu nome, defina chaves restritas que permitam somente o acesso mínimo exigido por esses microsserviços. Por exemplo, se você usa um serviço de monitoramento de contestações, crie uma chave restrita que só forneça acesso de leitura a recursos relacionados a contestações. Essa chave permite que o serviço obtenha os dados necessários, mas não permite fazer alterações ou acessar nenhum outro dado.
As chaves restritas não podem interagir com muitas partes da API da Stripe, pois sua finalidade é reduzir o risco durante o uso ou a criação de microsserviços. Não use chaves restritas como alternativa ao segredo da sua conta ou às chaves de API publicáveis durante o desenvolvimento da sua integração com a Stripe .
Erros de permissão
Se você usar uma chave de API restrita em uma chamada à qual ela não tem acesso, a Stripe gera um erro de permissão.
Limitar os endereços IP que podem enviar solicitações de API
Você pode aumentar a segurança de uma chave secreta ou restrita limitando os endereços IP que podem usá-la para enviar solicitações de API. Além disso, é possível restringir uma chave a um ou mais endereços IP ou a um intervalo de endereços IP.
Revelar uma chave secreta de API para o modo de teste
No modo de teste, você pode revelar uma chave de API secreta quantas vezes quiser.
Para revelar uma chave secreta no modo de teste:
- No Dashboard do desenvolvedor, selecione a guia chaves de API.
- Na lista de Chaves padrão, na linha Chave secreta, clique em Revelar chave de teste.
- 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
Por segurança, no modo de produção, a Stripe só mostra uma chave secreta ou restrita de API uma vez. Guarde a chave em um local seguro onde você não a perderá. Para ajudar a si mesmo a lembrar onde você a armazenou, deixe uma observação na chave no Dashboard. Se você perder a chave, revogue-a ou exclua-a e crie outra.
Você não pode revelar uma chave secreta do modo de produção que criou
Depois que você cria um segredo ou chave de API restrita no modo de produção, nós exibimos o valor antes de salvá-lo. Você precisa copiar o valor antes de salvá-lo, pois não é possível revelá-lo depois. Só é possível revelar uma chave secreta padrão ou uma chave gerada por uma revogação agendada.
Para revelar uma chave secreta ou restrita no modo de produção e anexar uma observação:
Observação
O link API keys aqui é aberto no modo de produção.
- No Dashboard do desenvolvedor, selecione a guia chaves de API.
- Na lista de Chaves padrão ou na lista de Chaves restritas, na linha da chave que você deseja revelar, clique em Revelar chave em modo de produção.
- 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.
Revogar uma chave de API
O processo de revogação de uma chave a revoga e gera uma chave de substituição. É possível revogar uma chave imediatamente ou agendar uma revogação para depois de um determinado período. Revogue 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 revogar uma chave de API:
- Abra a página de chaves de API.
- Na linha da chave que você deseja revogar, clique no menu de navegação () e selecione **Revogar chave… **.
- Escolha uma data de validade no menu suspenso Validade.
- Clique em Lançar 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ê revoga uma chave publicável, o nome da chave de substituição é sempre Publishable key. Quando você revoga uma chave secreta, o nome da chave de substituição é sempre Secret key. Quando você revoga uma chave restrita, o nome da chave de substituição é o mesmo da chave revogada. Para renomear uma chave secreta ou restrita, clique no menu flutuante e selecione **Editar chave… **.
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. Crie uma chave 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 de Chaves padrão ou Chaves restritas. Clique no ícone do menu de navegação () na linha dessa chave e selecione **Excluir chave… **.
- Na caixa de diálogo Excluir chave de API, se tiver certeza de que deseja excluir a chave, clique em Excluir chave. Caso contrário, clique em Cancelar.
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, na linha da chave que deseja clonar, clique no menu de navegação () e selecione **Duplicar chave… **. 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 correspondente a essa chave. Se você usa o Connect, também pode selecionar a permissão dessa chave ao acessar contas conectadas. As permissões disponíveis são Nenhuma, Leitura ou 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.
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.
- Na lista de Chaves padrão ou Chaves restritas, na linha da chave que deseja revelar, clique no menu de navegação () 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.
- Na linha da chave que você deseja alterar, clique no menu de navegação () 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.
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.