Skip to main content
A API da Finvia conecta o sistema da sua empresa à operação de pagamentos. Com ela você gera cobranças Pix e de cartão de crédito, guarda cartões para recompra, cobra assinaturas automaticamente, divide o valor de uma venda entre várias contas, solicita saques por Pix da própria conta e das subcontas e acompanha cada mudança por notificações enviadas ao seu servidor. Os meios de pagamento são dois: cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix. Tudo acontece por requisições HTTPS com corpo em JSON, autenticadas com a chave secreta da sua conta. O mesmo endereço atende o ambiente de testes (sandbox) e o de produção: o que define o ambiente é a chave usada. O desenho abaixo mostra quem conversa com quem em uma integração típica, do pagamento do comprador ao aviso que chega ao seu servidor. A chave secreta (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.
Para o desenvolvedor: detalhes de implementação, armadilhas de código e formas de depurar.

Como a documentação está organizada

O portal tem cinco abas. Cada uma responde a uma pergunta diferente.

Caminho recomendado de leitura

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.