Skip to main content
Configure uma comissão sobre as transações da subconta, com ou sem 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. Na cobrança com splitRules, a taxa sai da parte dos sellers do split. Na cobrança sem splitRules, com a taxa ligada, a Malga cobra a taxa do único seller ativo da subconta, como descrito em Venda sem split.

​
Como funciona

A taxa da plataforma é simples de configurar e opera em três 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). Não existe regra genérica: cada método que você vende precisa de regra própria. 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. A venda Apple Pay não paga a taxa da plataforma, com ou sem split.
  • Regras por seller: Um seller da subconta pode ter taxa própria em um ou mais métodos. Onde ele não tem regra própria, vale a regra da subconta. Veja Taxa por seller.
Quando uma cobrança é criada com splitRules e a subconta tem a taxa ligada, 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 nas splitRules — a fatia da plataforma é retida automaticamente. Quando algum seller da cobrança tem regra própria para o método e a parcela, a conta é feita seller a seller, como descrito em Conta por seller. Sem splitRules, a cobrança paga a taxa pelo único seller ativo da subconta, como descrito em Venda sem split.

​
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, com até 50 objetos de regra. Uma tabela ou fórmula de crédito conta como um objeto. Um corpo com mais de 50 é recusado com 400. Os dois exemplos abaixo têm o mesmo efeito:
Cadastre regra para cada método que você vende e, no crédito, para cada parcela. 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, como descrito em Parcela sem regra própria.
Consulte o contrato completo em Criar regras de platform fee.

​
Regra default descontinuada

A regra genérica paymentMethod: default não existe mais. 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 da subconta. Essa regra aparece em rules sem o campo installment, e não é criada pela API: a regra avulsa de crédito exige installment. POST e PUT com paymentMethod: default, na subconta ou no seller, respondem 400 com PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED, e nada é gravado. Cadastre regra para todo método e parcela que você vende, na subconta ou no seller, e use coverage para conferir o que falta.

​
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

Com a taxa ligada, a venda no crédito, com ou sem split, precisa de regra para a parcela vendida, na subconta ou no seller. Quando nenhuma das duas cobre a parcela, a cobrança é recusada com 422 e platform_fee_rule_not_configured, e error.context diz o seller, o método e a parcela. Vale o mesmo para Pix e boleto sem regra. Cadastre a tabela de crédito de 1x a 24x, ou ao menos até o maior número de parcelas que você vende. Por exemplo, com regras de crédito só em 1x, 2x e 7x: Resposta da cobrança com split em 18x, sem regra para 18x na subconta nem no seller:
A consulta descrita em Consultando a taxa calculada mostra, parcela por parcela, qual regra a cobrança usa e quais parcelas ficam sem regra.

​
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 e boleto não mudam, nem a regra de crédito sem installment, quando a subconta tem uma, como descrito em Regra default descontinuada.
  • 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. 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. As parcelas removidas deixam de ter regra própria na subconta e, sem outra regra que as cubra, a venda nelas é recusada com a taxa ligada, como descrito 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.
Os blocos simulation e methods só vêm quando simulationAmount é enviado. platformFeeEnabled, rules, sellerRules e coverage vêm sempre. sellerRules e o estado por seller estão descritos em Consultando as regras dos sellers. 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. A subconta não tem regra de 13x a 24x, e essas parcelas vêm com accepted: false, reason: no_rule_configured e sem os campos de taxa. O trecho abaixo omite rules, sellerRules e coverage.merchant.methods e mostra 1x, 2x, 12x e 13x:
Campos de cada parcela em installments: Em pix e boleto, os campos de taxa vêm no próprio item do método, com source: rule. Sem regra, o item vem só com { "paymentMethod": "boleto", "accepted": false, "reason": "no_rule_configured" }, e o método entra em coverage.merchant.missing. 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, warnings traz avisos em texto, como a flag de ativação desligada ou as parcelas de crédito sem regra, e methods traz o estado de cada método e faixa de parcelas. Os avisos são para leitura humana: para tratar esses casos no código, use source, accepted, reason e coverage.merchant.methods. Consulte todos os campos da resposta em Listar regras de platform fee.

​
Taxa por seller

Um seller da subconta pode ter taxa própria, diferente da taxa da subconta. A regra do seller substitui a regra da subconta para ele, método a método e só nas parcelas que ela cobre. O que a regra do seller não cobre continua seguindo a regra da subconta. Por exemplo, um seller com regra própria só no Pix paga a própria taxa no Pix e a taxa da subconta no boleto e no crédito. Um seller com tabela de crédito própria de 1x a 4x, numa subconta com tabela de 1x a 12x, paga a própria taxa de 1x a 4x e a da subconta de 5x a 12x. Antes de começar:
  • O seller precisa estar cadastrado na subconta em que você vai criar a regra. Seller de outra subconta, sem subconta ou de outro cliente responde 404 com PLATFORM_FEE_SELLER_NOT_FOUND.
  • A flag de ativação continua sendo da subconta e vale para todos os sellers dela. Não existe flag por seller.
  • Para ligar a taxa, a subconta precisa ter ao menos uma regra própria. Regras de seller não contam. Com a taxa ligada, a última regra da subconta não pode ser apagada: o DELETE responde 400 com PLATFORM_FEE_RULES_REQUIRED_WHILE_ENABLED.

​
Criando as regras de um seller

As regras do seller usam as mesmas formas de corpo das regras da subconta: regra avulsa, installmentRates, installments e fórmula, em array ou em objeto com a lista em rules, com o mesmo limite de 50 objetos. Como na subconta, paymentMethod: default é recusado com 400 e PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED. A diferença está no crédito: a regra do seller é só percentual por parcela. Qualquer fixedAmount diferente de 0 no crédito do seller recusa a requisição com 400. No Pix e no boleto, o seller aceita percentual, valor fixo ou os dois.
Resposta 201, com as regras gravadas e um aviso fixo sobre assinaturas:
Neste exemplo, o seller fica isento no Pix, paga 1,99% em 1x e 2,49% em 2x, e segue a subconta no boleto e de 3x a 24x. O GET na mesma rota lista as regras próprias do seller, e o PUT altera as regras dele com as mesmas regras do PUT da subconta: a regra avulsa altera só os campos enviados, e a tabela de crédito substitui a tabela do seller inteira, sem mexer na da subconta. Consulte o contrato completo em Criar regras de platform fee do seller.

​
Isentando um seller ou devolvendo à regra da subconta

  • Isentar num método: regra do seller com percentage: 0 e fixedAmount: 0, os dois na mesma requisição. Um PUT só com percentage: 0 numa regra que tinha valor fixo continua cobrando o valor fixo.
  • Voltar à regra da subconta: apague a regra do seller pelo id, com DELETE /v1/merchants/{merchantId}/platform-fee/{platformFeeId}. A mesma rota apaga regras da subconta e de seller.
Mudanças nas regras valem a partir da próxima cobrança. Cobranças já feitas não mudam.

​
Como a cobrança escolhe a regra de cada seller

Para cada seller do split, na ordem:
  1. A regra do seller para o método e a parcela da cobrança.
  2. A regra da subconta para o método e a parcela. No crédito, sem regra para a parcela, vale a regra de crédito sem installment da subconta, quando ela existe.
  3. Nenhuma: a cobrança é recusada com 422 e platform_fee_rule_not_configured, dizendo o seller, o método e a parcela.

​
Conta por seller

Quando algum seller da cobrança tem regra própria para o método e a parcela, a conta é feita seller a seller:
  • O percentual da regra incide sobre a parte bruta de cada seller, e a taxa de cada seller arredonda para baixo. O centavo do arredondamento fica com o seller.
  • O valor fixo da regra do seller é cobrado inteiro dele.
  • O valor fixo da regra da subconta é cobrado uma vez por cobrança e rateado, proporcional à parte bruta, só entre os sellers que usam a regra da subconta. O centavo que sobra do rateio fica com os sellers.
  • Cada seller precisa receber ao menos R$ 0,01. Senão, a cobrança é recusada com platform_fee_exceeds_amount.
Exemplo: Pix de R$ 100,00 com split de 50%, 30% e 20%. A subconta cobra 1,09% mais R$ 0,30 no Pix. O seller A tem regra própria de Pix só com R$ 0,39 fixos. Sem a regra do seller A, a mesma cobrança seguiria a conta de sempre, com a taxa da subconta sobre o valor total: R$ 1,39. No boleto, com a subconta e o seller A cobrando R$ 1,09 fixos cada, A paga R$ 1,09 e os R$ 1,09 da subconta são rateados entre B e C: R$ 0,65 e R$ 0,43. O centavo que sobra do rateio não é cobrado, e a plataforma fica com R$ 2,17.

​
Split por percentual

Quando algum seller da cobrança tem regra própria para o método e a parcela, o split precisa ser por percentual. Split por valor nessa cobrança é recusado com platform_fee_requires_percentage_split. Sem regra de seller na cobrança, o split por valor continua como hoje.

​
Validações com a taxa ligada

Com a flag de ativação da subconta ligada, a cobrança com split também é recusada nestes casos:
  • Seller repetido (platform_fee_duplicate_seller): o mesmo seller aparece em mais de uma linha do split. Some as partes numa linha só.
  • Seller fora da subconta (platform_fee_seller_not_in_merchant e platform_fee_seller_without_merchant): um seller do split está cadastrado em outra subconta ou não tem subconta. Cadastre-o na subconta da cobrança.
  • Split diferente entre provedores (platform_fee_split_differs_by_provider): a cobrança manda a lista provider e os provedores não têm o mesmo split. Conta como diferente ter outros sellers, os mesmos sellers com percentuais ou valores diferentes, ou um provedor sem split ao lado de outro com split. Mande o mesmo split para todos os provedores ou use só o splitRules do topo.
  • Seller que receberia menos de R$ 0,01 (platform_fee_exceeds_amount): no split por percentual, depois da taxa, algum seller ficaria com menos de R$ 0,01. Aumente a parte dele ou o valor da cobrança, ou revise a regra.
Essas validações valem para toda cobrança com split da subconta com a flag ligada, com ou sem regra de seller. Com a flag desligada, nenhuma delas roda e a cobrança segue como hoje.

​
A taxa na resposta da cobrança

O objeto platformFee da cobrança mantém os campos de sempre e, quando algum seller tem regra própria, ganha lines, um item por seller, com a regra usada, a parte bruta, a taxa e o que ele recebe. Nesse caso, amount é a soma de lines[].feeAmount, e os campos do topo trazem a regra da subconta quando alguma linha a usa. Se nenhuma linha usa a regra da subconta, eles trazem a regra da primeira linha que tem regra. Cobranças sem regra de seller e cobranças antigas não têm lines. O platformFee do webhook 1.1 da cobrança traz os mesmos campos, com lines. Trecho da resposta da cobrança Pix do exemplo acima:

​
Consultando as regras dos sellers

O GET /v1/merchants/{merchantId}/platform-fee traz, além das regras da subconta em rules:
  • sellerRules: um item por seller com ao menos uma regra própria, com as regras dele no mesmo formato de rules.
  • coverage.merchant.methods e coverage.sellers[].methods: o estado de pix, boleto e de cada faixa de parcelas de credit, para a subconta e para cada seller.
Um seller sem regra própria num método ou parcela em que a subconta está em missing também aparece como missing, e não como inherits. Trecho de coverage de uma subconta com Pix, boleto e crédito de 1x a 2x próprios, sem regra de 3x a 24x, e um seller com Pix e crédito 1x próprios:
Com simulationAmount, cada item de sellerRules ganha methods, com a taxa calculada como se o seller recebesse o valor simulado inteiro. Em cada método e parcela, scope diz se vale a regra do seller ou a da subconta.

​
Venda sem split

Com a taxa ligada, a cobrança sem splitRules, no topo e na lista provider, também paga a taxa da plataforma. A Malga usa como recebedor o único seller ativo da subconta, calcula a taxa como se ele recebesse o valor inteiro da cobrança e envia ao provedor o split com esse seller e o valor já líquido da taxa. A plataforma fica com a taxa.
  • Seller ativo é o seller da subconta com status active ou partial e ao menos um provedor ativo. Ele também precisa estar ativo em cada provedor da cobrança.
  • A regra é escolhida como na cobrança com split: a regra do seller para o método e a parcela e, sem ela, a da subconta. Sem regra em nenhum nível, a cobrança é recusada com platform_fee_rule_not_configured. Taxa maior ou igual ao valor da cobrança é recusada com platform_fee_exceeds_amount.
  • Na resposta, splitRules traz o seller com amount igual ao que ele recebe, e platformFee traz a taxa. Quando vale a regra própria do seller, platformFee tem lines, com uma linha.
  • A venda Apple Pay continua sem taxa.
  • Com a taxa desligada, nada muda: a cobrança sem split segue sem taxa e sem split.
Quando a subconta não tem exatamente um seller ativo, a cobrança é recusada com 422 e platform_fee_seller_not_active, antes de ir ao provedor. error.context.reason diz o motivo, e error.context traz também paymentMethod e, no crédito, installment: Para escolher quem recebe numa subconta com mais de um seller ativo, envie splitRules na cobrança. Exemplo de recusa numa subconta com dois sellers ativos:

​
Estornos

Em estornos totais ou parciais, o platform-fee é revertido proporcionalmente ao valor estornado. A devolução de cada seller é proporcional ao que ele recebeu na cobrança, e a plataforma devolve o restante. 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
Com taxa por seller, a conta é a mesma. No estorno de R$ 50,00 da cobrança Pix do exemplo de Conta por seller, A devolve R$ 24,80, B devolve R$ 14,75, C devolve R$ 9,83 e a plataforma devolve R$ 0,62.

​
Erros

​
Na configuração

​
Na cobrança

A recusa vem em error.declined_code. Nas recusas de seller, error.details traz um texto em inglês com os valores, e error.context traz os mesmos valores em campos, para você montar a sua mensagem. Exemplo de recusa por seller: