Skip to main content
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.
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.

​
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, a taxa é definida por parcela: cada número de parcelas, de 1x a 24x, pode ter um valor diferente.
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: percentual, valor fixo ou os dois combinados. O corpo da requisição aceita um array de regras ou um objeto com a lista em rules. Os dois exemplos abaixo têm o mesmo efeito:
A regra default é obrigatória na primeira configuração e não pode ser removida. Ela funciona como fallback: cobre o método de pagamento que não tem regra própria e, no cartão de crédito, a parcela que não tem regra própria.
Consulte o contrato completo em Criar regras de platform fee.

​
Taxa de crédito por parcela

No cartão de crédito, cada número de parcelas tem a própria taxa, de 1x a 24x. Uma regra com installment: 3 vale só para vendas em 3x, e a taxa de 3x pode ser diferente da taxa de 2x e da de 4x. A taxa incide sobre o valor total da venda, e não sobre o valor de cada parcela:
Numa venda de R$ 1.000,00 em 12x com taxa de 24,30%, a plataforma retém R$ 243,00 e os recebedores dividem R$ 757,00. Você pode cadastrar a tabela de crédito parcela a parcela ou por fórmula. Nos dois casos, a Malga grava uma regra por parcela, e é essa tabela que a cobrança usa.

​
Cadastrando a tabela parcela a parcela

A mesma tabela pode ser escrita de três formas. Use uma forma por objeto de regra.
Use installmentRates quando a tabela só tem percentual. A posição na lista é o número de parcelas: o primeiro item vale para 1x, o segundo para 2x, e assim por diante, até 24 itens.
A requisição grava 12 regras de crédito, de 1x a 12x. As parcelas gravadas por installmentRates ficam sem valor fixo.A regra de tabela curta aceita só paymentMethod e installmentRates. Qualquer outra chave no mesmo objeto recusa a requisição com 400, em vez de ser ignorada.
A mesma parcela não pode aparecer duas vezes no corpo. O mesmo método também não pode aparecer duas vezes como tabela, nem como tabela e regra avulsa, na mesma requisição. Se alguma parcela já tiver regra, o POST retorna 409: para alterar uma tabela existente, use o PUT, descrito em Atualizando a tabela de crédito.

​
Cadastrando a tabela por fórmula

Quando a taxa segue uma regra de crescimento, envie a fórmula e a Malga gera a tabela. A fórmula é calculada no cadastro: o que fica gravado é uma regra por parcela, de 1x até maxInstallments, e a fórmula em si não é armazenada. Os modos de crescimento em growth.mode: Para cada parcela, a conta segue esta ordem:
  1. Parte da base.
  2. Aplica o crescimento, se a parcela for igual ou maior que growth.from.
  3. Soma as sobretaxas cujo fromInstallment já foi alcançado.
  4. Limita ao cap.
  5. Substitui pelo overrides da parcela, se houver.
  6. Arredonda o percentual para 2 casas decimais, com meio para cima.
Exemplo com crescimento linear, uma sobretaxa a partir de 7x e teto:
A requisição grava oito regras de crédito: Em 7x entra a sobretaxa de 0,50 ponto. Em 8x a conta daria 4,69%, e o teto limita o valor a 4,60%. A configuração inteira é recusada com 400 quando:
  • growth.mode é exponential e falta cap.percentage;
  • um item de overrides fica acima do cap;
  • alguma parcela calculada passa de 100%;
  • maxInstallments está ausente ou fora de 1 a 24;
  • uma sobretaxa não tem percentage nem fixedAmount, ou surcharges e overrides repetem a mesma parcela;
  • a regra ou algum objeto da fórmula traz uma chave desconhecida, como capp no lugar de cap. A regra de fórmula aceita só paymentMethod, maxInstallments, base, growth, surcharges, overrides e cap;
  • a fórmula vem fora de credit ou junto com installmentRates, installments, installment, percentage ou fixedAmount.

​
Parcela sem regra própria

A platform fee não recusa uma venda por falta de regra na parcela. Em cada venda no crédito, a cobrança usa a regra da própria parcela e, quando ela não existe, a regra default. Para que cada parcela seja cobrada exatamente como você definiu, cadastre regra própria para todas as parcelas que você vende. Por exemplo, com regras só em 1x, 2x e 7x e uma regra default de 2%: A consulta descrita em Consultando a taxa calculada mostra, parcela por parcela, qual dessas regras a cobrança usa.

​
Atualizando a tabela de crédito

O PUT /v1/merchants/{merchantId}/platform-fee aceita o mesmo corpo do POST, e o efeito depende da forma:
  • Com installmentRates, installments ou fórmula, o PUT substitui a tabela de crédito inteira: atualiza as parcelas que já existem, cria as que faltam e remove as que ficaram de fora. As regras de pix, boleto e default não mudam.
  • Com regra avulsa, o PUT atualiza só a regra da mesma parcela e só os campos enviados. Se a parcela não tiver regra, a resposta é 404.
O PUT é aplicado por inteiro ou não é aplicado. Se qualquer regra avulsa do corpo não existir, a resposta é 404 e nada muda, nem a tabela enviada na mesma requisição. Quando a nova tabela cria uma parcela que ainda não tinha regra, a subconta precisa ter a regra default, como no POST; sem ela, a resposta é 400. A resposta de sucesso traz as regras como ficaram gravadas.
Na substituição, a tabela enviada passa a ser a tabela inteira. Enviar três parcelas numa subconta que tinha doze deixa a subconta com três, e as parcelas removidas passam a seguir a ordem descrita em Parcela sem regra própria.

​
Consultando a taxa calculada

O GET /v1/merchants/{merchantId}/platform-fee devolve as regras gravadas em rules e, junto, a conta feita: quanto a plataforma retém e quanto sobra para os recebedores em cada método e em cada parcela. Informe em simulationAmount o valor da venda simulada, em centavos. Sem o parâmetro, a simulação usa R$ 100,00.
Os blocos simulation, methods e coverage só vêm quando simulationAmount é enviado. Sem ele, a resposta traz apenas platformFeeEnabled e rules. Resposta para a tabela curta de 1x a 12x cadastrada acima, numa venda de R$ 10.000,00. A lista installments traz sempre as 24 parcelas; o trecho abaixo omite rules e mostra 1x, 2x, 12x e 13x:
Campos de cada parcela em installments: Valores de source: Em pix e boleto, os campos de taxa vêm no próprio item do método, e source é rule ou default. No crédito, a origem de cada parcela está em installments[].source. Em coverage.merchant, missing lista os métodos sem nenhuma regra aplicável, e warnings traz avisos em texto, como a flag de ativação desligada ou as parcelas que usam a regra default. Os avisos são para leitura humana: para tratar esses casos no código, use source, accepted e reason. Consulte todos os campos da resposta em Listar 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