Se você opera um marketplace, ou seja, uma plataforma que conecta compradores e vendedores e fica com uma comissão, as **subcontas da Woovi** permitem receber o pagamento do comprador e distribuir o valor entre todas as partes da venda, com controle de cada repasse.

Neste artigo você vai entender como o modelo funciona e qual é o passo a passo para montar a operação.

**Atenção: a estrutura contábil e fiscal do marketplace deve ser validada com o contador da sua empresa.** Veja também: [Como criar um marketplace da forma correta do ponto de vista contábil e fiscal?](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-criar-um-marketplace-da-forma-correta-do-ponto-de-vista-contabil-e-fiscal)

## Como funciona

A subconta é uma **conta gráfica, administrativa**, dentro da conta principal do marketplace. Ela não é uma conta bancária separada: serve para organizar quanto do saldo pertence a cada parte da venda.

1. O comprador paga uma cobrança Pix gerada pelo marketplace.
2. O valor entra na conta principal do marketplace e é distribuído entre as subcontas conforme as regras de split que você enviou na cobrança.
3. O saldo de cada subconta fica **reservado**: ele aparece no saldo total da conta, mas não entra no saldo disponível para saques e pagamentos da conta principal.
4. Quando for a hora de repassar, você faz o **saque da subconta** para a chave Pix cadastrada nela, que pode ser do vendedor, do comissionado ou de outra conta sua.

Cada subconta é identificada por uma **chave Pix**, que é também o destino do saque. Por isso, cada recebedor (vendedor, intermediário, comissionado) tem uma única subconta, mesmo que participe de várias vendas.

![Como o dinheiro circula em um marketplace com subcontas](https://chat.woovi.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBZ0t0IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--364bbab3045b17aa0db90528d14e151d58583c7a/marketplace-subconta-fluxo.png)

## Antes de começar

* **Tenha uma conta nominal ao marketplace.** O ideal é que a operação do marketplace fique em uma conta separada da operação do dia a dia da empresa, o que facilita a conciliação.
* **Ative as subcontas.** A funcionalidade precisa estar habilitada na sua conta. Veja [como ativar o split para subcontas](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/ativando-split-subcontas-na-plataforma) ou fale com o nosso time.
* **Crie uma chave de API (AppID)** com as permissões de cobrança e de subconta.

## Passo a passo

### 1. Crie as subcontas dos recebedores

Cadastre uma subconta para cada parte que vai receber, informando a chave Pix e um nome que ajude a identificá-la.

* Documentação: [Como criar uma subconta](https://developers.woovi.com/docs/subaccount/how-to-create-a-subbaccount)

A chave Pix precisa ser válida, pois é para ela que o saque será enviado.

### 2. Gere a cobrança com o split

Na criação da cobrança, envie a lista de `splits` com o valor de cada recebedor. A lista pode mudar a cada venda: uma venda pode ter só o vendedor e o marketplace, e outra pode incluir um ou mais comissionados.

```
{
  "correlationID": "pedido-12345",
  "value": 100000,
  "splits": [
    { "pixKey": "chave-do-vendedor", "value": 85000, "splitType": "SPLIT_SUB_ACCOUNT" },
    { "pixKey": "chave-do-comissionado", "value": 5000, "splitType": "SPLIT_SUB_ACCOUNT" }
  ]
}
```

Os valores são em centavos. A soma dos splits não pode ultrapassar o valor da cobrança, e o que não for distribuído permanece na conta principal do marketplace.

* Documentação: [Como criar uma cobrança com split para subconta](https://developers.woovi.com/docs/subaccount/how-to-create-charge-with-split-to-subbaccount-using-api)

**Dica:** use o `correlationID` para identificar a venda ou o pedido no seu sistema. Ele volta em todos os eventos dessa cobrança e é a principal chave de conciliação.

### 3. Confirme o pagamento

Quando o comprador paga, você recebe o webhook `OPENPIX:CHARGE_COMPLETED` com o `correlationID`, os dados do pagador e a lista de splits. A partir desse momento os valores já estão nas subcontas.

* Documentação: [Eventos de webhook](https://developers.woovi.com/webhook-events)

### 4. Faça o repasse para as partes

Quando quiser liberar o valor, solicite o saque da subconta pelo painel ou pela API. Pela API, é possível sacar o saldo total ou apenas uma parte dele.

* Documentação: [Como realizar o saque de uma subconta via API](https://developers.woovi.com/docs/subaccount/how-to-withdraw-from-subaccount-using-api)
* Pelo painel: [Como realizar o saque de uma subconta?](https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-realizar-o-saque-de-uma-subconta)

O resultado do saque chega pelos webhooks `OPENPIX:MOVEMENT_CONFIRMED` (saque concluído) e `OPENPIX:MOVEMENT_FAILED` (saque não realizado, com o motivo).

O saque não é automático: é a sua plataforma que decide o momento do repasse. Você pode repassar logo após o pagamento, em uma data fixa (semanal, mensal) ou só depois que a venda for concluída, por exemplo após a entrega do produto.

## Quando usar a transferência entre subcontas

Na maioria dos marketplaces, a divisão já é conhecida na hora da venda e o split da cobrança resolve tudo. A **transferência entre subcontas** é útil quando a divisão só é definida depois do pagamento, por exemplo quando a comissão depende de uma confirmação ou quando um valor precisa mudar de recebedor.

* Documentação: [Como transferir entre subcontas](https://developers.woovi.com/docs/subaccount/how-to-make-a-transfer-between-subaccounts)

A transferência aceita um `correlationID` próprio. Use o identificador da venda para facilitar a conciliação.

## Acompanhando saldos e conciliando

* **Pelo painel:** em **Contas > Detalhes da conta** você vê o saldo total, o saldo das subcontas, o saldo bloqueado e o saldo disponível. Na aba **Subcontas** você vê as entradas e saídas de cada uma.

![Os saldos da conta do marketplace](https://chat.woovi.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBZ090IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--283d031388137269323a32d316f9f39c5962b80e/marketplace-subconta-saldos.png)

* **Pela API:** consulte o saldo e o extrato de cada subconta.
  * Documentação: [Saldo e detalhes da subconta](https://developers.woovi.com/docs/subaccount/how-to-get-balance-and-details-of-subaccount-using-api)

Para conciliar por venda, guarde no seu sistema o `correlationID` de cada cobrança e de cada transferência, além do identificador retornado em cada saque.

## Devoluções

Se uma venda for cancelada, a devolução ao comprador pode ser feita pelo **estorno da cobrança**, que devolve o valor para a conta de origem do pagamento. O estorno pode ser total ou parcial.

* Documentação: [Como criar um reembolso de cobrança](https://developers.woovi.com/docs/refund/charge-refund-create-api)

Lembre-se de ajustar também o saldo da subconta envolvida na venda, para que o valor devolvido não continue reservado para o recebedor.

## Taxas

As taxas da Woovi são cobradas no **recebimento** da cobrança e em **cada saque** de subconta, conforme o plano da sua conta. A taxa do saque é debitada do saldo disponível da conta principal, e o valor enviado ao recebedor não é descontado.

## Resumo

| Etapa | O que fazer |
|---|---|
| Preparação | Conta nominal ao marketplace e subcontas ativadas |
| Cadastro | Uma subconta por recebedor, vinculada à chave Pix dele |
| Venda | Cobrança Pix com `splits` e `correlationID` da venda |
| Confirmação | Webhook `OPENPIX:CHARGE_COMPLETED` |
| Repasse | Saque da subconta (total ou parcial), no momento que você definir |
| Ajustes após a venda | Transferência entre subcontas (opcional) |
| Cancelamento | Estorno da cobrança e ajuste da subconta |

Ficou com alguma dúvida? Fale com o nosso time pelo chat.