xFlow para marketplaces

Um marketplace precisa receber do comprador, separar a parte de cada vendedor e ficar com a comissão, sem planilha no meio. Na xFlow Payments, isso acontece na própria cobrança Pix: você envia o split de pagamento ao criar a cobrança, e quando o pagamento é confirmado cada vendedor é creditado no próprio saldo. O que sobra é a parte do marketplace.

As dores de quem opera um marketplace

• Repasse manual. Receber tudo numa conta e depois transferir para cada vendedor dá trabalho e abre espaço para erro.
• Comissão que muda. Cada categoria, vendedor ou campanha pode ter uma comissão diferente.
• Conciliação por pedido. É preciso saber quanto de cada pedido foi para quem.
• Vendedor cobrando o repasse. Quando o dinheiro demora a aparecer, o suporte do marketplace recebe a pressão.
• Queda de provedor. Se o Pix para, o checkout inteiro para junto.

Recursos da xFlow que resolvem

Fluxo de exemplo: um pedido, dois vendedores

1. O comprador fecha um carrinho com produtos de dois vendedores, no total de R$ 200,00.
2. O marketplace chama POST /api/v1/charges com amountCents: 20000, o external_reference do pedido e o campo splits.
3. A API devolve o QR Code e o copia e cola. O comprador paga um único Pix.
4. A xFlow confere o pagamento na adquirente.
5. Cada vendedor é creditado no saldo dele, conforme o split. O restante fica no saldo do marketplace.
6. O webhook transaction.paid avisa o marketplace, que atualiza o pedido.
7. Cada vendedor saca o próprio saldo por Pix, pelo painel ou pela API.

"splits": [
  { "recipient_id": "id-do-vendedor-1", "type": "PERCENTAGE", "percent": 45 },
  { "recipient_id": "id-do-vendedor-2", "type": "PERCENTAGE", "percent": 40 }
]

Nesse exemplo, o vendedor 1 recebe 45% do valor líquido, o vendedor 2 recebe 40% e o marketplace fica com o restante. Se a comissão for um valor fixo, use "type": "FIXED" com amount em centavos. O passo a passo completo, com os cuidados de cada etapa, está em split de pagamento para marketplace.

Regras que você precisa conhecer

• Cada vendedor precisa ter conta na xFlow, ativa e diferente da conta do marketplace.
• A soma dos percentuais não pode passar de 100.
• Split inválido retorna 400, e a cobrança não é criada.
• No ambiente de teste, cobranças com splits retornam 400. Teste o restante da integração no sandbox e use o split em produção.
• A reserva da conta, quando existe, incide só sobre a parte que sobra para o marketplace.

Contingência para o checkout não parar

O split não depende de uma adquirente específica. A cobrança com splits passa pelo mesmo roteamento por regras das outras cobranças da conta, entre as 11 adquirentes da xFlow. Se a adquirente escolhida não responde, a xFlow tenta de novo e, se precisar, gera a cobrança na próxima da cadeia. O comprador recebe o QR Code normalmente, e a divisão entre os vendedores continua a mesma. Para um marketplace, isso significa que uma instabilidade em um provedor não precisa parar o checkout de todos os vendedores ao mesmo tempo.

Conciliação sem planilha

Cada cobrança traz o id da xFlow, o seu external_reference, o pix.endToEnd e os dados de quem pagou em payer. O webhook transaction.paid traz o valor (amount), o líquido (net) e a taxa (fee). Com isso, o marketplace fecha o pedido sem cruzar extratos à mão. Veja como em conciliação de pagamentos.

Como começar

Crie a conta do marketplace, integre a API Pix com uma chave de teste e, quando estiver pronto, peça aos vendedores que criem as contas deles para receber o split.