> ## 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.

# Taxa da plataforma

Configure uma comissão fixa sobre transações com split, aplicada automaticamente em cada cobrança.

A taxa da plataforma `(platform-fee)` permite que intermediadores — marketplaces, SaaS de pagamentos e plataformas B2B — configurem uma comissão persistente sobre as transações dos seus sellers. Em vez de incluir a própria conta nas `splitRules` de cada cobrança, a plataforma define a taxa uma vez na subconta e a Malga aplica automaticamente antes de distribuir o valor restante entre os recebedores.

<Info>
  O `platform-fee` é uma camada sobre o split de provedor. Ele só se aplica quando a cobrança tem `splitRules`. Transações **sem** `splitRules` não sofrem desconto de taxa.
</Info>

## Como funciona

A taxa da plataforma é simples de configurar e opera em dois níveis:

* Ativação: Uma flag no merchant habilita ou desabilita a aplicação das taxas. Enquanto desativada, nenhuma regra é aplicada nas transações, dando total controle sobre quando começar a cobrar.
* Regras por método de pagamento: Cada regra define a taxa para um método específico (`credit`, `pix`, `boleto`). Para cartão de crédito, as regras são configuradas por faixa de parcelamento.

Quando uma cobrança é criada com `splitRules`  e a subconta tem platformFee configurado, a Malga executa o seguinte antes de enviar ao provedor:

1. Calcula o valor da taxa sobre o montante bruto da transação
2. Subtrai esse valor para obter o valor líquido
3. Distribui o valor líquido entre os sellers declarados nas `splitRules`
4. O valor não declarado nos `splitRules` vai para a conta da plataforma

O cliente nunca precisa incluir a própria conta no splitRules — a fatia da plataforma é retida automaticamente.

## Configurando as regras

As regras são configuradas no nível da subconta via API. Cada regra define o método de pagamento e o valor da taxa — em percentual, valor fixo ou ambos combinados. Para cartão de crédito, as regras são configuradas por faixa de parcelamento.

| Campo           | Descrição                                                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentMethod` | Método ao qual a regra se aplica: credit, pix, boleto ou default (fallback).                                                                                               |
| `percentage`    | Percentual da taxa (0-100), com até 2 casas decimais.                                                                                                                      |
| `fixedAmount`   | Valor fixo em centavos. Pode coexistir com percentage na mesma regra.                                                                                                      |
| `installment`   | Número de parcelas. Obrigatório para credit; proibido nos demais métodos. Agrupado em faixas: à vista (1), 2x-6x, 7x-12x, 13x-24x. Apenas uma regra por faixa é permitida. |

<Info>
  A regra `default` funciona como fallback: aplica-se quando não há regra específica para o método da transação. Se nenhuma regra `default` estiver configurada e não houver regra para o método, o platform-fee não é aplicado.
</Info>

Consulte o contrato completo em [Criar regras de platform fee](/api-reference/merchants/criar-regras-de-platform-fee).

## Estornos

Em estornos totais ou parciais, o `platform-fee` é revertido proporcionalmente ao valor estornado.

Exemplo:

* transação de R$ 1.000,00 com platformFee de 2% (plataforma reteve R$ 20,00, seller recebeu R\$ 980,00).
* Estorno parcial de R\$ 500,00:
  * Plataforma devolve: R\$ 10,00
  * Seller devolve: R\$ 490,00


## Related topics

- [Oct 21 - Bandeira de cartão | Painel](/release-notes/2024-10-21-Release-Notes.md)
- [Webhooks v1.1](/documentations/webhooks/webhook1-1.md)
- [Cartão de crédito](/documentations/payment-methods/credit-card.md)
- [Primeiros passos](/documentations/welcome/primeiros-passos.md)