Como criar um marketplace usando subconta da Woovi?

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?

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.

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

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

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

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
• Pelo painel: 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

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.

• Pela API: consulte o saldo e o extrato de cada subconta.
  • Documentação: Saldo e detalhes da subconta

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

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

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