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

# Split de pagamentos

> Divida o valor de cada venda entre a conta master e as subcontas do seu grupo Connect, por regra padrão da conta ou por cobrança via API, e saiba quando cada parte é repassada.

O split divide automaticamente o valor de uma venda entre contas do mesmo [grupo Connect](https://docs.fastpaybrasil.com/glossario.md) (a conta master e as subcontas dela). A plataforma recebe a comissão dela, o vendedor recebe a parte dele, e um parceiro pode receber uma fatia, tudo na mesma cobrança e sem transferências manuais depois da venda.

## Quando usar

| Situação | Como o split ajuda |
| - | - |
| Plataforma que cobra comissão sobre as vendas dos clientes | A subconta vende e uma parte de cada venda vai para a conta master |
| Marketplace com produto de um vendedor e frete ou serviço de outro | A venda é dividida entre duas subcontas do mesmo grupo |
| Programa de afiliados ou indicação dentro do grupo | Uma subconta recebe um percentual das vendas de outra |
| Conta master que vende e repassa parte a um parceiro | A master origina a cobrança e destina um percentual à subconta do parceiro |

Não use o split para dividir valores com empresas fora do seu grupo Connect: todas as contas participantes precisam estar no mesmo grupo. Para cadastrar um novo participante, crie uma subconta ([Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)).

> [!WARNING]
>
> Para PSPs, o split é obrigatório: toda transação de PSP precisa ter split entre a conta master (PSP) e a subconta (lojista), e split de 100% para o PSP não é permitido. Veja as [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md).

## Como funciona

O desenho abaixo mostra como o valor de uma venda é dividido, usando o exemplo "Dois recebedores" desta página: a plataforma fica com 5% do líquido, o parceiro com 10% e o vendedor com o restante.

```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
    ORIG["Subconta do vendedor<br/>originadora da venda"]:::lojista
    API["Finvia API"]:::finvia
    Q{"A cobrança traz<br/>o campo split?"}:::decisao
    SAPI["Vale o split enviado<br/>só para esta cobrança"]:::neutro
    SPAD["Vale a regra padrão<br/>da conta ou da master"]:::neutro
    C(["Comprador"]):::comprador
    BRUTO["Valor bruto da venda"]:::neutro
    LIQ["Valor líquido<br/>base do split"]:::alerta
    MASTER["Conta master<br/>plataforma · 5%"]:::lojista
    PARC["Subconta do parceiro<br/>entrega · 10%"]:::lojista
    VEND["Subconta do vendedor<br/>restante · 85%"]:::lojista
    ORIG -->|"1. POST /v1/charges<br/>com a chave dele"| API
    API --> Q
    Q -->|"sim"| SAPI
    Q -->|"não"| SPAD
    C -->|"2. paga"| BRUTO
    SAPI --> BRUTO
    SPAD --> BRUTO
    BRUTO -->|"3. menos a taxa da Finvia<br/>fixa + percentual"| LIQ
    LIQ ==>|"4. 5%"| MASTER
    LIQ ==>|"4. 10%"| PARC
    LIQ ==>|"4. o que sobra"| VEND
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

O valor de cada participante é calculado na criação da cobrança e dividido igualmente entre as parcelas. O vendedor não entra na lista `split`: como originador, ele fica com o que sobra.

**1. Defina quem origina a venda**

O [originador](https://docs.fastpaybrasil.com/glossario.md) é a conta cuja chave secreta cria a cobrança. Em um marketplace, normalmente é a subconta do vendedor.

**2. Defina os recebedores e percentuais**

Cada recebedor é um `merchantId` com um `percentage` entre `0.01` e `100`. A soma não pode passar de 100%.

**3. Crie a cobrança**

Com regra de split padrão configurada na conta, basta criar a cobrança. Para uma divisão específica daquela venda, envie o campo `split` em `POST /v1/charges`.

**4. O valor de cada participante é calculado**

Na criação da cobrança, a Finvia desconta a taxa transacional (fixa + percentual) do [valor bruto](https://docs.fastpaybrasil.com/glossario.md). Sobre o [valor líquido](https://docs.fastpaybrasil.com/glossario.md) que sobra, cada recebedor fica com o percentual dele. O restante fica com o originador. O valor de cada participante é dividido igualmente entre as parcelas.

**5. Repasse na liquidação**

Cada parte é repassada parcela a parcela, quando o recebível do originador é [liquidado](https://docs.fastpaybrasil.com/glossario.md): no cartão, a cada 30 dias por parcela; no Pix, logo após a confirmação do pagamento. Veja a seção "Liquidação e repasse", abaixo.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Soma dos percentuais | Não pode passar de 100% |
| Restante | Se a soma for menor que 100%, o que sobra fica com o originador da venda |
| Grupo | Todas as contas participantes precisam pertencer ao mesmo grupo Connect |
| Limites por recebedor | `percentage` mínimo `0.01` e máximo `100` |
| Base de cálculo | Por padrão, o percentual incide sobre o valor **líquido**, depois da taxa transacional da Finvia. Calcular sobre o valor bruto é uma configuração de conta, sob consulta |
| Autenticação | A cobrança é criada com a chave secreta da conta originadora |
| Prioridade | O split enviado na API vale só para aquela cobrança e prevalece sobre a regra padrão da conta |
| Sem `split` na cobrança | Vale a regra padrão da conta para aquela moeda e método. Subconta sem regra própria usa a regra padrão da master |
| Repasse | Parcela a parcela, na liquidação do recebível do originador: cartão em D+30, D+60...; Pix no mesmo dia, logo após a confirmação |
| PSP | Toda transação de PSP precisa de split entre a master (PSP) e a subconta (lojista). Split de 100% para o PSP não é permitido |
| Assinaturas | As cobranças recorrentes de assinatura não recebem split |

### Relações permitidas

| Originador | Recebedor |
| - | - |
| Conta master | Subconta |
| Subconta | Conta master |
| Subconta | Subconta do mesmo grupo |

> [!WARNING]
>
> O percentual é aplicado sobre o valor **líquido**, que é o valor da venda menos as taxas da Finvia. Se a sua plataforma cobra 2% sobre o valor bruto e você envia `percentage: 2`, recebe menos do que espera. Calcule o percentual correto com a fórmula de [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

> [!WARNING]
>
> Para que a venda fique vinculada à subconta que vendeu, crie a cobrança com a **chave secreta da subconta originadora**, obtida em `GET /v1/submerchants/{id}/api-keys`. Se a cobrança for criada com a chave da master, a master é a originadora.

## Split padrão da conta

No [painel da Finvia](https://app.finvia.com.br), na gestão de subcontas, você configura a regra de split padrão: os participantes e o percentual de cada um.

* A configuração vira o **padrão** daquela conta: todas as cobranças que ela originar sem o campo `split` seguem a regra.
* A regra vale por moeda e por meio de pagamento (por exemplo, um percentual no Pix e outro no cartão).
* Uma subconta sem regra própria usa a regra padrão definida pela master.

> [!NOTE]
>
> **Para o negócio:** o split padrão é indicado quando a regra comercial é fixa por vendedor, como uma comissão contratual. A sua equipe configura uma vez e as vendas seguintes já saem divididas, mesmo que a integração não envie o campo `split`.

## Split por cobrança via API

Envie o campo `split` no corpo de `POST /v1/charges`:

| Campo | Tipo | Descrição |
| - | - | - |
| `split` | array | Lista de recebedores daquela cobrança |
| `split[].merchantId` | string | `id` da conta que recebe a parte |
| `split[].percentage` | number | Percentual destinado a essa conta. Mínimo `0.01`, máximo `100` |

A configuração enviada pela API vale **somente para aquela cobrança** e prevalece sobre a regra padrão da conta. O split vale para cobranças criadas por `POST /v1/charges`; as cobranças recorrentes de assinatura não recebem split.

**Em validação (V-64):** há um erro conhecido no split de cobranças com 3D Secure gerenciado. Até a correção, não combine split com 3DS gerenciado.

> [!TIP]
>
> **Para o desenvolvedor:** use o split via API quando o percentual muda de venda para venda (por exemplo, comissão diferente por categoria de produto ou por campanha). Calcule o percentual no seu servidor, com as taxas reais da subconta, antes de criar a cobrança.

## Exemplos

Os exemplos usam três contas do mesmo grupo Connect. Substitua pelos `id` reais.

| Papel | `id` de exemplo |
| - | - |
| Conta master (plataforma) | `36OO3bcGjhPjjF3tzrqOGcmQuKo` |
| Subconta do vendedor | `2vorkDcXyvzifL63YX09S9VqcnI` |
| Subconta do parceiro | `2vorkEaaaBbbCccDddEeeFffGgg` |

A variável `SUBCONTA_SECRET_KEY` guarda a chave secreta da subconta do vendedor, e `FINVIA_API_KEY` guarda a chave secreta da conta master.

> [tab] Comissão da plataforma
>
> A subconta do vendedor vende um produto de R\$ 100,00 por Pix e a plataforma (conta master, `36OO3bcGjhPjjF3tzrqOGcmQuKo`) recebe a comissão. A plataforma cobra 2% sobre o bruto. As taxas deste exemplo são ilustrativas: Pix com 1,5% e sem taxa fixa. O líquido é R\$ 98,50 e o percentual sobre o líquido fica em `2.0305`, que entrega R\$ 2,00 à plataforma (veja a fórmula em [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)). Na sua integração, use as taxas reais da subconta.
>
> ```bash theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
>   -u "$SUBCONTA_SECRET_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "amount": 100,
>     "currency": "BRL",
>     "customer": {
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document": { "type": "cpf", "id": "52998224725" }
>     },
>     "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 },
>     "items": [
>       { "title": "Curso de fotografia", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 100, "quantity": 1 }
>     ],
>     "split": [
>       { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 2.0305 }
>     ],
>     "postbackUrl": "https://meusite.com.br/webhooks/finvia"
>   }'
> ```

> [tab] Dois recebedores
>
> Venda de R\$ 450,00 em 3x no cartão. A subconta do vendedor (`2vorkDcXyvzifL63YX09S9VqcnI`) origina a venda com a chave dela. A plataforma (conta master, `36OO3bcGjhPjjF3tzrqOGcmQuKo`) recebe 5% do líquido e o parceiro de entrega (subconta `2vorkEaaaBbbCccDddEeeFffGgg`) recebe 10% do líquido. A soma é 15%, e os 85% restantes ficam com o vendedor, que não aparece na lista `split` porque é o originador.
>
> ```bash theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
>   -u "$SUBCONTA_SECRET_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "amount": 450,
>     "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": "Luminária de mesa", "type": "physical", "description": "Luminária articulada", "unit_price": 450, "quantity": 1 }
>     ],
>     "shippingAddress": {
>       "postalCode": "01310100",
>       "addressLine1": "Av. Paulista, 1000",
>       "addressLine2": "Apto 51",
>       "neighborhood": "Bela Vista",
>       "city": "São Paulo",
>       "state": "SP",
>       "country": "BRA"
>     },
>     "split": [
>       { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 5 },
>       { "merchantId": "2vorkEaaaBbbCccDddEeeFffGgg", "percentage": 10 }
>     ]
>   }'
> ```

> [tab] Subconta para subconta
>
> Um professor (subconta do vendedor, `2vorkDcXyvzifL63YX09S9VqcnI`, originadora) vende uma aula de R\$ 200,00 e repassa 30% do líquido ao estúdio que hospeda a aula (subconta do parceiro, `2vorkEaaaBbbCccDddEeeFffGgg`). A conta master não participa desta divisão.
>
> ```bash theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
>   -u "$SUBCONTA_SECRET_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "amount": 200,
>     "currency": "BRL",
>     "customer": { "name": "Ana Lima", "email": "ana@email.com" },
>     "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 },
>     "items": [
>       { "title": "Aula particular de violão", "type": "digital", "description": "Aula online de 1 hora", "unit_price": 200, "quantity": 1 }
>     ],
>     "split": [
>       { "merchantId": "2vorkEaaaBbbCccDddEeeFffGgg", "percentage": 30 }
>     ]
>   }'
> ```

> [tab] Master para subconta
>
> A conta master vende diretamente e destina 15% do líquido à subconta do parceiro (`2vorkEaaaBbbCccDddEeeFffGgg`). Aqui a cobrança é criada com a chave secreta da master.
>
> ```bash theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
>   -u "$FINVIA_API_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "amount": 120,
>     "currency": "BRL",
>     "customer": { "name": "Joao Silva", "email": "joao@email.com" },
>     "paymentMethod": { "type": "pix", "expirationInDays": 1 },
>     "items": [
>       { "title": "Ingresso de workshop", "type": "digital", "description": "Workshop de marketing digital", "unit_price": 120, "quantity": 1 }
>     ],
>     "split": [
>       { "merchantId": "2vorkEaaaBbbCccDddEeeFffGgg", "percentage": 15 }
>     ]
>   }'
> ```

### Exemplo em Node.js

```javascript Node.js theme={null}
async function criarVendaComComissao({ chaveSubconta, valor, percentualSplit, contaComissao, pedido }) {
  const credentials = Buffer.from(`${chaveSubconta}:`).toString('base64');

  const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: valor,
      currency: 'BRL',
      customer: pedido.cliente,
      paymentMethod: { type: 'pix', expirationInSeconds: 3600 },
      items: pedido.itens,
      metadata: { orderId: pedido.id },
      split: [{ merchantId: contaComissao, percentage: percentualSplit }],
    }),
  });

  return response.json();
}
```

## Split em Pix e em cartão parcelado

O campo `split` é o mesmo para Pix e para cartão. A diferença está nas taxas: cada método, bandeira e número de parcelas pode ter uma taxa diferente, e isso muda o valor líquido. Como o split incide sobre o líquido, o mesmo percentual entrega valores diferentes em uma venda Pix e em uma venda em 6x de mesmo valor bruto.

Se a sua comissão é definida sobre o valor bruto, calcule o percentual para cada combinação de método e parcelas a partir das taxas reais da subconta ([Taxas da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md) e [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)).

## Liquidação e repasse

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, a cada 30 dias por parcela (D+30, D+60...); no Pix, 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. Se o originador antecipar, o repasse acontece na antecipação e é calculado sobre o valor já descontada a taxa de antecipação. A parte correspondente à reserva financeira do originador é repassada quando a reserva é liberada.

O desenho abaixo mostra quando a parte do recebedor sai do saldo do originador e chega ao saldo dele, no Pix, no cartão parcelado e na antecipação.

```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
    PAGA(["Cobrança paga<br/>partes já calculadas"]):::ok
    ALIB["Saldo a liberar<br/>do originador<br/>recebedor ainda não vê"]:::alerta
    Q{"Quando o recebível<br/>do originador liquida?"}:::decisao
    PIX["Pix<br/>no mesmo dia, logo<br/>após a confirmação"]:::neutro
    CARD["Cartão parcelado<br/>parcela a cada 30 dias<br/>1ª D+30 · 2ª D+60..."]:::neutro
    ANT["Antecipação: na hora<br/>com base líquida, desconta<br/>a taxa de antecipação"]:::alerta
    REP["Repasse<br/>sai do saldo disponível<br/>do originador"]:::finvia
    REC(["Saldo disponível<br/>do recebedor"]):::ok
    PAGA --> ALIB
    ALIB --> Q
    Q -->|"Pix"| PIX
    Q -->|"cartão"| CARD
    Q -.->|"originador antecipa"| ANT
    PIX -->|"parte inteira"| REP
    CARD -->|"parte de cada<br/>parcela"| REP
    ANT -->|"parte recalculada"| REP
    REP ==> REC
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
```

Retenção do recebível pela Finvia, reserva financeira, bloqueio de saldo do recebedor e estorno mudam esse caminho como descrito na tabela a seguir.

| Situação | O que acontece com o split |
| - | - |
| Cartão de crédito | Cada parcela é liberada 30 dias corridos depois da criação da cobrança: 1ª em D+30, 2ª em D+60 e assim por diante |
| Pix | Liberação no mesmo dia, logo após a confirmação do pagamento |
| Antes da liquidação | O valor inteiro fica no saldo a liberar do originador. O recebedor ainda não vê nada no saldo |
| Recebível do originador retido pela Finvia | A liquidação e o repasse ficam suspensos até a liberação |
| Recebedor com bloqueio de saldo | O crédito entra como saldo bloqueado |
| Reserva financeira do originador | A fração do split que corresponde à parte reservada só é repassada quando a reserva daquele recebível é liberada pela Finvia (padrão de 90 dias). O restante é repassado na liquidação |
| Antecipação pelo originador | Só o originador antecipa; o recebedor não antecipa a parte do split. Na antecipação, a parte do split é repassada na hora. Com base líquida (o padrão), o split é recalculado sobre o valor já descontada a taxa de antecipação, ou seja, o recebedor arca proporcionalmente com essa taxa |
| Estorno depois do repasse | A parte já repassada é debitada do saldo do recebedor e devolvida ao originador |

> [!NOTE]
>
> **Para o negócio:** duas opções são configuradas pela Finvia, **sob consulta**: calcular o split sobre o valor bruto (com base bruta, a antecipação não muda o valor do split) e a conta master absorver a taxa de antecipação das subcontas. Fale com o seu contato comercial se precisar de alguma delas.

## Consulte os valores divididos

Depois da venda, consulte a cobrança em [`GET /v1/charges/{id}`](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar). A resposta traz a lista `splits`, um item por recebedor. Ela não aparece na listagem de cobranças nem na resposta de criação.

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/2v2TGGb4NHTQWCiMmnelz2WVOZP" \
  -u "$SUBCONTA_SECRET_KEY:"
```

| Campo de `splits[]` | Significado |
| - | - |
| `id` | Id do registro de split |
| `destinyMerchantId` | Conta recebedora (o `merchantId` enviado em `split[]`) |
| `destinyMerchantName` | Nome fantasia da conta recebedora |
| `splitPercentage` | Percentual, como texto decimal (ex.: `"30.00000000"`). Converta para número |
| `splitAmount` | Valor exibido para o recebedor, número com 2 casas (truncado). Veja abaixo |
| `referenceAmount` | Base de cálculo: `net` (valor líquido, o padrão) ou `gross` (valor bruto) |

No POST o campo é `split` (singular), com `merchantId` e `percentage`. Na consulta é `splits` (plural), com os nomes acima. Se a cobrança foi criada sem `split`, `splits` vem preenchido com a regra padrão da conta.

O que `splitAmount` mostra com base `net`:

* **Enquanto há parcelas a liquidar e nenhuma antecipação concluída:** uma simulação do valor que o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Não é o valor que será repassado.
* **Depois que as parcelas liquidam sem antecipação:** o percentual sobre o valor líquido, sem desconto de antecipação.
* **Depois de uma antecipação concluída:** o valor efetivamente destinado, recalculado sobre o valor antecipado.

Com base `gross`, `splitAmount` é sempre o percentual × valor bruto. O split pode aparecer também em cobrança recusada, mas o repasse só acontece quando a cobrança é paga.

Para acompanhar o total recebido por split em cada subconta, `GET /v1/submerchants/{id}` traz o objeto `metrics`, com `splitBalance` (total recebido por split, em reais) e `splitRate` (percentual médio de split aplicado à subconta).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| Cobrança rejeitada com erro de validação | `percentage` igual a 0, acima de 100 ou soma dos percentuais acima de 100% | Envie cada percentual entre `0.01` e `100` e confira a soma |
| Cobrança rejeitada | `merchantId` inexistente ou fora do seu grupo Connect | Use o `id` de uma conta do mesmo grupo |
| Recebedor ficou com menos do que o esperado | Percentual calculado sobre o bruto, mas aplicado sobre o líquido | Recalcule com a fórmula de [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) |
| Venda não aparece vinculada à subconta | Cobrança criada com a chave da master | Use a chave secreta da subconta originadora |
| Venda saiu com a divisão configurada no painel | O campo `split` não foi enviado na cobrança, então valeu a regra padrão da conta (ou da master) | Envie `split` na cobrança. O split da API prevalece sobre o padrão |
| `splitAmount` menor que percentual × líquido | Enquanto as parcelas não liquidam, o valor exibido simula uma antecipação | Use `splitPercentage` e `referenceAmount` para conferir. O valor final aparece depois da liquidação |
| Assinatura sem split | As cobranças recorrentes de assinatura não recebem split | Use cobranças avulsas em `POST /v1/charges` quando precisar dividir o valor |
| Valores com diferença de centavos | Arredondamento do percentual | Mantenha as casas decimais do percentual e arredonde só o valor em reais, no fechamento ([Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)) |

## Perguntas frequentes

> [accordion] Se eu não enviar split na cobrança, o que acontece?
>
> Vale a regra padrão da conta originadora para aquela moeda e método. Uma subconta sem regra própria usa a regra padrão da master. Sem nenhuma regra, a venda inteira (líquida de taxas) fica com o originador.

> [accordion] Posso mandar 100% para outra conta?
>
> Tecnicamente, o máximo por recebedor é `100`, e a soma não pode passar de 100%. Para PSPs, a regra é outra: split de 100% para o PSP não é permitido, e toda transação precisa dividir o valor entre a master e a subconta do lojista.

> [accordion] O split da API substitui a regra padrão ou soma com ela?
>
> Substitui. A configuração enviada na cobrança vale só para ela e prevalece sobre a regra padrão.

> [accordion] Quando o recebedor vê o dinheiro?
>
> Na liquidação de cada parcela do originador: no cartão, em D+30 para a 1ª parcela, D+60 para a 2ª e assim por diante; no Pix, no mesmo dia, logo após a confirmação. Se o originador antecipar, o repasse acontece na antecipação.

> [accordion] Quem paga as taxas da Finvia na venda com split?
>
> Com a base líquida (o padrão), a taxa transacional é descontada antes da divisão, e todos os participantes recebem o percentual deles sobre o que sobra. Se o originador antecipar, a taxa de antecipação também reduz a base. A base bruta e a opção de a master absorver a taxa de antecipação das subcontas existem sob consulta.

## Como testar

Cenários do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md), seção de cobrança com split:

| Código | O que comprovar |
| - | - |
| SPL-01 | Cobrança com split para 1 recebedor (ex.: 30%), aprovada, e `GET /v1/charges/{id}` mostrando `splits` com `destinyMerchantId` e `splitPercentage` |
| SPL-02 | Split para 2 ou mais recebedores somando até 100% |
| SPL-03 | Percentual inválido (0, acima de 100 ou soma inconsistente) rejeitado pela API |
| SPL-04 | `merchantId` inexistente ou fora do grupo rejeitado pela API |
| SPL-05 | `splitPercentage` e `splitAmount` coerentes com a base (`referenceAmount`). Antes da liquidação, `splitAmount` pode ser menor por causa da simulação de antecipação |
| SPL-06 | Split em Pix e em cartão parcelado, se usar os dois |
| FC-05, FC-06 | Cobrança criada com a chave da subconta e cobrança com split entre subcontas do grupo |

## Veja também

> [card] [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
>
> Como transformar uma comissão sobre o bruto no percentual correto.

> [card] [Taxas da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md)
>
> De onde vêm as taxas que definem o valor líquido.

> [card] [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Referência completa, incluindo o campo `split`.

> [card] [Marketplace e PSP](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)
>
> Caso de uso completo com subcontas e split.


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