Para o negócio: os casos mostram o que a API faz hoje. Nenhum deles promete resultado de vendas, de aprovação ou de custo. Os detalhes de cada recurso, com todas as regras e erros, ficam nos guias indicados em cada página.
Os oito casos
E-commerce
Loja virtual de produtos físicos: Pix com validade curta, cartão parcelado, Apple Pay, 3DS, entrega, estorno e recompra.
SaaS por assinatura
Software com plano mensal: trial, cartão salvo, renovação automática, retentativas e controle de acesso por webhook.
Marketplace e PSP
Plataforma com vários vendedores: subcontas, KYC, split com comissão sobre o bruto e saques dos vendedores.
Infoprodutos
Cursos e produtos digitais: Pix e cartão parcelado, liberação de acesso só após confirmação, reembolso e coprodução.
ERP e software de gestão
Sistema que cobra em nome dos próprios clientes: cada cliente vira subconta, com conciliação e onboarding em massa.
Cobrança por mensagem
Venda pelo WhatsApp, Instagram ou telefone: Pix gerado pela API e enviado por mensagem, com confirmação por webhook.
Agências e white label
Agência que monta um gateway próprio para os clientes: conta master, subcontas, chaves por cliente e repasse de eventos.
Educação e mensalidades
Escolas e cursos: mensalidade por assinatura, Pix avulso para matrícula e material, inadimplência e cancelamento.
Qual recurso cada caso usa
A Finvia recebe por cartão de crédito (digitado, salvo no cofre ou pelo Apple Pay) e por Pix. Todos os casos usam só esses dois meios. Na tabela, Sim indica que o recurso faz parte do fluxo principal do caso, Opcional indica que aparece em uma variação ou melhora o fluxo, e Não indica que o caso não depende dele.
Onde cada recurso está documentado:
Como escolher
Comece pela pergunta que define a arquitetura: o dinheiro da venda é só seu, ou é de outras empresas que vendem pela sua plataforma? O desenho abaixo resume essa escolha: duas perguntas levam ao caso de uso mais próximo do seu negócio e aos blocos da API que ele usa. Todos os casos usam webhooks para saber quando o pagamento entrou. Os passos abaixo detalham cada caminho.1
O dinheiro é só da sua empresa
Você é o merchant e cobra os seus próprios clientes. Escolha pelo modelo de cobrança:
- Venda avulsa com o cliente no site ou no app: E-commerce ou Infoprodutos.
- Cobrança automática a cada ciclo: SaaS por assinatura ou Educação e mensalidades.
- Venda sem site, fechada por conversa: Cobrança por mensagem.
2
O dinheiro é de outras empresas
Cada empresa que vende pela sua plataforma precisa da própria conta, com cadastro e KYC. Na Finvia, isso é feito com o módulo Connect: a sua empresa vira a conta master (MerchantMaster) e cada vendedor vira uma subconta (SubMerchant).
- Vários vendedores em uma vitrine única: Marketplace e PSP.
- Software que já atende empresas e passa a cobrar em nome delas: ERP e software de gestão.
- Agência que monta a operação de pagamentos para vários clientes: Agências e white label.
3
Combine quando precisar
Os casos se combinam. Uma escola com várias unidades pode usar assinaturas em cada subconta. Um marketplace de cursos pode usar a lógica de liberação de acesso dos infoprodutos. Use a tabela acima para ver quais recursos entram na sua combinação.
Regras que valem para todos os casos
Os exemplos usam a URL base da API,
https://api-global.fastpaybrasil.com. O painel fica em https://app.finvia.com.br, e as chaves estão em Configurações > Chave de API.
Como testar no Modo Teste
Com a chave de teste (sk_test_), toda cobrança criada em POST /v1/charges é simulada e não movimenta dinheiro. Os outros recursos têm regras próprias:
O detalhe está em Credenciais e ambientes.
Como cada caso está organizado
Todas as páginas seguem a mesma ordem, para facilitar a comparação:- O cenário: a empresa fictícia, o que ela vende e o problema de pagamento.
- O que a Finvia resolve: o que os recursos fazem nesse contexto.
- Arquitetura da solução: tabela com necessidade, recurso e rota.
- Passo a passo: requisições reais, válidas contra o contrato.
- Regras e cuidados: o que causa erro, cobrança indevida ou perda de dinheiro.
- Variações do caso: alternativas comuns do mesmo modelo.
- Checklist de implementação e Como homologar, com os códigos de cenário do roteiro de homologação.
Veja também
Conceitos
Cobrança, cliente, subconta, split, webhook e postback.
Sua primeira cobrança
Uma cobrança Pix completa em poucos minutos.
Roteiro de homologação
Cenários obrigatórios por funcionalidade.
Checklist de go-live
O que conferir antes de virar para produção.

