Pagamentos para marketplace: o split que funciona hoje e o que ainda está no roadmap

Um gateway de pagamento para marketplace precisa fazer três coisas que um gateway comum não faz: dividir cada pedido entre o lojista (seller) e a plataforma no momento do pagamento, cadastrar e verificar sellers sem fila manual, e devolver o dinheiro do comprador tirando a parte certa de cada um no estorno. O HeroPay faz a primeira e a terceira hoje, dentro da plataforma, para parceiros fixos por produto: o split de pagamentos é por percentual, soma 100%, incide sobre o líquido e vale em Pix, cartão e boleto, sem tarifa extra. O que o HeroPay ainda não tem é split por API, com cadastro de recebedor e regra criada pedido a pedido pelo seu código: a exposição do split por API está em evolução, sem data prometida. Se esse é o seu caso, esta página diz com clareza quando o HeroPay já basta, quando não basta e onde acompanhar a entrega.

Criar conta sandbox · Ler a documentação

Quais são as 3 dores de pagamento de um marketplace?

Dor 1: dividir o pedido sem virar banco do seller

A dor em uma frase: sem split, o dinheiro inteiro do pedido cai na conta do marketplace, que vira responsável por guardar e repassar a parte do seller, e ainda fatura sobre um valor que não é dele.

A feature que resolve: o split de pagamentos divide a venda na liquidação. A parte do seller nasce no saldo do seller; a comissão da plataforma nasce no saldo da plataforma. Ninguém repassa nada, e cada um emite nota sobre o que recebeu.

A conta em reais. Pedido de R$ 200 com comissão de 15% para a plataforma:

Tarifas conforme a tabela de preços, verificado em setembro/2026.

O efeito fiscal é o que mais pesa no fim do ano. Um marketplace com R$ 100 mil de pedidos por mês e comissão de 15% que recebe tudo e repassa depois aparece com R$ 100 mil de entrada no mês; com split, a entrada dele é a comissão, perto de R$ 15 mil. É essa diferença que decide faixa do Simples Nacional e teto de MEI (confirme o enquadramento com seu contador; o detalhe está no guia de split para marketplaces).

Limite honesto: o split de hoje é configurado por produto ou oferta, com parceiros fixos. Ele não recebe uma regra nova a cada pedido vinda do seu código, e não aceita comissão em valor fixo (R$ 10 por pedido, por exemplo). Se a sua comissão é fixa, ela precisa ser convertida em percentual por oferta.

Dor 2: colocar seller para vender sem onboarding manual

A dor em uma frase: cada seller novo precisa de conta recebedora, verificação de documento e chave de saque, e fazer isso por planilha e e-mail trava o crescimento do marketplace.

O que existe hoje: no HeroPay, cada participante do split tem a própria conta, criada em modo self-service pelo próprio participante. A chave Pix de saque é cadastrada pela API (POST /financial/pix_accounts) e passa por verificação: o status sai de waiting para approved ou disapproved, e a chave precisa estar no mesmo CPF ou CNPJ do titular. Isso é onboarding do próprio seller, na conta dele, não da plataforma em nome do seller.

O que não existe: endpoint para o marketplace criar a conta do seller, enviar documentos de verificação (KYC) em nome dele ou consultar o saldo de cada seller a partir da conta da plataforma. O cadastro de recebedor pela API está em evolução, sem data.

A conta em reais. Não há tarifa de abertura de conta nem mensalidade por seller: um marketplace com 30 sellers ativos paga R$ 0 de custo fixo de conta. O custo do onboarding hoje é operacional (cada seller cria a própria conta), não financeiro. Para 30 sellers fixos, isso é uma tarde. Para 300 sellers por mês entrando sozinhos, é o motivo para esperar o split por API ou usar outro gateway agora.

Dor 3: estornar sem deixar o prejuízo no colo da plataforma

A dor em uma frase: quando o comprador pede o dinheiro de volta, o marketplace precisa devolver o valor inteiro, mas a maior parte já está no saldo do seller, que pode ter sacado tudo.

A feature que resolve: no split do HeroPay, o estorno é rateado pela mesma regra da venda. Cada participante devolve a própria parte, e o estorno é validado contra o saldo de todos os envolvidos antes de ser processado. A plataforma não banca a parte do seller.

A conta em reais. Estorno do pedido de R$ 200 no Pix com 15% de comissão: o seller devolve R$ 170,00 e a plataforma devolve R$ 30,00. Se o seller tiver só R$ 90 de saldo, o estorno não é processado até o saldo dele cobrir os R$ 170. Por isso o contrato com o seller deve prever o que acontece em reembolso e quanto ele precisa manter de saldo, principalmente se ele saca tudo assim que o dinheiro libera.

O estorno em si é uma chamada à API:

curl -X POST "https://api.beta.heropay.tech/refund" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{ "refund": { "payment_id": 64113 } }'

Trecho da resposta 201 (exemplo da OpenAPI v1):

{
  "data": {
    "id": 64113,
    "status": "refund_analyzing",
    "price_cents": 40000,
    "total_paid_by_buyer": 48000,
    "net_value_cents": 36740,
    "total_fees_cents": 3260,
    "refund_limit_date": "2025-09-17T14:01:52.159-03:00",
    "refund_request_at": "2025-08-29T04:01:20.939-03:00"
  }
}

O pedido de estorno volta como refund_analyzing, e o seu sistema fica sabendo da conclusão pelo webhook refunded. Três regras da v1: não dá para estornar duas vezes, é preciso ter saldo, e existe prazo limite por método (no Pix, até 90 dias; confira o refund_limit_date). Chargeback é outro caminho, disparado pela operadora, e chega pelo webhook chargeback_request; a tarifa de chargeback está na central de ajuda (ajuda.herospark.com). Deixe no contrato com o seller como ele participa de uma contestação.

O HeroPay serve para o meu marketplace?

Depende de como o seu marketplace divide dinheiro. Três formatos, três respostas:

Um ponto que evita um desenho errado: o HeroPay não serve para o marketplace receber tudo e repassar por saque. O saque vai para a chave Pix do próprio titular da conta, no mesmo CPF ou CNPJ, e não para a chave de terceiros. Além disso, é exatamente o modelo que infla o seu faturamento. Se você não pode usar o split, use o formato "cada seller com conta própria".

A configuração de coprodução e afiliação, hoje, é feita na plataforma HeroSpark.

Arquitetura típica: como um marketplace pluga no HeroPay hoje

Para o formato de catálogo curado, que é o que o HeroPay atende inteiro hoje:

1. Plataforma HeroSpark: configure o produto e os parceiros. Cada produto ou oferta tem os seus participantes e percentuais. Isso é feito uma vez, não por pedido.
2. API: gere o link de cada oferta. POST /payment_links cria o checkout com Pix, cartão em até 12x e boleto. Use o parâmetro src para marcar a origem de cada venda (?src=vitrine, ?src=instrutor-ana), que volta no campo cart.src de todo webhook. Detalhes em /link-de-pagamento.
3. Webhook: libere o pedido pelo evento. spark_payment_confirmed diz que o pedido foi pago; refunded e chargeback_request dizem que precisa revogar. Os eventos chegam assinados no header X-HeroPay-Signature (HMAC SHA-256 do corpo bruto) com retry automático. Confie no evento, não no polling. Veja /webhooks.
4. Relatórios: concilie pela API. GET /reports/transaction/paid/revenue_by_offer dá a receita por oferta; GET /reports/transaction/refunded/full_report dá os estornos e chargebacks. Cada participante do split enxerga as próprias vendas na própria conta.
5. Saldo e saque: cada um no seu. Cada participante consulta GET /financial/balance e saca pela própria conta. O marketplace não toca no dinheiro do seller.

O que falta nesse desenho para um marketplace aberto: um passo zero ("crie o recebedor pela API") e um campo de regra de split no passo 2. As duas coisas são a RFC de split por API na comunidade.

Mini-case: uma escola com instrutores parceiros

Uma escola online de fotografia vende cursos de oito instrutores. Cada curso tem um dono (o instrutor) e a escola fica com uma comissão pela vitrine, pelo tráfego e pelo atendimento.

A escola configura cada curso como um produto com coprodução: o instrutor com o percentual dele, a escola com o dela, somando 100%. Ela gera um link por curso pela API e marca a origem com src para saber se a venda veio da vitrine ou do Instagram do instrutor. Quando uma aluna compra no Pix, a tarifa é R$ 0 e o líquido inteiro é dividido na hora: a parte do instrutor aparece no saldo dele, a da escola no dela. O webhook spark_payment_confirmed chega no sistema da escola, que libera o acesso.

Um mês depois, uma aluna pede reembolso dentro da garantia. A escola chama POST /refund; o instrutor devolve a parte dele e a escola a dela, na mesma proporção da venda. No fim do mês, cada instrutor emite nota sobre o que recebeu e a escola sobre a comissão. Ninguém montou planilha de repasse.

Agora a escola quer abrir a vitrine para qualquer fotógrafo se cadastrar sozinho e vender. Aqui o HeroPay de hoje para: não há endpoint para criar o recebedor nem para mandar a regra por pedido. A escola vota na RFC de split por API na comunidade e, se não puder esperar, compara as opções em /melhores-gateways-de-pagamento.

O que o marketplace usa do HeroPay

Como outros gateways atendem marketplace

Se você precisa de split por API hoje, estas são as opções que documentam isso. Verificado em setembro/2026 nas documentações oficiais.

Fontes: Asaas, split · Asaas, preços · Pagar.me, split · iugu, split · Stripe Connect, contas conectadas · Stripe, preços Brasil. Stripe Pix: 1,19% e só por convite; boleto R$ 3,45. Pagar.me e iugu não publicam tabela aberta.

Onde os outros são melhores hoje: marketplace aberto, com sellers criados por API, regra de split por pedido e comissão fixa. Asaas, Pagar.me, iugu e Stripe entregam isso e o HeroPay não. Onde o HeroPay é melhor: marketplace de catálogo curado e de produto digital, em que coprodução e afiliados já vêm prontos, o estorno já é rateado e Pix e boleto custam R$ 0 para todo mundo que divide a venda. A comparação completa com o Asaas está em /comparativos/asaas-vs-heropay.

Comece pelo que já funciona

Crie a conta, monte um produto com dois parceiros e faça um pedido e um estorno no sandbox. Em uma hora você sabe se o split de hoje resolve o seu marketplace. Se não resolver, conte o caso na RFC de split por API.

Criar conta sandbox · Ler a documentação

Continue por aqui: Split de pagamentos · Guia de split para marketplaces · Link de pagamento · Webhooks · Preços · Asaas vs HeroPay · Roadmap na comunidade · Plataformas · Glossário: split de pagamento · Glossário: marketplace · Glossário: chargeback