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

# June 18, 2026 - Platform Fee

> Taxas de plataforma por método de pagamento nos merchants

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 dennis = {
  name: "Dennis Quintal",
  title: "Software Engineer",
  url: "https://github.com/dennisqq",
  image: "https://github.com/dennisqq.png"
};

export const filippe = {
  name: "Filippe Rodrigues",
  title: "Tech Lead",
  url: "https://github.com/filipperodrigues",
  image: "https://github.com/filipperodrigues.png"
};

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

  <AuthorProfile author={dennis} />
</div>

Novidade na Malga! Agora você pode configurar **taxas de plataforma (platform fee)** diretamente nos seus merchants via API.

Se você opera um marketplace ou plataforma, essa funcionalidade permite definir regras de cobrança por método de pagamento de forma simples e flexível com suporte a percentual, valor fixo ou ambos combinados.

## Como funciona

O platform fee é simples de configurar e opera em dois níveis:

1. **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.
2. **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**.

As regras suportam cobrança por **percentual** (0-100%), **valor fixo** em centavos, ou **ambos combinados** adaptando-se ao modelo de negócio que fizer mais sentido para você.

## Faixas de parcelamento para crédito

Para o método de pagamento `credit`, o campo `installment` é **obrigatório** e o valor informado (1 a 24) é automaticamente associado a uma das quatro faixas:

| Faixa     | Parcelas |
| --------- | -------- |
| À vista   | 1        |
| 2x a 6x   | 2 a 6    |
| 7x a 12x  | 7 a 12   |
| 13x a 24x | 13 a 24  |

Cada merchant pode ter **no máximo uma regra por faixa**. O valor original informado é preservado na resposta da API.

### Exemplo

Se você criar uma regra com `installment: 5`, ela cobrirá a faixa **2x a 6x**. Ao tentar criar outra regra com `installment: 3` (mesma faixa), a API retornará `409 Conflict` com a mensagem indicando que já existe uma regra para a faixa 2x a 6x.

### Outros detalhes

* O método de pagamento `default` **não aceita** o campo `installment`. Ele funciona exclusivamente como regra de fallback para métodos sem regra específica.
* Para `pix` e `boleto`, uma regra por método, sem parcelamento.

## Novos endpoints

* `PATCH /v1/merchants/{merchantId}/platform-fee/enabled`: Ativar ou desativar platform fee
* `POST /v1/merchants/{merchantId}/platform-fee`: Criar regras de taxa
* `GET /v1/merchants/{merchantId}/platform-fee`: Listar regras ativas
* `PUT /v1/merchants/{merchantId}/platform-fee`: Atualizar regras existentes
* `DELETE /v1/merchants/{merchantId}/platform-fee/{platformFeeId}`: Remover regras

Para mais detalhes, consulte a [referência da API](/api-reference/merchants/criar-regras-de-platform-fee).

<Tip>
  Features:

  1. Configuração de taxas de plataforma por método de pagamento (credit, pix, boleto)
  2. Suporte a percentual, valor fixo ou ambos combinados
  3. Regras por faixa de parcelamento para cartão de crédito (à vista, 2x-6x, 7x-12x, 13x-24x)
  4. Ativação/desativação independente via flag no merchant
  5. CRUD completo de regras via API
</Tip>