xFlow para plataformas de infoproduto

Uma plataforma de infoproduto vende em nome de milhares de produtores e precisa dividir cada venda entre produtor, coprodutor, afiliado e a própria plataforma. Na xFlow Payments, essa divisão vai na cobrança Pix: você envia o split de pagamento ao criar a cobrança e, quando o pagamento é confirmado, cada parte é creditada no saldo da conta de quem recebe. Por trás da mesma chamada, a cobrança é gerada numa das 11 adquirentes da xFlow, com roteamento por regras e retentativa automática.

O que a plataforma exige do Pix

• Comissões diferentes por venda. Cada produto tem a sua regra de coprodução, e cada venda pode ter ou não um afiliado.
• Repasse sem planilha. Milhares de produtores esperando o dinheiro não combinam com transferência manual.
• Pico de lançamento. Um lançamento concentra vendas em poucas horas, e um provedor instável vira carrinho perdido.
• Clique duplo e reenvio. O comprador ansioso clica duas vezes; a rede cai no meio da chamada.
• Contestação e reserva. Uma venda contestada precisa chegar ao time certo, com os dados do pagamento à mão.

Recursos da xFlow para cada exigência

Split entre produtor, coprodutor e afiliado

A cobrança é criada pela conta da plataforma. Cada participante da venda é um item do splits:

"splits": [
  { "recipient_id": "id-do-produtor", "type": "PERCENTAGE", "percent": 56 },
  { "recipient_id": "id-do-coprodutor", "type": "PERCENTAGE", "percent": 14 },
  { "recipient_id": "id-do-afiliado", "type": "PERCENTAGE", "percent": 20 }
]

Nesse exemplo, o afiliado fica com 20% do líquido, o produtor com 56%, o coprodutor com 14% e a plataforma com os 10% que sobram. Repare na conta do coprodutor: se o contrato diz "20% da parte do produtor" e o produtor tem 70% do líquido, o coprodutor recebe 14% do líquido e o produtor fica com 56%. O percent é sempre sobre o líquido da cobrança, depois da taxa, então converta as regras de comissão antes de enviar. Se uma comissão for valor fixo, use "type": "FIXED" com amount em centavos.

As regras que a sua plataforma precisa respeitar:

• Cada recebedor é uma conta da xFlow ativa e diferente da conta da plataforma. O recipient_id é o id da empresa recebedora, que ela encontra em GET /api/v1/company.
• A soma dos percentuais não passa de 100.
• Split inválido retorna 400, e a cobrança não é criada. Valide antes de chamar.
• No ambiente de teste, cobranças com splits retornam 400. Teste o resto no sandbox e o split em produção.

Como milhares de produtores entram na xFlow, quem é titular de cada conta e como a plataforma recebe cada recipient_id é um desenho combinado com a equipe antes de começar. O passo a passo técnico do split, com os cuidados antes de ir para produção, está em split de pagamento para marketplace.

Repasse: o saldo de cada um

Quando o pagamento é confirmado, a parte de cada recebedor entra no saldo dele. Não há transferência da plataforma para o produtor: o crédito acontece na própria cobrança. Cada produtor, coprodutor ou afiliado saca o saldo por Pix, no painel em Recebimentos > Solicitar saque ou pela API, com a chave dele. A parte da plataforma fica no saldo da plataforma. Pela documentação, a reserva da conta, quando existe, incide só sobre o que sobra para quem criou a cobrança.

Se a plataforma também paga pessoas que não têm conta na xFlow, como afiliados que só informaram uma chave Pix, o caminho é o saque por API. O desenho está em xFlow para plataformas de payout.

Lançamento: volume sem perder venda

• Contingência entre adquirentes. Se a adquirente escolhida pela regra não responder, a cobrança é gerada na próxima da cadeia. O comprador vê um único QR Code. Se nenhuma gerar, a resposta é 502 charge_failed: mostre um botão de tentar de novo e repita com a mesma Idempotency-Key.
• Regras por valor, horário e dia. Uma regra pode mandar o horário do lançamento para uma adquirente e o resto do dia para outra.
• Limite de requisições por conta. Toda resposta autenticada traz x-ratelimit-remaining e x-ratelimit-reset. No 429, espere o retry-after.
• Webhook idempotente. O transaction.paid pode chegar mais de uma vez, porque a entrega é reenviada até 3 vezes sem resposta 2xx. Libere o acesso ao curso uma vez só, pelo id da cobrança. Os detalhes estão em webhook Pix.
• Varredura de segurança. Depois do pico, liste GET /api/v1/charges?status=paid no período e confira se todo pedido pago teve o acesso liberado.

Contestação, estorno e reserva

Quando a conta tem MED ativo, a xFlow envia dispute.opened ao abrir uma contestação e dispute.accepted ou dispute.rejected no desfecho. A defesa é respondida no painel, em Disputas, dentro do prazo. Pela documentação, contas em plano sem MED não precisam agir, porque a equipe da xFlow cuida. O que a integração deve preparar está em MED na integração Pix.

O estorno pela API devolve o valor total da cobrança, uma vez por cobrança, até 90 dias depois do pagamento, com POST /api/v1/charges/{id}/refund. Se o saldo não cobrir, a resposta é 422 insufficient_balance. A documentação não detalha como o estorno de uma cobrança com split afeta o saldo de cada recebedor, então combine essa regra com a equipe antes de operar. As regras gerais estão em estorno Pix por API.

O que a API não faz hoje

A API trabalha com Pix: cobrança, split, estorno total e saque. Cartão, checkout hospedado e assinaturas ainda não estão na API, então a tela de pagamento e a cobrança recorrente ficam com a sua plataforma. Para a tela de pagamento, veja xFlow para plataformas de checkout.

Como começar

Crie uma chave de teste e integre a cobrança no sandbox, mesmo antes da aprovação do cadastro. Em paralelo, fale com a equipe para desenhar a entrada dos produtores e as regras de split. A referência dos campos está na documentação da API.