Split de pagamento para marketplace: como montar no Pix

Split de pagamento para marketplace é dividir o valor de cada venda entre os vendedores e a plataforma no próprio pagamento, sem receber tudo numa conta e repassar depois. O comprador paga um único Pix. Quando o pagamento é confirmado, a parte de cada vendedor cai no saldo dele, e a comissão fica com o marketplace. Na xFlow Payments, isso é feito com o campo splits na criação da cobrança.

Se você chegou aqui procurando o split payment da reforma tributária, que recolhe IBS e CBS, a diferença está em split de pagamento x split payment.

Por que marketplace precisa de split

Sem split, o marketplace recebe o dinheiro do comprador e depois transfere a parte de cada vendedor. Isso traz três problemas:

• Trabalho operacional. Cada repasse é uma transferência a mais para controlar.
• Risco de erro. Valor errado ou repasse esquecido viram atrito com o vendedor.
• Dinheiro de terceiros no seu saldo. A parte dos vendedores passa pela conta do marketplace antes de chegar a eles.

Com split, a divisão acontece na confirmação do pagamento, e cada um recebe a própria parte.

Como montar o split na xFlow, passo a passo

1. Cada vendedor cria a conta dele

O recebedor do split precisa ser uma conta da xFlow ativa e diferente da conta do marketplace. Cada vendedor cria a conta e passa a você o id da empresa dele, que aparece em GET /api/v1/company. Esse id é o recipient_id.

2. Defina a regra de comissão

Escolha como a divisão é calculada:

A soma dos percentuais não pode passar de 100. O que sobra depois das partes dos recebedores fica com o marketplace.

3. Envie o split na cobrança

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-3344" \
  -d '{
    "amountCents": 15000,
    "customer": { "name": "Comprador", "email": "comprador@exemplo.com", "document": "00000000000" },
    "description": "Pedido #3344",
    "external_reference": "pedido-3344",
    "splits": [
      { "recipient_id": "id-do-vendedor-1", "type": "PERCENTAGE", "percent": 85 }
    ]
  }'

Nessa cobrança de R$ 150,00, o vendedor 1 recebe 85% do valor líquido (o valor da cobrança menos a taxa). O marketplace fica com o restante. A reserva da conta, quando existe, incide só sobre a parte que sobra para o marketplace.

4. Mostre o QR Code ao comprador

A resposta traz pix.copyPaste e pix.qrCodeBase64. O comprador vê o valor cheio do pedido e paga um único Pix.

5. Receba a confirmação

Quando o pagamento é conferido na adquirente, a xFlow credita cada recebedor no próprio saldo e envia o webhook transaction.paid ao marketplace, com o valor (amount), o líquido (net) e a taxa (fee). O guia de webhook Pix mostra como validar a assinatura.

6. Cada vendedor saca o próprio saldo

O vendedor saca por Pix, pelo painel ou pela API, com POST /api/v1/transfers. O marketplace não precisa intermediar o repasse. O passo a passo do saque está em API de saque Pix.

Pedido com mais de um vendedor

Um carrinho com produtos de vendedores diferentes pode virar uma cobrança só, com um item de split para cada vendedor:

"splits": [
  { "recipient_id": "id-do-vendedor-1", "type": "PERCENTAGE", "percent": 50 },
  { "recipient_id": "id-do-vendedor-2", "type": "PERCENTAGE", "percent": 35 },
  { "recipient_id": "id-do-parceiro", "type": "FIXED", "amount": 500 }
]

Calcule as porcentagens no seu sistema a partir do peso de cada vendedor no pedido. O total dos percentuais aqui é 85, dentro do limite de 100.

Split na cobrança ou regra da conta

Há dois jeitos de aplicar a divisão:

• Na cobrança, com o campo splits em cada POST /api/v1/charges. É o caminho natural para marketplace, porque cada pedido pode ter vendedores e valores diferentes.
• Como regra padrão da conta, configurada com a equipe da xFlow. Serve quando a divisão é sempre a mesma, como a comissão fixa de um parceiro em todas as vendas.

Na dúvida, comece pelo split na cobrança: a regra fica no seu sistema, junto com a lógica do pedido, e você controla cada venda.

Testando o fluxo sem o split

Como o split não roda no ambiente de teste, separe a homologação em duas partes. No sandbox, com chaves pk_test_ e sk_test_, teste a criação da cobrança, a exibição do QR Code, a simulação do pagamento com POST /api/v1/test/charges/{id}/pay e o recebimento do webhook com livemode: false. Em produção, faça as primeiras vendas com split em valores baixos e confira o saldo de cada recebedor.

Cuidados antes de ir para produção

• Split inválido não cria a cobrança. Soma acima de 100, recebedor inativo ou igual ao emissor retornam 400.
• Sandbox sem split. Com chave de teste, cobranças com splits retornam 400. Teste o fluxo de cobrança e de webhook no sandbox e ative o split em produção.
• Estorno total. O estorno é total, uma vez por cobrança paga, até 90 dias após o pagamento. Defina com os vendedores como fica a devolução antes de vender.
• Idempotência. Use um Idempotency-Key por pedido para não gerar duas cobranças num retry.
• Rastreio por pedido. Grave o número do pedido em external_reference. Ele volta em toda resposta e webhook e pode ser usado como filtro na listagem.

Conciliação do marketplace

Para fechar o mês, cruze o external_reference de cada cobrança com o seu pedido, use net e fee do webhook para saber quanto ficou com o marketplace e confira o pix.endToEnd com o extrato. O guia de conciliação de pagamentos detalha o processo. Para ver tudo o que a xFlow oferece para marketplaces, acesse xFlow para marketplaces e split de pagamento.