Skip to main content
Cada caso de uso desta seção parte de uma empresa fictícia brasileira, com números plausíveis. Ele mostra como a empresa monta a operação de pagamentos com a API da Finvia: quais rotas chama, em que ordem, o que acontece em cada etapa, quais regras limitam o desenho e o que testar antes de ir para produção. Os casos foram escritos para dois leitores ao mesmo tempo. O analista de negócios encontra o cenário, o que o recurso faz e as regras que afetam o produto. O desenvolvedor encontra a arquitetura, as requisições válidas contra o contrato da API e os cenários de homologação.
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:
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).
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 cofre de cartões é o mesmo para teste e produção. Um cardTokenId criado na homologação também funciona com a chave de produção, e aí a mesma chamada cobra de verdade.
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:
  1. O cenário: a empresa fictícia, o que ela vende e o problema de pagamento.
  2. O que a Finvia resolve: o que os recursos fazem nesse contexto.
  3. Arquitetura da solução: tabela com necessidade, recurso e rota.
  4. Passo a passo: requisições reais, válidas contra o contrato.
  5. Regras e cuidados: o que causa erro, cobrança indevida ou perda de dinheiro.
  6. Variações do caso: alternativas comuns do mesmo modelo.
  7. 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.