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

# Conceitos essenciais

> Os termos e objetos que aparecem em toda a API, explicados para quem programa e para quem decide.

Esta página explica as peças que formam a API da Finvia: quem vende, quem paga, o que é cobrado, como o dinheiro se move e como o seu sistema fica sabendo de cada mudança. Cada conceito traz uma explicação em linguagem de negócio e, quando ajuda, o nome técnico que aparece nos campos e nas rotas.

Para definições curtas em ordem alfabética, use o [Glossário](https://docs.fastpaybrasil.com/glossario.md).

O desenho abaixo mostra como os principais objetos da API se relacionam. Cada um deles é explicado nas seções seguintes.

```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
    M["Sua conta (merchant)<br/>no Connect, a conta master"]:::lojista
    SUB["Subcontas (Connect)<br/>um vendedor cada"]:::lojista
    CLI(["Cliente<br/>customer"]):::comprador
    PLAN["Plano<br/>preço e periodicidade"]:::neutro
    CARD["Cartão salvo<br/>id do cofre = cardTokenId"]:::neutro
    ASS["Assinatura<br/>cliente + plano + cartão"]:::neutro
    CHG["Cobrança (charge)<br/>items · paymentMethod"]:::finvia
    WH[["Webhooks<br/>charge.* · subscription.*"]]:::evento
    WAL["Carteira (wallet)<br/>saldo por moeda"]:::neutro
    PAY["Saque (payout)<br/>Pix para a chave CNPJ"]:::neutro
    M -->|"cria e gerencia"| SUB
    M -->|"cadastra"| CLI
    M -->|"cria"| PLAN
    CLI -->|"guarda no cofre"| CARD
    CLI --> ASS
    PLAN --> ASS
    CARD --> ASS
    M -->|"POST /v1/charges"| CHG
    CLI -->|"paga"| CHG
    CARD -.->|"recompra com CVV"| CHG
    ASS -->|"cobra a cada ciclo"| CHG
    CHG -.->|"split opcional"| SUB
    CHG -->|"cada mudança"| WH
    ASS -->|"cada mudança"| WH
    CHG -->|"valor liquidado"| WAL
    WAL -->|"sacar"| PAY
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

## Quem participa

### Merchant (lojista)

O **merchant** é a empresa cliente da Finvia que vende e recebe. É a sua empresa. Toda cobrança, cliente, cartão salvo e plano pertence a um merchant, e o merchant é identificado pela chave usada na requisição. Em respostas da API, o campo `merchantId` indica a qual conta um objeto pertence.

### Conta master e subconta (Connect)

O **Connect** é o módulo da Finvia para marketplaces e plataformas que atendem vários vendedores. Ele é habilitado pela Finvia na sua conta e cria uma hierarquia de duas camadas:

| Papel | Nome técnico | O que faz |
| - | - | - |
| **Conta master** | MerchantMaster | A plataforma. Cria e gerencia as subcontas, define regras de split e acompanha os saques |
| **Subconta** | SubMerchant | Cada vendedor da plataforma. Tem CNPJ, dados bancários, chaves de API e saldo próprios |

Na criação, a subconta recebe uma **cópia das taxas e configurações** vigentes da conta master. Depois disso, as taxas da subconta são independentes: alterar as taxas da master não muda as das subcontas já criadas. Antes de vender, ela passa por análise cadastral (KYC, a verificação de identidade da empresa e dos sócios) e só opera depois de aprovada, com status `active`.

> [!NOTE]
>
> **Para o negócio:** com o Connect, cada venda fica registrada na conta do vendedor que vendeu, e a comissão da plataforma é separada automaticamente pelo split. Isso dá rastreabilidade por vendedor e evita repasses manuais.

### Cliente (customer)

O **cliente** é quem paga: a pessoa ou empresa que compra do merchant. Na API, é o objeto `customer`. Há duas formas de informar o cliente em uma cobrança:

* **Cadastro prévio:** você cria o cliente com [`POST /v1/customers`](https://docs.fastpaybrasil.com/referencia/clientes/criar) (`name`, `email`, `documentId` e `documentType` obrigatórios) e depois envia só o `customer.id` na cobrança.
* **Cadastro junto com a cobrança:** você envia `name` e `email` (ou `phone`) dentro da cobrança, e a API cria ou localiza o cliente.

O cadastro prévio é o caminho natural quando o mesmo cliente volta a comprar, guarda cartão ou assina um plano. Depois de criado, o documento do cliente não pode ser alterado: [`PUT /v1/customers/{id}`](https://docs.fastpaybrasil.com/referencia/clientes/atualizar) aceita só `name`, `email` e `phoneNumber`.

## O que é cobrado

### Cobrança (charge)

A **cobrança** (charge) é o pedido de pagamento: quanto cobrar, de quem, pelo quê e por qual meio. É o objeto central da API, criado em [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar). Ela nasce com um `id` único, que é a chave para consultar, estornar e conciliar a cobrança com os webhooks.

Campos obrigatórios na criação: `amount`, `currency`, `customer`, `paymentMethod` e `items`.

O valor vai em reais: `"amount": 10` significa R\$ 10,00 e `"amount": 99.9` significa R\$ 99,90. O mínimo é `1`.

### Item

Cada cobrança traz a lista `items`, com o que está sendo vendido. Todos os campos do item são obrigatórios: `title`, `type`, `description`, `unit_price` e `quantity`.

O `type` do item é `physical` (produto físico) ou `digital` (produto digital ou serviço). Se algum item da cobrança for `physical`, o endereço de entrega (`shippingAddress`) é obrigatório, com `postalCode`, `addressLine1`, `city`, `state` e `country` (`addressLine2` e `neighborhood` são opcionais). Sem ele, a API responde `400` e não cria a cobrança.

### Forma de pagamento

A Finvia aceita dois meios de pagamento: **cartão de crédito** (digitado, salvo no cofre ou via Apple Pay) e **Pix**. A forma de pagamento vai no objeto `paymentMethod` da cobrança e é identificada pelo campo `type`:

| Forma | `type` | Como o cliente paga | Quando o resultado sai |
| - | - | - | - |
| Pix | `pix` | Lê o QR Code ou cola o código no app do banco | Depois, quando o cliente paga (aviso por webhook) |
| Cartão de crédito | `credit_card` | Digita os dados do cartão | Na própria resposta da criação |
| Cartão salvo | `credit_card` com `cardTokenId` | Informa só o CVV | Na própria resposta da criação |
| Apple Pay | `credit_card` com `wallet` | Autoriza no iPhone, Mac ou Apple Watch | Na própria resposta da criação |

A rota [`GET /v1/payment-methods`](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar) lista os meios de pagamento habilitados para a sua conta.

### Status

O **status** diz em que ponto da vida a cobrança está. Ele muda ao longo do tempo, e o seu sistema acompanha essas mudanças pelos webhooks ou consultando a cobrança.

| Status | Significado resumido |
| - | - |
| `pending` | Aguardando pagamento |
| `paid` | Pago |
| `refused` | Recusado pelo processador |
| `failed` | Falha no processamento |
| `refunded` | Estornado |
| `in_analysis` | Em análise antifraude |
| `authentication_required` | Aguardando autenticação do comprador (3D Secure) |
| `pre_chargeback` | Alerta de contestação recebido antes do chargeback formal |
| `chargeback` | Chargeback formalizado |

A tabela completa, com o que fazer em cada status, está em [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md). O bloqueio de uma cobrança em disputa não é um status: a cobrança continua `paid` e passa a ter `isBlocked: true` (veja [Bloqueio](#bloqueio)).

> [!NOTE]
>
> **Para o negócio:** a regra mais segura para liberar um pedido, enviar um produto ou dar acesso a um curso é esperar o status `paid`. `pending` e `in_analysis` ainda não significam dinheiro recebido.

## Ciclo de vida de uma cobrança

### Cobrança Pix

**1. Seu sistema cria a cobrança**

Você chama `POST /v1/charges` com `paymentMethod.type` igual a `pix` e a validade do QR Code (`expirationInDays` ou `expirationInSeconds`, mínimo de 900 segundos, ou seja, 15 minutos).

**2. A API devolve o QR Code**

A resposta `201` traz `status` `pending` e, em `paymentDetails`, o código copia e cola (`copyPaste`) e a imagem do QR Code (`qrCodeBase64`). Seu checkout mostra essas informações ao cliente.

**3. A Finvia avisa que a cobrança foi criada**

Os webhooks `charge.created` e `charge.pending` chegam aos endpoints cadastrados no painel e à `postbackUrl` da cobrança, se informada.

**4. O cliente paga no app do banco**

O pagamento é feito fora do seu sistema, no aplicativo bancário do cliente.

**5. A Finvia confirma o pagamento**

O webhook `charge.paid` chega com `status` `paid` e a data em `paid_at`. A partir daí, você pode liberar o pedido. No sandbox, o Pix de teste vira `paid` sozinho, cerca de 5 segundos depois da criação.

**6. Pós-venda, se houver**

Se for preciso devolver o dinheiro, um [estorno](https://docs.fastpaybrasil.com/guias/estorno.md) leva a cobrança a `refunded` e dispara `charge.refunded`. Se o pagamento for contestado, a cobrança pode ser [bloqueada](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

### Cobrança com cartão de crédito

**1. Seu sistema cria a cobrança**

Você chama `POST /v1/charges` com `paymentMethod.type` igual a `credit_card`, os dados do cartão (ou o `cardTokenId` de um cartão salvo, ou o `wallet` do Apple Pay) e o número de parcelas (`installments`, até 12).

**2. Autenticação 3D Secure, quando aplicável**

Com o 3D Secure gerenciado (`threeDSMode` igual a `managed`), quando a política 3DS da conta dispara e o banco emissor pede verificação ou desafio, a cobrança nasce com `authentication_required` e traz a `authenticationUrl`, para onde o comprador é levado. A própria página dessa URL conduz a autenticação e retoma a cobrança, que só é processada depois disso. Na autenticação sem atrito, a resposta já traz o status final.

**3. A resposta traz o resultado**

Na resposta `201`, o `status` já indica aprovação (`paid`), recusa (`refused`) ou falha (`failed`). Em recusas, o campo `reason` explica o motivo, e o checkout pode oferecer outra forma de pagamento em seguida.

**4. A Finvia notifica o resultado**

O webhook `charge.paid` (aprovação), `charge.refused` (recusa) ou `charge.failed` (falha) chega aos endpoints cadastrados e à `postbackUrl`. A resposta síncrona continua sendo a fonte principal; o webhook é complementar.

**5. Pós-venda, se houver**

Estorno total (`refunded`), alerta de contestação (`pre_chargeback`) ou chargeback (`chargeback`), cada um com sua notificação.

## Como o seu sistema fica sabendo

### Webhook e postback

Um **webhook** é uma notificação que a Finvia envia ao seu servidor, por uma requisição HTTP POST com corpo em JSON, quando algo acontece. Assim você não precisa consultar a API o tempo todo para saber se uma cobrança foi paga.

Existem dois canais para eventos de cobrança, e eles se complementam:

| Canal | Onde é configurado | O que recebe |
| - | - | - |
| **Webhook** (endpoint cadastrado) | No painel, em **Configurações > Webhooks** da conta selecionada, ou pela API em [`POST /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint) | Eventos de todas as cobranças e assinaturas da conta (`charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked` e `subscription.*`) e, nas subcontas, os eventos de saque |
| **Postback** | No campo `postbackUrl` de cada cobrança | Os mesmos eventos de cobrança, só daquela cobrança, mais o `charge.updated` legado, que só existe neste canal |

O webhook de cobrança tem um envelope com `id` (identificador do evento), `event` (nome do evento), `livemode` (`false` em cobranças de teste) e `data` (a cobrança). Os mesmos endpoints recebem eventos de teste e de produção: separe-os por `livemode`. O `charge.updated` tem formato próprio, sem `id` e sem `livemode`. Detalhes em [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) e no [Catálogo de eventos](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md).

> [!WARNING]
>
> Os webhooks não trazem assinatura HMAC: antes de uma ação crítica, confirme o estado com [`GET /v1/charges/{id}`](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar) (veja [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#regras-de-negócio)). Use sempre HTTPS no seu endpoint.

## Depois da venda

### Estorno

O **estorno** devolve ao cliente o valor de uma cobrança paga. Na API ele é sempre **total**: estorno parcial não é suportado. Só cobranças com `status` `paid` podem ser estornadas (as demais recebem `404`), e cada cobrança aceita um único estorno (um segundo pedido recebe `422`). A rota é [`POST /v1/refunds`](https://docs.fastpaybrasil.com/referencia/cobrancas/estornar), com `chargeId` e `reason`. Funciona para Pix e cartão de crédito.

### Chargeback, pré-chargeback e MED

* **Chargeback** é a contestação de uma compra com cartão, aberta pelo banco emissor do cartão por meio da bandeira. A disputa chega à Finvia pela adquirente, e a decisão final é do emissor ou da bandeira. Se a contestação prevalece, o valor volta ao portador e a cobrança fica `chargeback`.
* **Pré-chargeback** é um alerta recebido antes de o chargeback ser formalizado. A cobrança vai para `pre_chargeback` e o evento `charge.pre_chargeback` é enviado. O campo `chargebackAlertRefunded` (no webhook, `chargeback_alert_refunded`) diz se o valor já foi devolvido ao portador (`true`) ou se a disputa segue aberta sem estorno (`false`).
* **MED** (Mecanismo Especial de Devolução) é o mecanismo do Pix, definido pelo Banco Central, que permite à instituição de quem pagou pedir a devolução de um Pix quando há fundada suspeita de fraude ou falha operacional. A contestação é analisada pela instituição de quem recebeu. Durante a análise, o valor fica bloqueado; se a contestação for aceita, ele é devolvido ao pagador. O MED existe só no Pix.

O MED é diferente do **bloqueio cautelar**, outra ferramenta do Pix: uma retenção preventiva e curta, feita pela instituição de quem recebeu quando suspeita de fraude. Na API da Finvia, os dois aparecem do mesmo jeito, como bloqueio da cobrança.

### Bloqueio

Quando há um MED, um chargeback em análise ou outra suspeita, a equipe Finvia pode **bloquear** uma cobrança `paid`. O bloqueio não chega automaticamente do banco: é aplicado pela Finvia. Na API, não existe status nem evento chamado MED. O que você vê é:

* a cobrança continua com `status` `paid` e passa a ter `isBlocked: true`, `blockedAt` e `blockedReason` (texto livre, que pode vir vazio);
* o evento `charge.blocked` vai aos endpoints e à `postbackUrl` da cobrança, e a `postbackUrl` recebe também o `charge.updated` legado;
* o valor já liquidado da venda sai do saldo disponível e vai para o saldo bloqueado;
* `GET /v1/charges?status=blocked` lista as cobranças bloqueadas.

A defesa não é feita pela API. O alerta de chargeback ou MED chega por e-mail à conta (no Connect, à conta master). Você responde a esse e-mail com as evidências da venda (comprovante de entrega, nota fiscal, conversa com o cliente), dentro do prazo indicado nele. Dúvidas, pelo suporte. Os desfechos possíveis:

| Desfecho | O que a API mostra |
| - | - |
| Bloqueio retirado | `isBlocked: false`. Hoje, a liberação não gera webhook: consulte a cobrança. Use `isBlocked`, porque `blockedAt` continua preenchido |
| Contestação aceita no Pix | Estorno: `status` `refunded` e evento `charge.refunded` |
| Chargeback perdido no cartão | `status` `chargeback`, informado pela adquirente. Chega à `postbackUrl` como `charge.updated` com `status: "chargeback"` e, quando o valor é revertido do saldo, também como `charge.refunded` |

Detalhes em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Cartões e recorrência

### Cartão salvo (cofre e token)

O **cofre de cartões** guarda o cartão do cliente de forma segura na Finvia. Ao registrar um cartão com [`POST /v1/cards`](https://docs.fastpaybrasil.com/referencia/cartoes/registrar), você recebe um `id` (o token do cartão) e passa a usar esse identificador no lugar do número. O cartão pertence ao merchant da chave que o registrou e não pode ser usado por outro merchant ou subconta.

Regras que mudam o desenho do produto:

* Para registrar, o cliente precisa ter **e-mail** e **CPF ou CNPJ**. Outros documentos, como passaporte, são recusados.
* Com o processador atual, o cartão já nasce `active`. Não há transação de teste nem etapa de ativação.
* Em uma cobrança avulsa com cartão salvo (`cardTokenId`), o **CVV do comprador é obrigatório toda vez**. Para cobrar sem o comprador presente, use assinaturas.
* O cofre é o mesmo para teste e produção: um `cardTokenId` criado com a chave de teste cobra de verdade se for usado com a chave de produção.

### Plano e assinatura

| Conceito | O que é | Exemplo |
| - | - | - |
| **Plano** | O modelo da cobrança recorrente: nome, preço, moeda, periodicidade e, opcionalmente, período de teste | "Plano Premium Mensal, R\$ 99,90 por mês, 14 dias grátis" |
| **Assinatura** | O vínculo de um cliente a um plano, com um cartão | "Maria Souza assina o Plano Premium desde 15/01" |

A periodicidade do plano (`recurrenceType`) pode ser `weekly`, `biweekly`, `monthly` ou `custom`. Editar um plano não altera assinaturas existentes: preço, moeda e periodicidade ficam congelados no momento da contratação. Uma assinatura aceita só alteração de `metadata`. Para trocar cartão ou plano, cancele e crie outra. Detalhes em [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

> [!NOTE]
>
> **Para o negócio:** cancelamentos em até 7 dias da criação da assinatura são tratados como arrependimento e estornam automaticamente todas as cobranças pagas. Depois disso, o cancelamento é regular: as cobranças param imediatamente, sem estorno, e a sua plataforma controla o acesso até o fim do período pago.

## Dinheiro em movimento

O desenho abaixo mostra o caminho do dinheiro, da cobrança paga até o saque na conta bancária.

```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
    PAID(["Cobrança paga<br/>status paid"]):::ok
    LIQ["Recebível liquidado<br/>Pix: no mesmo dia<br/>cartão: D+30, D+60..."]:::finvia
    SO["Saldo disponível<br/>do originador"]:::lojista
    SR["Saldo disponível<br/>do recebedor do split"]:::lojista
    SAQ["Saque pedido · pending<br/>valor bruto sai do<br/>saldo disponível"]:::alerta
    OK["approved<br/>Pix do valor líquido<br/>para a chave CNPJ"]:::ok
    REJ["rejected<br/>o valor volta ao<br/>saldo disponível"]:::erro
    PAID -->|"1. desconta a<br/>taxa transacional"| LIQ
    LIQ -->|"2. a cada parcela"| SO
    SO -->|"3. split: percentual<br/>sobre o valor líquido"| SR
    SO -->|"4. saque"| SAQ
    SR -->|"4. saque"| SAQ
    SAQ -->|"aprovado"| OK
    SAQ -->|"recusado"| REJ
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

O split só acontece entre contas do mesmo grupo Connect. As regras de cada etapa estão nas seções abaixo.

### Split (divisão de valores)

O **split** divide o valor de uma cobrança entre contas do mesmo [grupo Connect](https://docs.fastpaybrasil.com/glossario.md) (a conta master e as subcontas dela). Você informa no campo `split` da cobrança quais contas recebem e qual percentual de cada uma. Sem `split`, vale a regra de split padrão da conta para aquela moeda e método, se houver (em subconta sem regra própria, vale a da master).

* A soma dos percentuais não pode passar de 100%. O que sobra fica com o [originador](https://docs.fastpaybrasil.com/glossario.md), a conta que criou a cobrança.
* Todas as contas precisam pertencer ao mesmo grupo Connect.
* Por padrão, o percentual é aplicado sobre o **[valor líquido](https://docs.fastpaybrasil.com/glossario.md)**, depois da taxa transacional. O uso do valor bruto é configurado pela Finvia, sob consulta.
* O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do originador é liquidado: no cartão, cada parcela em D+30, D+60 e assim por diante; no Pix, no mesmo dia, logo após a confirmação do pagamento. O repasse sai do saldo disponível do originador e entra no saldo disponível do recebedor.
* As cobranças recorrentes de assinatura não recebem split.

> [!NOTE]
>
> **Para o negócio:** se a sua plataforma cobra uma comissão de 10% sobre o valor bruto da venda, o percentual de split precisa ser maior que 10% para entregar o mesmo valor, porque a base é o líquido. O cálculo está em [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

### Saldo e carteira (wallet)

A **carteira** (wallet) mostra o saldo da conta por moeda, em três partes: `available` (disponível), `pending` (a liberar) e `reserved` (reservado). O campo `isWithdrawalEnabled` diz se saques estão habilitados naquela moeda. A rota é [`GET /v1/wallets`](https://docs.fastpaybrasil.com/referencia/carteiras/listar).

### Saque (payout)

O **saque** (payout) transfere saldo para fora da Finvia, sempre por **Pix** para a chave CNPJ da conta que saca (o mesmo CNPJ do cadastro). Antes de sacar, cadastre esse CNPJ como chave Pix em uma conta bancária da empresa. As rotas de saque usam Basic com a chave secreta, e não existe saque no Modo Teste: com a chave de teste, a criação responde `403`.

| Saque | Rota | Como funciona |
| - | - | - |
| Da própria conta | [`POST /v1/payout-requests`](https://docs.fastpaybrasil.com/referencia/saques/criar) | Corpo com `merchantId`, `amount` em reais, `currency` `BRL` e `externalAccountDetails` `{ "type": "pix" }`. Responde `201` sem corpo; o `id` se obtém na listagem. Não gera webhook |
| De subconta (Connect) | [`POST /v1/submerchants/{merchantId}/payout-requests`](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque) | Corpo com `amount` em reais (mínimo R\$ 1,00). Responde com o `id`. Sempre passa por aprovação manual e gera os webhooks `payout.approved` e `payout.rejected` |

A taxa de saque é descontada do valor (`netAmount` é o líquido). Os status são:

| Status | Significado |
| - | - |
| `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão |
| `approved` | Aprovado (pela operação ou por aprovação automática) e enviado para pagamento |
| `rejected` | Recusado. O valor volta ao saldo disponível, e o motivo fica em `rejectionReason` |

O acompanhamento é pela listagem [`GET /v1/payout-requests`](https://docs.fastpaybrasil.com/referencia/saques/listar).

## Ambientes e chaves

A Finvia usa o mesmo endereço para testes e produção: `https://api-global.fastpaybrasil.com`. O ambiente é definido pela chave.

| Chave | Prefixo | Uso |
| - | - | - |
| Chave secreta de produção | `sk_` | No servidor, para operações reais |
| Chave secreta de teste | `sk_test_` | No servidor, no sandbox |
| Chave pública | `pk_` (`pk_test_` em teste) | No navegador, só nas rotas que pedem por ela (Apple Pay e 3D Secure) |

A chave age com as permissões do usuário que a gerou. No Modo Teste, toda cobrança via `POST /v1/charges` é simulada, inclusive com cartão salvo. O cadastro de cartão registra o cartão de verdade (sem cobrar) e as **assinaturas cobram de verdade** mesmo com a chave de teste. Como gerar e usar as chaves: [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).

## Veja também

> [card] [Glossário](https://docs.fastpaybrasil.com/glossario.md)
>
> Definições curtas de termos de pagamentos e da API.

> [card] [Mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md)
>
> Todas as rotas em uma página.

> [card] [Sua primeira cobrança](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md)
>
> Coloque os conceitos em prática no sandbox.

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> Cada status, quando acontece e o que fazer.


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