sk_) fica só no seu servidor. O front-end usa a chave pública (pk_) apenas no Apple Pay e no 3D Secure, e o saque sai sempre por Pix para a chave CNPJ da conta.
Antes de começar
Para integrar, sua empresa precisa de:- Conta ativa na Finvia e acesso ao painel.
- A chave de produção, criada automaticamente para o proprietário da conta, ou uma chave gerada por um usuário com perfil Owner ou Manager (veja Permissões da chave).
- Um servidor que receba requisições HTTPS da internet, para os webhooks. No desenvolvimento, uma ferramenta como o ngrok expõe sua máquina local.
- Para o marketplace: o módulo Connect habilitado pela Finvia na sua conta.
O que dá para fazer com a API
Para o negócio: a API é a mesma para todos os modelos de venda. Uma loja virtual usa Pix, cartão e webhooks. Um SaaS soma planos e assinaturas. Um marketplace acrescenta o Connect, que cria uma subconta para cada vendedor e separa a parte de cada um em toda venda. Os casos de uso mostram essas combinações com exemplos completos.
Para quem é esta documentação
Cada página foi escrita para ser lida por duas pessoas ao mesmo tempo.
Ao longo das páginas, dois quadros ajudam a separar os assuntos:
Para o negócio: decisões, regras comerciais e impactos para a operação.
Como a documentação está organizada
O portal tem cinco abas. Cada uma responde a uma pergunta diferente.Caminho recomendado de leitura
- Desenvolvedor
- Analista de negócios
1
Configure as credenciais
Gere a chave de teste e faça a primeira chamada autenticada em Credenciais e ambientes.
2
Crie a primeira cobrança
Siga o tutorial Sua primeira cobrança: Pix e cartão no sandbox, com recebimento de webhook.
3
Entenda os contratos gerais
Leia Paginação, ordenação e idempotência e Erros e como tratar. Eles valem para todas as rotas.
4
Implemente os recursos do seu modelo
Abra o caso de uso mais próximo do seu negócio e siga os guias que ele indica.
5
Consulte a referência e os anexos
Use a Referência da API para os campos exatos e os anexos de status, eventos e códigos de erro durante o desenvolvimento.
6
Homologue
Execute os cenários do roteiro de homologação, envie as evidências ao suporte da Finvia e confira o checklist de go-live.
Primeiros passos
Credenciais e ambientes
Gere suas chaves e faça a primeira chamada autenticada.
Sua primeira cobrança
Pix e cartão no sandbox, da criação ao webhook.
Paginação, ordenação e idempotência
Como listar dados e evitar cobranças duplicadas.
Erros e como tratar
Formatos de erro, códigos HTTP e boas práticas de retentativa.
Casos de uso
E-commerce
Loja virtual com Pix, cartão parcelado e produtos físicos.
SaaS e assinaturas
Planos recorrentes, período de teste e cancelamento.
Marketplace e PSP
Subcontas por vendedor, split e saques com o Connect.
Infoprodutos
Cursos e produtos digitais, com divisão de valores entre parceiros.
ERP e software de gestão
Pagamentos embutidos no sistema que seus clientes já usam.
Cobrança por mensagem
Cobranças enviadas por mensagem, e-mail ou WhatsApp.
White label e agências
Agências e plataformas que integram pagamentos para vários clientes.
Educação e mensalidades
Mensalidades escolares e cursos com cobrança recorrente.
Convenções que valem para toda a API
Veja também
Conceitos essenciais
Merchant, cobrança, webhook, split e outros termos explicados.
Mapa da API
Todas as rotas em uma página, agrupadas por assunto.
Glossário
Termos de pagamentos e da API em ordem alfabética.
Roteiro de homologação
O que testar antes de ir para produção.

