> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Casos de uso

> Oito modelos de negócio montados sobre a API da Finvia, com os recursos que cada um usa e como escolher o seu ponto de partida.

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.

> [!NOTE]
>
> **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

> [card] [E-commerce](https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md)
>
> Loja virtual de produtos físicos: Pix com validade curta, cartão parcelado, Apple Pay, 3DS, entrega, estorno e recompra.

> [card] [SaaS por assinatura](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)
>
> Software com plano mensal: trial, cartão salvo, renovação automática, retentativas e controle de acesso por webhook.

> [card] [Marketplace e PSP](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)
>
> Plataforma com vários vendedores: subcontas, KYC, split com comissão sobre o bruto e saques dos vendedores.

> [card] [Infoprodutos](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md)
>
> Cursos e produtos digitais: Pix e cartão parcelado, liberação de acesso só após confirmação, reembolso e coprodução.

> [card] [ERP e software de gestão](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md)
>
> Sistema que cobra em nome dos próprios clientes: cada cliente vira subconta, com conciliação e onboarding em massa.

> [card] [Cobrança por mensagem](https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md)
>
> Venda pelo WhatsApp, Instagram ou telefone: Pix gerado pela API e enviado por mensagem, com confirmação por webhook.

> [card] [Agências e white label](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md)
>
> Agência que monta um gateway próprio para os clientes: conta master, subcontas, chaves por cliente e repasse de eventos.

> [card] [Educação e mensalidades](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md)
>
> 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.

| Recurso | E-commerce | SaaS | Marketplace e PSP | Infoprodutos | ERP | Cobrança por mensagem | White label | Educação |
| - | - | - | - | - | - | - | - | - |
| Cobrança Pix | Sim | Opcional | Sim | Sim | Sim | Sim | Sim | Sim |
| Cartão de crédito | Sim | Opcional | Sim | Sim | Sim | Opcional | Sim | Sim |
| Cartão salvo | Sim | Sim | Opcional | Opcional | Opcional | Não | Opcional | Sim |
| Apple Pay | Sim | Não | Opcional | Opcional | Não | Não | Opcional | Não |
| 3D Secure | Sim | Não | Opcional | Opcional | Não | Não | Opcional | Não |
| Assinaturas | Não | Sim | Não | Opcional | Opcional | Não | Opcional | Sim |
| Connect e split | Não | Não | Sim | Opcional | Sim | Não | Sim | Opcional |
| Saques | Não | Não | Sim | Opcional | Sim | Não | Sim | Não |
| Webhooks | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim |

Onde cada recurso está documentado:

| Recurso | Guia | Rota principal |
| - | - | - |
| Cobrança Pix | [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) | `POST /v1/charges` com `paymentMethod.type` `pix` |
| Cartão de crédito | [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) | `POST /v1/charges` com `paymentMethod.type` `credit_card` |
| Cartão salvo | [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) | `POST /v1/cards` e `POST /v1/charges` com `cardTokenId` |
| Apple Pay | [Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) | `POST /v1/charges` com `paymentMethod.wallet` |
| 3D Secure | [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md) | `POST /v1/charges` com `threeDSMode` ou `threeDS` |
| Assinaturas | [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) | `POST /v1/subscription-plans` e `POST /v1/subscriptions` |
| Connect e split | [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md) | `POST /v1/submerchants` e campo `split` em `POST /v1/charges` |
| Saques de subcontas | [Saques de subcontas](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) | `POST /v1/submerchants/{merchantId}/payout-requests` |
| Saque da própria conta | [Saldos e saques](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md) | `POST /v1/payout-requests` |
| Webhooks | [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) | Endpoints cadastrados no painel ou em `POST /v1/webhook-endpoints`, e `postbackUrl` da cobrança |

## 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.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%

flowchart TB
    INI(["Seu negócio vende<br/>pela API da Finvia"]):::neutro
    Q1{"De quem é o<br/>dinheiro da venda?"}:::decisao
    Q2{"Como você<br/>cobra?"}:::decisao
    A["<b>E-commerce</b><br/><b>Infoprodutos</b><br/>Pix, cartão, Apple Pay"]:::neutro
    B["<b>SaaS</b> e <b>Educação</b><br/>assinatura no cartão<br/>e Pix avulso"]:::neutro
    C["<b>Cobrança por mensagem</b><br/>Pix enviado<br/>na conversa"]:::neutro
    CON["<b>Connect</b><br/>você é a conta master<br/>e cada empresa, subconta"]:::finvia
    Q3{"Quem são<br/>essas empresas?"}:::decisao
    D["<b>Marketplace e PSP</b><br/>KYC, split e saques<br/>dos vendedores"]:::neutro
    E["<b>ERP e gestão</b><br/>subconta por cliente<br/>e baixa por webhook"]:::neutro
    F["<b>White label</b><br/>chaves por cliente<br/>e repasse de eventos"]:::neutro
    INI --> Q1
    Q1 -->|"só da sua empresa"| Q2
    Q1 -->|"de outras empresas"| CON
    Q2 --->|"venda avulsa<br/>no site ou app"| A
    Q2 --->|"automática<br/>a cada ciclo"| B
    Q2 --->|"fechada<br/>na conversa"| C
    CON --> Q3
    Q3 -->|"vendedores de<br/>uma vitrine"| D
    Q3 -->|"clientes do<br/>seu software"| E
    Q3 -->|"clientes da<br/>sua agência"| F
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

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](https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md) ou [Infoprodutos](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md).
* Cobrança automática a cada ciclo: [SaaS por assinatura](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md) ou [Educação e mensalidades](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md).
* Venda sem site, fechada por conversa: [Cobrança por mensagem](https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md).

**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](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md).
* Software que já atende empresas e passa a cobrar em nome delas: [ERP e software de gestão](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md).
* Agência que monta a operação de pagamentos para vários clientes: [Agências e white label](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md).

**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

| Regra | O que significa |
| - | - |
| Valores em reais | `"amount": 10` é R\$ 10,00. Enviar `1000` pensando em R\$ 10,00 gera uma cobrança de R\$ 1.000,00 |
| Endereço de entrega para produto físico | Se algum item for `physical`, `shippingAddress` é obrigatório. Sem ele, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`. No endereço, `postalCode`, `addressLine1`, `city`, `state` e `country` (três letras, como `BRA`) são obrigatórios; `addressLine2` e `neighborhood` são opcionais |
| Sem `Idempotency-Key` | Cada `POST /v1/charges` cria uma cobrança nova. Depois de um timeout, não reenvie de imediato: recupere a cobrança pelo webhook `charge.created` ou pela listagem, como em [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md) |
| `metadata` em camelCase | Os exemplos desta seção usam chaves em camelCase ou de uma palavra só, que voltam iguais em todos os canais. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata) |
| Webhooks sem assinatura HMAC | Confirme o estado real na API (`GET /v1/charges/{id}`) antes de liberar produto, acesso ou dinheiro |
| Teste e produção no mesmo endpoint | Os endpoints de webhook recebem eventos de teste e de produção. Nas cobranças, separe pelo campo `livemode` (`false` no teste) |
| Permissão da chave | A chave age com o perfil do usuário que a gerou. O perfil Desenvolvedor recebe `403` ao criar cobrança, nas rotas de assinatura, no saldo e nos saques. Gere a chave com um usuário Owner ou Manager |

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:

| Recurso | Como se comporta com a chave de teste |
| - | - |
| Pix | A cobrança nasce `pending` com um QR Code fictício e passa sozinha para `paid` cerca de 5 segundos depois. Não tente pagar o código no app do banco. Não há como simular expiração |
| Cartão digitado | O resultado depende do número: `4444333322221111` aprova, `4444333322221112` recusa (`card_declined`), um número terminado em `2222` fica `pending` e qualquer outro número aprova. Envie o número só com dígitos |
| Cartão salvo (`cardTokenId`) | A cobrança é simulada. O cadastro do cartão em `POST /v1/cards` é real, mas não cobra nada |
| Assinaturas | São reais: as cobranças acontecem de verdade, inclusive a validação de R\$ 1,00 do trial grátis |
| Saques | Não existem no Modo Teste. A criação responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` |
| Webhooks | As cobranças de teste chegam com `livemode: false`. O reenvio de webhook de teste dispara um evento novo com o status escolhido e não altera a cobrança |

> [!WARNING]
>
> 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](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).

## 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](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Veja também

> [card] [Conceitos](https://docs.fastpaybrasil.com/conceitos.md)
>
> Cobrança, cliente, subconta, split, webhook e postback.

> [card] [Sua primeira cobrança](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md)
>
> Uma cobrança Pix completa em poucos minutos.

> [card] [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenários obrigatórios por funcionalidade.

> [card] [Checklist de go-live](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md)
>
> O que conferir antes de virar para produção.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.