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

# Agências e plataformas white label

> Agência ou plataforma que monta um gateway próprio sobre a Finvia: conta master, uma subconta por cliente, chaves por subconta, remuneração por split e repasse de webhooks aos clientes.

Agências digitais e plataformas de tecnologia muitas vezes querem oferecer pagamentos aos clientes com a própria marca: o cliente da agência integra uma vez, vê a marca da agência e não precisa negociar diretamente com um gateway. Esta página mostra como montar essa camada sobre a API da Finvia, com uma subconta para cada cliente, a remuneração da agência separada em cada venda e os avisos de pagamento repassados a cada cliente.

> [!TIP]
>
> Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](https://docs.fastpaybrasil.com/integrar-com-ia.md).

Implementar este caso com um assistente de IA

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/saques.md](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/split.md](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
* [https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar neste projeto o fluxo descrito na página "Agências e plataformas white label" ([https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md)). Resumo do caso: Agência ou plataforma que monta um gateway próprio sobre a Finvia: conta master, uma subconta por cliente, chaves por subconta, remuneração por split e repasse de webhooks aos clientes.

Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

## O cenário

A **Órbita Digital** é uma agência de Florianópolis que cria e mantém lojas virtuais e sistemas de agendamento para **60 clientes**: lojas de moda, restaurantes, clínicas de estética e escolas de idiomas. A Órbita quer lançar o **Órbita Pay**, uma camada de pagamentos própria:

* o sistema de cada cliente fala só com a API do Órbita Pay;
* o dinheiro de cada venda entra na conta do cliente;
* a Órbita recebe **1,5% do [valor bruto](https://docs.fastpaybrasil.com/glossario.md)** de cada venda;
* cada cliente recebe os avisos de pagamento no sistema dele;
* a Órbita vê as taxas de cada cliente para montar a proposta comercial.

## O que a Finvia resolve

> [!NOTE]
>
> **Para o negócio:** com o Connect, a Órbita vira a conta master (MerchantMaster) e cada cliente vira uma subconta (SubMerchant), com cadastro, análise de documentos, chaves de API e saldo próprios. O backend do Órbita Pay cria as cobranças com a chave da subconta do cliente, então o dinheiro entra no saldo do cliente. O campo `split` separa a remuneração da Órbita em cada venda. A Órbita recebe os eventos de cobrança e repassa a cada cliente. A rota de taxas mostra as taxas cadastradas de cada subconta.

## Arquitetura da solução

| Necessidade | Recurso | Rota ou guia |
| - | - | - |
| Habilitar o modelo | Módulo Connect | Contato com o time Finvia |
| Conta de cada cliente | Subconta com KYC | `POST /v1/submerchants`, `POST /v1/submerchants/{merchantId}/document` · [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md) |
| Chaves por cliente | Chaves da subconta | `GET /v1/submerchants/{merchantId}/api-keys` |
| Cobranças do cliente | Cobrança com a chave da subconta | `POST /v1/charges` |
| Remuneração da agência | `split` para a conta master | [Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) · [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) |
| Avisos ao cliente | Endpoint da conta master com eventos das subcontas, `postbackUrl` e repasse | [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) · `POST /v1/webhook-endpoints` |
| Taxas por cliente | Consulta de taxas e dados cadastrais | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` · [Taxas](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md) |
| Saque do cliente | Saque da subconta | `POST /v1/submerchants/{merchantId}/payout-requests` · [Saques](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) |

O desenho abaixo mostra uma venda feita pelo Órbita Pay, do sistema do cliente até o repasse do aviso de pagamento.

```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
    CF(["Cliente final<br/>do Bistrô Maré"]):::comprador
    SC["Sistema do Bistrô Maré<br/>credencial da Órbita"]:::lojista
    OP["Backend do Órbita Pay<br/>conta master"]:::lojista
    COF["Cofre de segredos<br/>chave sk_ de cada cliente"]:::lojista
    API["Finvia API · Connect"]:::finvia
    ADQ["Adquirente e bandeiras<br/>cartão em 3x"]:::externo
    EV[["Eventos das subcontas<br/>charge.* e payout.*"]]:::evento
    W["Receptor da Órbita<br/>include_submerchants"]:::lojista
    FL["Fila de repasse<br/>com retentativa própria"]:::lojista
    CF -->|"1. compra"| SC
    SC -->|"2. chama a API<br/>do Órbita Pay"| OP
    OP -->|"3. busca a chave<br/>do cliente"| COF
    OP ==>|"4. POST /v1/charges<br/>chave da subconta<br/>split 1,5669%"| API
    API -->|"5. autoriza"| ADQ
    API -->|"6. publica o evento"| EV
    EV -.->|"7. entrega"| W
    W -->|"8. confere o status<br/>e enfileira"| FL
    FL -.->|"9. repassa no formato<br/>da Órbita"| SC
    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 externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    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
```

Este segundo desenho mostra a estrutura de contas: a Órbita é a conta master e cada cliente tem a própria subconta.

```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
    FV["Finvia · Connect"]:::finvia
    OR["Órbita Digital<br/>conta master"]:::lojista
    S1["Bistrô Maré<br/>subconta"]:::lojista
    S2["Loja de moda<br/>subconta"]:::lojista
    S3["Escola de idiomas<br/>subconta"]:::lojista
    MAIS["...até 60 clientes<br/>cada um com subconta"]:::neutro
    BK["Conta do Bistrô Maré<br/>Pix na chave CNPJ"]:::externo
    SO["Saldo da Órbita<br/>parte de cada venda"]:::ok
    FV -->|"1. habilita o módulo"| OR
    OR -->|"2. subconta, KYC<br/>e chaves próprias"| S1
    OR --> S2
    OR --> S3
    OR -.-> MAIS
    S1 -->|"4. saque do saldo<br/>do cliente"| BK
    S1 -.->|"3. split em<br/>cada venda"| SO
    S2 -.-> SO
    S3 -.-> SO
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    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
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

Todo cliente segue o mesmo desenho do Bistrô Maré: recebe as vendas no próprio saldo e saca por Pix para a chave CNPJ dele.

## Passo a passo

**1. Habilite o Connect e defina a configuração padrão**

A Finvia habilita o módulo na conta da Órbita. Na criação, cada subconta recebe uma **cópia** das taxas e configurações da conta master vigentes naquele momento. Depois disso, as taxas da subconta são independentes: mudar as taxas da conta master não muda as das subcontas já criadas. Antes de cadastrar o primeiro cliente, alinhe com o time Finvia as taxas e a configuração que a conta master vai ter, porque elas viram o ponto de partida de todas as subcontas.

**2. Crie a subconta de cada cliente**

Quando a Órbita fecha com um cliente novo, o Bistrô Maré, o backend do Órbita Pay cria a subconta com a chave da conta master. O corpo segue o mesmo formato mostrado em [Marketplace e PSP](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md): dados da empresa, `productType`, representante legal, endereço, telefones, conta bancária e `canAccessDashboard`. Com país `BRA`, a API confere o dígito verificador do CNPJ e do CPF do responsável, a UF e o CEP de 8 dígitos, e o `addressLine1` leva o número depois da vírgula (`Av. Paulista, 1000`). Um CNPJ que já existe entre as subcontas da Órbita é recusado com `409`.

Com `canAccessDashboard: true`, o cliente ganha acesso ao painel da Finvia e o objeto `user` passa a ser obrigatório. Com `false`, o cliente usa só as telas do Órbita Pay. A decisão é da agência e depende de quanto ela quer centralizar o atendimento.

Guarde o `id` da subconta junto do cadastro do cliente no Órbita Pay.

**3. Conduza o KYC do cliente**

Envie cartão CNPJ, contrato social, documento do responsável (frente e verso) e selfie com documento. Se preferir que o próprio cliente envie os arquivos, emita um token de upload (`POST /v1/submerchants/{merchantId}/document/upload-token`, válido por 300 segundos e de uso único) e deixe o navegador do cliente chamar `POST /v1/document-uploads` com `Authorization: Bearer`. Assim, a chave da agência não sai do servidor.

Acompanhe os avisos de status até `active`. Eles vão para o `postbackUrl` informado na criação da subconta (sem ele, para a URL de aviso da conta master, se houver). Quando vier `correcting` ou `rejected`, o motivo está em `rejectionReason`. A correção de dados é feita no painel da Finvia, na gestão de subcontas.

**4. Gere e guarde as chaves por cliente**

Com a subconta ativa:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/api-keys" \
  -u "$FINVIA_API_KEY:"
```

```json theme={null}
{
  "publicKey": "pk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
  "secretKey": "sk_2vorkLm4Qp8TzR1sXc7Yb3NdWkE"
}
```

A chave secreta do cliente fica **no backend do Órbita Pay**, em um cofre de segredos, associada ao cliente. O sistema do cliente recebe uma credencial da própria Órbita, emitida pela agência. A chave pública pode ir para o front-end do cliente quando ele usar Apple Pay ou 3D Secure; ela não cria cobranças. As duas chaves formam um par: se a secreta for trocada, a pública também muda.

> [!WARNING]
>
> Não entregue a chave secreta da Finvia ao cliente se o modelo é que todas as chamadas passem pela Órbita. Com a chave na mão, o cliente pode criar cobranças sem o `split` da agência.

**5. Calcule a remuneração da agência**

A Órbita quer 1,5% do valor bruto. O split incide sobre o [valor líquido](https://docs.fastpaybrasil.com/glossario.md): o valor da venda menos a taxa transacional (fixa mais percentual). Exemplo com números ilustrativos: venda de R\$ 180,00 em 3x, com taxa transacional de 3,99% (índice `2` da linha `tx_spread`) e taxa fixa de R\$ 0,50.

| Passo | Conta | Resultado |
| - | - | - |
| Valor líquido (L) | 180 × (1 − 0,0399) − 0,50 | R\$ 172,318 |
| Remuneração desejada | 1,5% × R\$ 180,00 | R\$ 2,70 |
| Split a informar (s) | 2,70 ÷ 172,318, arredondado para cima na quarta casa | 1,5669% |
| Conferência | 1,5669% × 172,318 | R\$ 2,70 para a Órbita |

A taxa de antecipação (2,50% ao mês no exemplo abaixo) não entra nessa conta. Ela só reduz a base quando o cliente antecipa o recebível: nesse caso, o split é recalculado sobre o valor antecipado e a Órbita recebe proporcionalmente menos. A taxa de antecipação é mensal, multiplicada pelo número de meses até o vencimento de cada parcela (mínimo de 1 mês).

As taxas reais de cada cliente vêm da rota de taxas, chamada com a chave da conta master:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/fees-info" \
  -u "$FINVIA_API_KEY:"
```

```json theme={null}
{
  "merchant": {
    "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
    "legalName": "BISTRO MARE RESTAURANTE LTDA",
    "companyTaxId": "11222333000181"
  },
  "fees": [
    {
      "feeType": "tx_spread",
      "paymentMethod": "credit_card",
      "currencyCode": "BRL",
      "brand": null,
      "definition": {
        "fixed": 0.5,
        "percentages": [2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49]
      }
    },
    {
      "feeType": "anticipation",
      "paymentMethod": "credit_card",
      "currencyCode": "BRL",
      "brand": null,
      "definition": { "fixed": 0, "percentages": [2.5] }
    }
  ]
}
```

Com a chave da conta master, a rota devolve a subconta pedida. Com a chave da própria subconta, ela ignora o `id` e devolve os dados da subconta autenticada. Um `id` que não pertence à Órbita retorna `404` "Subconta não encontrada"; sem o Connect habilitado, `403`. Escolher a linha certa por bandeira e parcela é responsabilidade de quem consome: use a linha da bandeira do cartão quando existir e a linha `brand: null` quando não houver. A rota não traz reserva financeira nem taxa de saque.

Lista `fees` vazia, ou sem linha para o método e a moeda, significa subconta sem taxas configuradas: as cobranças dessa combinação são recusadas com `422` `Fees not configured`. Nesse caso, acione o suporte da Finvia.

**6. Crie as cobranças pelo Órbita Pay**

O sistema do cliente chama a API do Órbita Pay. O backend da Órbita recebe o pedido, calcula o percentual e chama a Finvia com a chave da subconta do cliente:

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$CHAVE_SUBCONTA_BISTRO_MARE:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 180,
    "currency": "BRL",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": { "type": "cpf", "id": "52998224725" }
    },
    "paymentMethod": {
      "type": "credit_card",
      "number": "1111222233334444",
      "holderName": "MARIA SOUZA",
      "expirationMonth": "10",
      "expirationYear": "2028",
      "cvv": "123",
      "installments": 3
    },
    "items": [
      { "title": "Voucher jantar para dois", "type": "digital", "description": "Menu degustação, válido por 90 dias", "unit_price": 180, "quantity": 1 }
    ],
    "split": [
      { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 1.5669 }
    ],
    "metadata": { "orbitaCliente": "bistro-mare", "orbitaPedido": "BM-7781" },
    "postbackUrl": "https://pay.orbita.exemplo.com.br/webhooks/finvia/postback"
  }'
```

O `merchantId` do split é o ID da conta master da Órbita (`36OO3bcGjhPjjF3tzrqOGcmQuKo`). Nos exemplos desta página, `2vorkLm4Qp8TzR1sXc7Yb3NdWkE` é a subconta do Bistrô Maré. O restante do líquido fica com o Bistrô Maré, que é o [originador](https://docs.fastpaybrasil.com/glossario.md) da venda. A parte da Órbita é repassada quando o recebível do Bistrô Maré é liquidado: no cartão, a cada parcela, em D+30, D+60 e D+90; no Pix, logo após a confirmação do pagamento.

**7. Repasse os webhooks a cada cliente**

As cobranças pertencem às subcontas dos clientes. Para receber os eventos de todas elas, a Órbita cadastra um endpoint na conta master com a opção de incluir subcontas:

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://pay.orbita.exemplo.com.br/webhooks/finvia",
    "enabled_events": [],
    "include_submerchants": true
  }'
```

O corpo vai em snake\_case, e `enabled_events: []` significa todos os eventos. A resposta é `201` sem corpo; para obter o `id` do endpoint, use `GET /v1/webhook-endpoints?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo`. No painel, o mesmo cadastro fica em **Configurações** > **Webhooks**, com a opção de incluir subcontas. O `postbackUrl` de todas as cobranças também aponta para o Órbita Pay, em outra URL.

Ao receber um evento, a Órbita identifica o cliente pelo `merchant_id` do evento (ou pelo `metadata`), confirma o status na Finvia e repassa ao endpoint que o cliente cadastrou no Órbita Pay.

```javascript theme={null}
app.post('/webhooks/finvia', async (req, res) => {
  const { id, event, data } = req.body;
  if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK');
  res.status(200).send('OK');

  const cliente = await clientes.porSubconta(data.merchant_id ?? data.merchantId);
  const cobranca = await finvia.get(`/v1/charges/${data.id}`, cliente.chaveSecreta);

  // Repasse no formato da Órbita, com o status confirmado na API
  await filaDeRepasse.enviar(cliente.urlWebhook, {
    evento: event,
    pedido: cobranca.metadata?.orbitaPedido,
    status: cobranca.status,
    valor: cobranca.amount,
  });
  if (id) await eventos.marcarProcessado(id);
});
```

| Canal da Finvia | O que chega | Observação |
| - | - | - |
| Endpoint da conta master com `include_submerchants: true` | Eventos de cobrança, de assinatura e de saque das subcontas, como `charge.paid`, `charge.refunded`, `charge.blocked`, `payout.approved` e `payout.rejected` | Envelope padrão; o `merchant_id` (ou `merchantId`, nos saques) indica a subconta |
| `postbackUrl` da cobrança | Os mesmos eventos de cobrança, mais o `charge.updated` legado | `charge.updated` (chargeback formalizado, recusa ou falha informada depois pela adquirente, Pix expirado, fim do 3DS, bloqueio, pré-chargeback) só chega por aqui, sem `id` de evento e em camelCase |
| Aviso de status da subconta | `pre_approved`, `correcting`, `active`, `rejected`, `blocked` | Vai ao `postbackUrl` do cadastro da subconta; payload sem envelope; responda com 2xx |

> [!TIP]
>
> **Para o desenvolvedor:** responda à Finvia com `200` antes de repassar ao cliente, e faça o repasse por uma fila com retentativa própria. Se o endpoint do cliente estiver fora do ar, a fila da Órbita tenta de novo, sem depender de uma nova entrega da Finvia. Como o `charge.updated` não tem `id`, use o `data.id` da cobrança mais o `status` e o `updatedAt` para deduplicar.

**8. Ofereça saque ao cliente**

Cada cliente saca o próprio saldo por Pix para a chave CNPJ da subconta, com valor em reais e mínimo de R\$ 1,00. A Órbita pede o saque com a chave secreta da conta master:

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/payout-requests" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1200 }'
```

O saque nasce `pending`, passa por aprovação da Finvia e termina `approved` ou `rejected`. Os avisos `payout.approved` e `payout.rejected` chegam ao endpoint da conta master com a opção de incluir subcontas, com os valores em texto decimal (`"1200.00000000"`). Confirme o status pela listagem `GET /v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE` antes de avisar o cliente. Oriente cada cliente a cadastrar o CNPJ como chave Pix em uma conta bancária da empresa antes do primeiro saque.

## Regras e cuidados

> [!WARNING]
>
> **Uma chave por cliente, sempre a certa.** Cobrança criada com a chave da conta master fica no saldo da Órbita. Cobrança criada com a chave de outro cliente fica no saldo do cliente errado. Valide o mapeamento cliente → chave antes de cada chamada.

> [!WARNING]
>
> **Valores em reais** em cobrança, split e saque. `"amount": 180` é R\$ 180,00.

* **Mesmo grupo.** As contas do `split` precisam pertencer ao mesmo [grupo Connect](https://docs.fastpaybrasil.com/glossario.md) (a conta master e as subcontas dela). A soma dos percentuais não passa de 100%.
* **Split da requisição prevalece.** O `split` enviado na cobrança vale para aquela venda e prevalece sobre a regra padrão de split da conta.
* **Assinaturas sem split.** Se um cliente cobrar mensalidades por assinatura, essas cobranças recorrentes não recebem split e a remuneração da Órbita não sai automaticamente.
* **Webhooks sem assinatura.** Os eventos não têm assinatura HMAC ([Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#regras-de-negócio)): confirme o status na API antes de repassar ao cliente um evento que libera produto ou serviço.
* **Saques pela listagem.** Confirme o status de cada saque em `GET /v1/payout-requests` antes de avisar o cliente.
* **Homologação por funcionalidade.** Cada funcionalidade que a Órbita oferece (cartão, Pix, Apple Pay, split, subcontas, saques) tem cenários próprios no roteiro. O roteiro é uma etapa recomendada, acompanhada pelo suporte da Finvia; a API não bloqueia a produção até a homologação.

## Variações do caso

> [accordion] E se a agência preferir cobrar uma mensalidade fixa?
>
> Remova o `split` das cobranças dos clientes e cobre a mensalidade da agência como uma assinatura na conta master, com o cliente da agência como pagador. O desenho está em [SaaS por assinatura](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md).

> [accordion] E se um cliente da agência tiver vendedores próprios?
>
> Subconta e conta master formam um único nível no Connect. Se o cliente for um marketplace com vendedores, os vendedores podem ser subcontas no mesmo grupo da Órbita, e a venda pode separar a parte do marketplace (subconta para subconta) e a parte da Órbita (subconta para conta master) no mesmo `split`. A soma dos percentuais continua limitada a 100%.

> [accordion] E se um cliente quiser Apple Pay no site dele?
>
> O domínio do checkout precisa ser registrado com a chave secreta **da subconta do cliente** (`POST /v1/apple-pay/domains`). Registrar o primeiro domínio ativa o Apple Pay na subconta, e o registro vale para teste e produção. Plataformas que servem várias lojas no mesmo hostname registram esse hostname uma vez para cada merchant. A validação de sessão no navegador usa a chave pública da subconta. Detalhes no [guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md).

> [accordion] E se a agência quiser dar ao cliente acesso direto ao painel?
>
> Crie a subconta com `canAccessDashboard: true` e o objeto `user` (nome, e-mail e telefone no formato E.164). O cliente passa a ver as próprias movimentações no painel da Finvia.

## Checklist de implementação

* [ ] Connect habilitado e configuração padrão da conta master alinhada com a Finvia
* [ ] Criação de subconta por cliente, com KYC completo
* [ ] Token de upload para o cliente enviar documentos sem expor a chave da agência
* [ ] Tratamento dos avisos de status das subcontas
* [ ] Chaves secretas dos clientes em cofre de segredos, no backend da agência
* [ ] Mapeamento cliente → subconta → chave validado antes de cada cobrança
* [ ] Percentual do split calculado por venda com as taxas de `fees-info`
* [ ] `postbackUrl` da agência em todas as cobranças
* [ ] Repasse de eventos aos clientes por fila própria, com status confirmado na API
* [ ] Deduplicação por `id` de evento e, no `charge.updated`, por cobrança + status + data
* [ ] Endpoint da conta master com `include_submerchants: true` para cobranças e saques das subcontas
* [ ] Cenários de homologação de cada funcionalidade oferecida aos clientes

## Como homologar

| Funcionalidade | Cenários |
| - | - |
| Subcontas | FC-01 a FC-08 |
| Remuneração por split | SPL-01 a SPL-06 |
| Cobranças | CHG-01 a CHG-10, conforme os métodos oferecidos |
| Apple Pay, se oferecido | AP-01 a AP-06 |

Cada cenário pede evidência (requisição, resposta, `id` e registro de webhook), enviada ao suporte da Finvia, que acompanha a homologação. O saque (FC-07) não roda com a chave de teste, que recebe `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. Detalhes no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md) e no [checklist de go-live](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md).

## Veja também

> [card] [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md)
>
> Conta master, subcontas e cópia das configurações na criação.

> [card] [Chaves de API da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md)
>
> Referência da rota de chaves.

> [card] [Taxas e dados da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados.md)
>
> Referência da rota `fees-info`.

> [card] [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Canais, envelopes e retentativas.


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