Skip to main content
Toda requisição à API da Finvia precisa de uma chave secreta. É com ela que a API sabe qual empresa está chamando, quais permissões ela tem e se a operação é de teste ou de produção.
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

A chave secreta (sk_) nunca pode aparecer em código que roda no navegador, no aplicativo do cliente ou em repositórios. A chave pública (pk_) foi feita para o front-end e só é aceita nas rotas que pedem por ela.

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.
A chave pública de teste (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.
Toda cobrança via POST /v1/charges é simulada no Modo Teste, inclusive com cartão salvo (cardTokenId) e Apple Pay. Duas operações, porém, não têm modo de teste:
  • Cadastro de cartão (POST /v1/cards): registra o cartão de verdade no cofre e na adquirente, mas não cobra nada.
  • Assinaturas (POST /v1/subscriptions): as cobranças da assinatura são feitas de verdade, inclusive a validação de R$ 1,00 (com estorno em seguida) dos planos com trial grátis.
O cofre de cartões é o mesmo para teste e produção. Um cardTokenId criado durante os testes também funciona com a chave de produção, e aí a mesma chamada cobra de verdade.
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 responde 400). 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.
O desenho abaixo resume o caminho da conta aprovada até as chaves de teste e de produção. Os nomes do painel usados no desenho seguem a mesma ressalva de validação (V-56) do quadro acima.
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.
No painel, os perfis Owner, Manager e Desenvolvedor podem gerar e revelar chaves. O perfil Visualizador só vê a página. Para a integração, gere as chaves, inclusive a de teste, com um usuário Owner ou Manager: uma chave gerada por Desenvolvedor fica com as restrições desse perfil (veja Permissões da chave). A 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 é:
Para o desenvolvedor: gere a chave de teste com um usuário Owner ou Manager. Se ela for gerada por um usuário Desenvolvedor, os testes de cobrança falham com 403. Quando a integração consulta dados mas recebe 403 ao criar cobranças, confira primeiro o perfil de quem gerou a chave.

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_abc123
2

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==
Para o desenvolvedor: para conferir se o Base64 foi montado certo, decodifique o valor e veja se ele termina com :. Se os dois pontos estiverem faltando, a API responde 401.

Teste a conexão

A forma mais simples de validar a chave é listar os meios de pagamento disponíveis para a sua conta. Resposta 200 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 a pk_ 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

Não. A URL é a mesma. Para ir para produção, troque a chave de teste (sk_test_) pela chave de produção (sk_).
Sim. Em Configurações > Chave de API, clique em Revelar chave e informe o código enviado ao seu e-mail.
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.
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.
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.
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.