Skip to main content
O Dashboard mostra dois tipos de chave, ambos separados por ambiente:

​
Chaves publicáveis

As duas chaves pk_* são criadas automaticamente com a organização e ficam visíveis em Developers → Chaves de API. Inicialize o SDK com a chave do ambiente:
Uma chave publicável pode ser incluída no JavaScript do site. Ela não lista customers, pagamentos ou cadastros e não substitui uma chave secreta. Para consultar ou concluir um cadastro de cartão, o browser também precisa do client_secret exato daquele setup_intent.
Publicável não significa que ela autoriza a conta. O acesso ao cadastro exige também o client_secret correspondente. Não exponha esse secret em analytics ou logs e nunca coloque uma chave secreta ch_* no browser.

​
Chaves secretas

Uma chave ch_* autentica chamadas server-to-server. Para saber quais headers e escopos enviar em cada request, consulte Autenticação.
O token completo aparece uma única vez, logo após a criação. Copie-o nesse momento e guarde-o em um secret manager ou variável de ambiente protegida.

​
Antes de começar

  • Entre no Dashboard como Administrador da organização.
  • Abra Developers → Chaves de API.
  • Decida se a chave será de teste ou produção e qual integração vai usá-la.

​
Criar uma chave secreta da sua organização

1

Crie uma nova chave

Clique em Nova chave e use um nome que identifique o serviço e o ambiente, como Faturamento — produção.
2

Escolha o acesso necessário

Selecione somente os escopos exigidos pela integração. Uma rotina de consulta precisa de read; uma integração que cria ou altera recursos precisa de write.
3

Defina ambiente e expiração

Escolha test ou live. Se o acesso for temporário, defina também uma data de expiração.
4

Copie e armazene o token

Copie o token antes de fechar a tela. Depois disso, ele não pode ser exibido novamente.
Dados e credenciais não atravessam ambientes. Veja os cenários disponíveis em Sandbox.

​
Credencial secreta e ID da chave

Cada API key possui dois valores diferentes: Para consultar somente as requests feitas por uma chave específica, envie o ID público no filtro api_key:
Em 1º de agosto de 2026, os IDs públicos de API keys existentes deixaram os formatos legados sk_live_... e sk_test_... e passaram para key_.... As credenciais secretas ch_live_... e ch_test_... não foram alteradas. Se sua integração armazenava o ID público para filtrar requests, atualize esse valor; nenhuma rotação da credencial é necessária.

​
Chargefy for Platforms: chaves da plataforma

Este recurso só está disponível para Chargefy for Platforms. Ter um SaaS, aplicativo ou marketplace próprio não significa que sua conta usa esse produto. Esta seção se aplica a quem opera pagamentos para suas organizações filhas.

​
Chaves publicáveis automáticas

Cada plataforma recebe automaticamente uma pk_test_* e uma pk_live_* quando é criada, sem ação manual. No console da plataforma, abra Developers → Chaves de API para copiá-las. Elas são independentes das chaves da organização dona e das chaves de suas organizações filhas, inclusive no registro de último uso. Use a chave publicável da plataforma no navegador para consultar ou confirmar o cadastro de cartão de uma organização filha. O client_secret precisa ser do cadastro exato e do mesmo ambiente; a plataforma e o vínculo com a filha precisam estar ativos. A chave da organização dona atende somente os cadastros da própria organização — ela não pode substituir a chave da plataforma.
Para a operação própria da organização dona, use as chaves do console da organização. Criar uma plataforma não altera essas chaves.

​
Criar uma chave secreta

A chave secreta do Chargefy for Platforms é criada na configuração da plataforma e usa o escopo exclusivo platform_admin.
1

Conclua a configuração

O Chargefy for Platforms precisa estar ativo e com as regras de split configuradas.
2

Gere a chave

Como Administrador, informe um nome e escolha o ambiente.
3

Copie e proteja o token

O token também aparece uma única vez. Guarde-o no backend em um secret manager.
Para atuar em uma organização filha, siga as regras de URL e do header Organization descritas em Autenticação do Chargefy for Platforms.

​
Acompanhar as chaves

A lista do Dashboard mostra:
  • nome e trecho mascarado do token;
  • ambiente e escopos;
  • criação e último uso;
  • expiração, quando configurada;
  • estado ativo, expirado ou revogado.
Ative Mostrar revogadas para consultar o histórico. Use “último uso” para confirmar uma implantação nova e identificar credenciais que deixaram de ser necessárias.

​
Expirar ou revogar

Revogação não pode ser desfeita. Apagar o segredo de um commit, log ou ticket não torna a credencial segura novamente.

​
Rotacionar sem downtime

1

Crie a substituta

Use o mesmo ambiente e apenas os escopos necessários.
2

Atualize a aplicação

Troque o valor no secret manager e publique a configuração.
3

Confirme o novo uso

Faça uma chamada autenticada e confira o horário de último uso da chave nova no Dashboard.
4

Revogue a anterior

Remova a chave antiga somente depois de confirmar que nenhum processo ainda depende dela.

​
Checklist de segurança

  • Use uma chave por integração para facilitar auditoria e revogação.
  • Nunca coloque chaves secretas ch_* em browser, aplicativo mobile, URL, log ou repositório. Chaves publicáveis pk_* foram feitas para o frontend.
  • Separe desenvolvimento, staging e produção.
  • Conceda o menor escopo necessário.
  • Monitore último uso, expiração e chaves sem atividade.
  • Revogue imediatamente qualquer credencial exposta.

​
Se a chave não funcionar

Veja os headers, escopos e erros de contexto em Autenticação. Para armazenamento, logs e resposta a incidentes, consulte Autenticação e segurança.

​
Próximos passos

Autenticação

Envie a credencial e escolha o contexto correto.

Autenticação e segurança

Proteja credenciais, dados de cartão, webhooks e logs.

Sandbox

Teste a integração sem efeito financeiro real.

Webhooks

Verifique eventos assinados no seu servidor.