> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Nov 03, 2026 - Taxa da plataforma por seller

> Taxa da plataforma própria para cada seller da subconta, com a conta feita seller a seller e o detalhe por seller na resposta da cobrança.

export const AuthorProfile = ({author}) => <div className="flex flex-row gap-3 items-center">
    {author.image && <img src={author.image} alt={author.name} className="w-10 h-10 rounded-full m-0" />}
    <div>
      <a href={author.url}>{author.name}</a>
      <br />
      <span>{author.title}</span>
    </div>
  </div>;

export const lucas = {
  name: "Lucas Saraiva",
  title: "Software Engineer",
  url: "https://github.com/lucassaraiva5",
  image: "https://github.com/lucassaraiva5.png"
};

<div className="flex flex-row gap-4">
  <AuthorProfile author={lucas} />
</div>

A [taxa da plataforma](/documentations/split/platform-fee) agora pode ser definida por seller. Um seller da subconta pode ter taxa própria em um ou mais métodos, e onde ele não tem regra própria continua valendo a taxa da subconta. Esta release também encerra a regra genérica (`default`) e, com a taxa ligada, passa a recusar algumas vendas com split, como descrito abaixo.

## Regras por seller

As regras do seller são cadastradas em `/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee`, com `POST`, `GET` e `PUT`, nas mesmas formas de corpo das regras da subconta. A regra do seller substitui a da subconta para ele, método a método e só nas parcelas que ela cobre.

* No Pix e no boleto, o seller aceita percentual, valor fixo ou os dois.
* No crédito, a regra do seller é só percentual por parcela.
* Para isentar um seller num método, cadastre `percentage: 0` e `fixedAmount: 0`. Para ele voltar à taxa da subconta, apague a regra dele.
* O seller precisa estar cadastrado na subconta da regra.

## Conta seller a seller

Quando algum seller da cobrança tem regra própria, a taxa de cada seller incide sobre a parte bruta dele. O valor fixo da regra da subconta é cobrado uma vez e rateado só entre os sellers que usam a regra da subconta. Cada seller precisa receber ao menos R\$ 0,01.

Numa cobrança Pix de R\$ 100,00 dividida em 50%, 30% e 20%, com a subconta cobrando 1,09% mais R\$ 0,30 e o primeiro seller com R\$ 0,39 fixos no Pix, os sellers recebem R\$ 49,61, R\$ 29,50 e R\$ 19,67, e a plataforma fica com R\$ 1,22.

O objeto `platformFee` da cobrança ganha `lines`, com a regra, a parte bruta, a taxa e o valor recebido de cada seller.

## Mudanças para quem usa a taxa da plataforma

<Warning>
  **Validações com a taxa ligada:** em toda subconta com a taxa ligada, mesmo sem regra de seller, a cobrança com split passa a ser recusada com `422` quando tem seller repetido, seller de outra subconta ou sem subconta, ou provedores com split diferente. No split por percentual, a cobrança em que algum seller ficaria com menos de R\$ 0,01 depois da taxa também é recusada, com `platform_fee_exceeds_amount`. Com a taxa desligada, nada muda.

  **Split por percentual:** com regra de seller na cobrança, o split precisa ser por percentual. Split por valor é recusado com `platform_fee_requires_percentage_split`.

  **Venda sem split:** com a taxa ligada, a cobrança sem `splitRules` paga a taxa pelo único seller ativo da subconta, que recebe o valor já líquido da taxa. Sem exatamente um seller ativo, a cobrança é recusada com `422` e `platform_fee_seller_not_active`, e `error.context.reason` diz o motivo. A venda Apple Pay continua sem taxa.

  **O que fazer:** confira os códigos em [Erros](/documentations/split/platform-fee#erros).
</Warning>

## Fim da regra genérica

A regra `paymentMethod: default` deixa de existir. Antes de ela sair, a Malga converteu cada regra `default` em regras por método, com o mesmo valor, nos métodos que a subconta oferece. No crédito, a conversão gravou uma regra sem `installment`, que vale para toda parcela sem regra própria. A taxa dessas vendas não mudou.

<Warning>
  **Cadastro:** `POST` e `PUT` com `paymentMethod: default`, na subconta ou no seller, respondem `400` com `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED`, e nada é gravado.

  **Venda sem regra:** com a taxa ligada, a venda, com ou sem split, num método ou numa parcela que não tem regra na subconta nem no seller é recusada com `422` e `platform_fee_rule_not_configured`. Antes, ela usava a regra `default` ou passava sem taxa.

  **O que fazer:** troque `default` por uma regra para cada método que você vende e cadastre a tabela de crédito de 1x a 24x, ou ao menos até o maior número de parcelas que você vende. O `GET /v1/merchants/{merchantId}/platform-fee` mostra em `coverage` o que ainda está sem regra.
</Warning>

<Tip>
  Principais novidades:

  <ul>
    <li>Rotas de regra de platform fee por seller, com isenção por método.</li>
    <li>`sellerRules` e `coverage` com o estado de cada método e parcela no `GET /v1/merchants/{merchantId}/platform-fee`.</li>
    <li>`platformFee.lines` na cobrança, com a taxa de cada seller.</li>
    <li>`error.context` nas recusas da taxa, com os valores em campos.</li>
    <li>Fim da regra genérica `default`, com recusa da venda com split sem regra para o método ou a parcela.</li>
  </ul>
</Tip>

<Info>Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io).</Info>


## Related topics

- [Realizar nova cobrança](/api-reference/charges/realizar-nova-cobranca.md)
- [Taxa da plataforma](/documentations/split/platform-fee.md)
- [June 18, 2026 - Platform Fee](/release-notes/2026-06-18-Release-Notes.md)
- [Abr 30, 2026 - APIs de payouts e novo campo totalPaidAmount](/release-notes/2026-04-30-Release-Notes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.