> ## Documentation Index > Fetch the complete documentation index at: https://malga-develop.mintlify.site/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. 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. | 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, de 0 a 2147483647. Pode coexistir com percentage na mesma regra. | | `installment` | Número exato de parcelas, de 1 a 24. Obrigatório na regra avulsa de credit; proibido nos demais métodos. | | `installmentRates` | Somente credit. Lista de percentuais em que a posição é o número de parcelas. | | `installments` | Somente credit. Lista de parcelas, cada uma com `installment`, `percentage` e `fixedAmount`. | | `maxInstallments`, `base`, `growth`, `surcharges`, `overrides`, `cap` | Somente credit. Fórmula que gera a tabela de parcelas. | 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: ```json Array theme={null} [ { "paymentMethod": "default", "percentage": 2 }, { "paymentMethod": "pix", "percentage": 1.09, "fixedAmount": 30 } ] ``` ```json Objeto theme={null} { "rules": [ { "paymentMethod": "default", "percentage": 2 }, { "paymentMethod": "pix", "percentage": 1.09, "fixedAmount": 30 } ] } ``` 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](/api-reference/merchants/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: ```text theme={null} fee = floor(amount * percentage / 100) + fixedAmount ``` 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. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "default", "percentage": 2 }, { "paymentMethod": "pix", "percentage": 1.09, "fixedAmount": 30 }, { "paymentMethod": "boleto", "fixedAmount": 109 }, { "paymentMethod": "credit", "installmentRates": [2.99, 5.11, 6.86, 8.64, 10.45, 12.29, 14.45, 16.35, 18.29, 20.26, 22.26, 24.30] } ] }' ``` 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. Use `installments` quando alguma parcela tem valor fixo ou quando você quer cadastrar só algumas parcelas. Cada entrada informa `installment` e ao menos um entre `percentage`, com até 2 casas decimais, e `fixedAmount`. A entrada não aceita outras chaves: um campo com grafia diferente, como `fixedamount`, recusa a requisição com `400`. A regra em volta também aceita só `paymentMethod` e `installments`. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "default", "percentage": 2 }, { "paymentMethod": "credit", "installments": [ { "installment": 1, "percentage": 2.99 }, { "installment": 2, "percentage": 5.11, "fixedAmount": 50 }, { "installment": 3, "percentage": 6.86, "fixedAmount": 50 } ] } ] }' ``` A requisição grava 3 regras de crédito: 1x só com percentual, 2x e 3x com percentual e R\$ 0,50 fixos. Cada objeto descreve uma parcela, com `installment` e o valor da taxa. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '[ { "paymentMethod": "default", "percentage": 2 }, { "paymentMethod": "credit", "installment": 1, "percentage": 2.99 }, { "paymentMethod": "credit", "installment": 2, "percentage": 5.11 }, { "paymentMethod": "credit", "installment": 3, "percentage": 6.86 } ]' ``` 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. | Campo | Descrição | | - | - | | `maxInstallments` | Obrigatório. Última parcela gerada, de 1 a 24. | | `base` | Obrigatório. `percentage` (obrigatório) e `fixedAmount` de partida de todas as parcelas. | | `growth` | Como o percentual cresce: `mode`, `step`, `rate` e `from`. | | `surcharges` | Sobretaxas com `fromInstallment`, `percentage` e `fixedAmount`. Valem da parcela indicada em diante e se acumulam. | | `overrides` | Valor final de parcelas específicas, com `installment`, `percentage` e `fixedAmount`. Substitui o valor calculado. | | `cap` | Teto do percentual (`percentage`) e do valor fixo (`fixedAmount`) calculados. | Os modos de crescimento em `growth.mode`: | Modo | Efeito | Campos | | - | - | - | | `none` | Todas as parcelas ficam com o percentual da base. É o padrão. | Não aceita `step`, `rate` nem `from`. | | `linear` | Soma `step` pontos percentuais a cada parcela, a partir de `from`. | `step` obrigatório. `from` vai de 2 até `maxInstallments`, e o padrão é 2. | | `exponential` | Multiplica o percentual da base por `1 + rate` a cada parcela, a partir de `from`. `rate` é uma fração, e não um percentual: com 0.06, cada parcela fica 6% acima da anterior, e com 10, 1000% acima. | `rate` e `cap.percentage` obrigatórios. `from` como no `linear`. | 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: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "default", "percentage": 2 }, { "paymentMethod": "credit", "maxInstallments": 8, "base": { "percentage": 2.79 }, "growth": { "mode": "linear", "step": 0.20, "from": 2 }, "surcharges": [{ "fromInstallment": 7, "percentage": 0.50 }], "cap": { "percentage": 4.60 } } ] }' ``` A requisição grava oito regras de crédito: | Parcela | 1x | 2x | 3x | 4x | 5x | 6x | 7x | 8x | | - | - | - | - | - | - | - | - | - | | Percentual | 2,79% | 2,99% | 3,19% | 3,39% | 3,59% | 3,79% | 4,49% | 4,60% | 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%: | Parcelas | Taxa usada na cobrança | `source` na consulta | | - | - | - | | 1x, 2x e 7x | A regra da própria parcela | `rule` | | 3x a 6x e 8x a 24x | A regra `default` | `default` | 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. ```bash theme={null} curl --location --request PUT 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "credit", "installmentRates": [3.49, 5.90, 7.80] } ] }' ``` ## 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. ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee?simulationAmount=1000000' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` 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: ```json theme={null} { "platformFeeEnabled": true, "simulation": { "amount": 1000000, "currency": "BRL" }, "methods": [ { "paymentMethod": "pix", "accepted": true, "source": "rule", "percentage": 1.09, "fixedAmount": 30, "fee": 10930, "sellerNet": 989070 }, { "paymentMethod": "boleto", "accepted": true, "source": "rule", "percentage": 0, "fixedAmount": 109, "fee": 109, "sellerNet": 999891 }, { "paymentMethod": "credit", "accepted": true, "installments": [ { "installment": 1, "accepted": true, "source": "rule", "percentage": 2.99, "fixedAmount": 0, "fee": 29900, "sellerNet": 970100, "buyerInstallmentAmount": 1000000 }, { "installment": 2, "accepted": true, "source": "rule", "percentage": 5.11, "fixedAmount": 0, "fee": 51100, "sellerNet": 948900, "buyerInstallmentAmount": 500000 }, { "installment": 12, "accepted": true, "source": "rule", "percentage": 24.3, "fixedAmount": 0, "fee": 243000, "sellerNet": 757000, "buyerInstallmentAmount": 83333 }, { "installment": 13, "accepted": true, "source": "default", "percentage": 2, "fixedAmount": 0, "fee": 20000, "sellerNet": 980000, "buyerInstallmentAmount": 76923 } ] } ], "coverage": { "merchant": { "missing": [], "warnings": ["credit sem regra própria em 13x a 24x; a cobrança cai na regra genérica"] } } } ``` Campos de cada parcela em `installments`: | Campo | Descrição | | - | - | | `installment` | Número de parcelas, de 1 a 24. | | `accepted` | Indica se a venda nessa parcela, no valor simulado, passaria com a taxa calculada. | | `reason` | Presente quando `accepted` é `false`: `fee_exceeds_amount` quando a taxa é maior ou igual ao valor simulado, e `no_rule_configured` quando nenhuma regra cobre a parcela. | | `source` | De onde vem a taxa da parcela: `rule` ou `default`. | | `percentage` e `fixedAmount` | Percentual e valor fixo aplicados. | | `fee` | Taxa sobre o valor total simulado, em centavos. | | `sellerNet` | Valor simulado menos a taxa, em centavos. É o que fica para os recebedores. | | `buyerInstallmentAmount` | Valor de cada parcela para o comprador, em centavos, arredondado para baixo. | Valores de `source`: | Valor | Significado | | - | - | | `rule` | A parcela tem regra própria. | | `default` | A parcela não tem regra própria, e a cobrança usa a regra `default`. | 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](/api-reference/merchants/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 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.