Para o negócio: a chave secreta dá acesso a cobranças, saldos e dados de clientes. Ela deve ficar só com o time técnico responsável pela integração, guardada no servidor, e nunca deve circular por e-mail, chat ou planilha. Se alguém de fora tiver acesso a ela, peça a troca ao suporte da Finvia imediatamente.
Tipos de chave
Onde a chave pública entra
A chave pública vai no lugar do usuário do HTTP Basic, do mesmo jeito que a secreta, mas em chamadas feitas a partir do navegador:
A chave pública não cria cobranças. Ela pode ficar no HTML da página ou no aplicativo, porque só é aceita nesses fluxos. A conta precisa estar ativa para a
pk_ funcionar.
Ambientes de teste e produção
A Finvia usa o mesmo endereço para testes (sandbox) e produção. O ambiente é definido pela chave enviada na requisição: com a chave de teste (Modo Teste), as cobranças são simuladas; com a chave de produção, as transações são reais.
Os outros endereços que você vai usar:
A sua aplicação precisa de uma única variável de configuração para a URL e de uma variável para a chave. Trocar de ambiente é trocar a chave.
pk_test_) também coloca as chamadas do front-end em modo de teste. A exceção é a validação de sessão do Apple Pay: ela sempre vai ao provedor real, porque a janela de pagamento do Safari só abre com uma sessão real. A cobrança Apple Pay criada depois, com a chave de teste, é simulada normalmente.
O que é simulado no Modo Teste
O desenho abaixo mostra como a chave define o ambiente e quais operações continuam reais mesmo com a chave de teste. Para homologar assinaturas, use um cartão real com valor baixo e cancele a assinatura no mesmo dia. O cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas.Cartões de teste
No Modo Teste, o resultado da cobrança de cartão depende só do número. Envie o número só com dígitos, sem espaços (com espaços, a API responde400).
Nome, CVV e validade não mudam o resultado. Use qualquer nome, CVV numérico de 3 dígitos e validade futura (mês com 2 dígitos, ex.:
05, e ano com 4). O parcelamento de 1 a 12 vezes funciona igual, desde que a conta tenha taxa configurada para o número de parcelas.
Esses números só valem com a chave de teste. As regras de 3D Secure e de antifraude da conta continuam valendo no Modo Teste: se a conta exige 3DS ou tem antifraude ligado, a recusa pode vir dessas etapas, com
reason começando em 3ds_ ou igual a antifraud_denied. Na cobrança com cartão salvo, a regra vale para o número guardado; como esse cartão costuma ser real, a cobrança de teste sai aprovada.Onde obter as chaves
As chaves ficam no painel da Finvia, em Configurações > Chave de API. A página se chama Chaves de API e tem duas abas: Produção e Teste. Não existe rota de API para a conta ler as próprias chaves.Em validação (V-56): os rótulos do painel citados nesta seção estão sendo conferidos na versão em produção. Se algum nome estiver diferente, procure a página de chaves em Configurações.
- Chave de produção
- Chave de teste
1
Abra a aba Produção
Em Configurações > Chave de API, abra a aba Produção. O par
sk_/pk_ de produção é criado automaticamente no cadastro ou na aprovação da conta e pertence ao proprietário dela. Se ele ainda não existir, a aba mostra o botão Gerar chave de produção.2
Revele a chave
Clique em Revelar chave. Um código de verificação é enviado ao seu e-mail e vale 5 minutos.
3
Copie o par
Depois de informar o código, o painel mostra juntas a Chave secreta (
sk_) e a Chave pública (pk_). Guarde a secreta em um cofre de segredos ou na variável de ambiente do servidor.sk_ e a pk_ formam um par. Se a chave secreta for trocada (a troca é feita pelo suporte), a chave pública também muda e precisa ser atualizada no front-end. Cada par pertence a uma única conta.
Formato de uma chave:
Permissões da chave
A chave age com as permissões do usuário que a gerou. Quem apenas revela a chave no painel não muda essas permissões. A chave de produção criada automaticamente pertence ao proprietário da conta e funciona em todas as rotas. Uma chave gerada por outro usuário fica limitada ao perfil dele, e isso vale também para a chave de teste.
Quando falta permissão, a resposta é:
Como se autenticar
A API usa HTTP Basic Auth. A chave secreta vai no lugar do usuário e a senha fica vazia. Passo a passo:1
Pegue a chave
sk_abc1232
Acrescente dois pontos no final
sk_abc123: (os dois pontos separam usuário e senha; como a senha é vazia, não há nada depois deles)3
Converta para Base64
c2tfYWJjMTIzOg==4
Envie no cabeçalho de toda requisição
Authorization: Basic c2tfYWJjMTIzOg==Teste a conexão
A forma mais simples de validar a chave é listar os meios de pagamento disponíveis para a sua conta. Resposta200 significa que a autenticação está correta.
Boas práticas de segurança
- Guarde a chave em variável de ambiente ou cofre de segredos, nunca no código-fonte.
- Use chaves diferentes para cada ambiente e nunca reaproveite a chave de produção em testes.
- Use sempre HTTPS.
- Se houver suspeita de vazamento da chave secreta, peça a troca ao suporte imediatamente. Depois da troca, atualize a
sk_no servidor e apk_no front-end, porque as duas mudam juntas. - Acompanhe os logs de acesso da sua aplicação para identificar uso fora do padrão.
Erros comuns
Perguntas frequentes
Preciso mudar a URL para sair do sandbox?
Preciso mudar a URL para sair do sandbox?
Não. A URL é a mesma. Para ir para produção, troque a chave de teste (
sk_test_) pela chave de produção (sk_).Perdi a chave. Consigo ver de novo?
Perdi a chave. Consigo ver de novo?
Sim. Em Configurações > Chave de API, clique em Revelar chave e informe o código enviado ao seu e-mail.
Posso testar assinaturas com a chave de teste?
Posso testar assinaturas com a chave de teste?
As assinaturas cobram de verdade mesmo com a chave de teste, e o cadastro de cartão registra o cartão de verdade (sem cobrar). Use um cartão real com valor baixo e cancele a assinatura no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas.
Uma cobrança com cartão salvo cobra de verdade no Modo Teste?
Uma cobrança com cartão salvo cobra de verdade no Modo Teste?
Não. Com a chave de teste, toda cobrança em
POST /v1/charges é simulada, inclusive com cardTokenId. O cvv continua obrigatório. Lembre que o mesmo cardTokenId cobra de verdade se for usado com a chave de produção.Quem da minha empresa deve gerar a chave?
Quem da minha empresa deve gerar a chave?
Um usuário com perfil Owner ou Manager. Uma chave gerada por Desenvolvedor não cria cobranças nem assinaturas e não acessa saldo nem saques.
Os webhooks de teste vão para endpoints separados?
Os webhooks de teste vão para endpoints separados?
Não. A lista de endpoints de webhook é uma só e recebe eventos de teste e de produção. Nos eventos de cobrança de teste,
livemode vem false e data.is_test vem true. Veja Sua primeira cobrança.Veja também
Sua primeira cobrança
Crie e acompanhe uma cobrança Pix no sandbox.
Paginação, ordenação e idempotência
Como listar dados e evitar cobranças duplicadas.
Erros e como tratar
Códigos HTTP e respostas de erro da API.
Roteiro de homologação
O que testar antes de ir para produção.

