curl --request POST \
--url https://api.malga.io/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Client-Id: <api-key>' \
--data '
{
"rules": [
{
"paymentMethod": "pix",
"percentage": 0,
"fixedAmount": 0
},
{
"paymentMethod": "credit",
"installmentRates": [
1.99,
2.49
]
}
]
}
'const options = {
method: 'POST',
headers: {
'X-Client-Id': '<api-key>',
'X-Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
rules: [
{paymentMethod: 'pix', percentage: 0, fixedAmount: 0},
{paymentMethod: 'credit', installmentRates: [1.99, 2.49]}
]
})
};
fetch('https://api.malga.io/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.malga.io/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee"
payload := strings.NewReader("{\n \"rules\": [\n {\n \"paymentMethod\": \"pix\",\n \"percentage\": 0,\n \"fixedAmount\": 0\n },\n {\n \"paymentMethod\": \"credit\",\n \"installmentRates\": [\n 1.99,\n 2.49\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Client-Id", "<api-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"sellerId": "9ba4c5bc-a0fe-46b9-8950-c6fdba1b3c67",
"rules": [
{
"id": "3a249406-b494-49f5-867c-86dd47ace95a",
"percentage": 0,
"fixedAmount": 0,
"paymentMethod": "pix",
"createdAt": "2026-09-29T14:49:54.612Z",
"updatedAt": "2026-09-29T14:49:54.612Z"
},
{
"id": "f18bcd0a-be5d-486e-883f-455ea501dcce",
"percentage": 1.99,
"fixedAmount": 0,
"paymentMethod": "credit",
"installment": 1,
"createdAt": "2026-09-29T14:49:54.612Z",
"updatedAt": "2026-09-29T14:49:54.612Z"
},
{
"id": "9e143ffb-5de0-4298-aa3c-f5686b8f4391",
"percentage": 2.49,
"fixedAmount": 0,
"paymentMethod": "credit",
"installment": 2,
"createdAt": "2026-09-29T14:49:54.612Z",
"updatedAt": "2026-09-29T14:49:54.612Z"
}
],
"warnings": [
"assinaturas aceitam split só em percentual, e com a taxa desta subconta ligada, uma assinatura com split por valor que inclua este seller tem as cobranças recusadas com platform_fee_requires_percentage_split quando a regra própria dele vale para o método e a parcela da cobrança"
]
}Criar regras de platform fee de um seller
Cria regras de platform fee próprias de um seller dentro 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 segue a regra da subconta.
O corpo aceita as mesmas formas do POST /v1/merchants/{merchantId}/platform-fee: regra avulsa, installmentRates, installments e fórmula, em array ou em objeto com a lista em rules. As diferenças para a regra da subconta:
- No crédito, a regra do seller aceita só percentual por parcela. Qualquer
fixedAmountdiferente de 0, em qualquer forma do corpo, recusa a requisição com400. Empixeboleto, o seller aceita percentual, valor fixo ou os dois.
Como na subconta, paymentMethod: default é recusado com 400 e PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED, e o corpo aceita até 50 objetos de regra.
O seller precisa estar cadastrado nesta subconta. Seller de outro cliente, de outra subconta ou sem subconta responde 404 com PLATFORM_FEE_SELLER_NOT_FOUND, com o mesmo corpo nos três casos.
Para isentar o seller num método, envie percentage: 0 e fixedAmount: 0 na mesma regra. Para ele voltar a seguir a regra da subconta, apague a regra dele com DELETE /v1/merchants/{merchantId}/platform-fee/{platformFeeId}.
A resposta traz as regras gravadas e um aviso fixo em warnings sobre assinaturas com split por valor.
curl --request POST \
--url https://api.malga.io/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Client-Id: <api-key>' \
--data '
{
"rules": [
{
"paymentMethod": "pix",
"percentage": 0,
"fixedAmount": 0
},
{
"paymentMethod": "credit",
"installmentRates": [
1.99,
2.49
]
}
]
}
'const options = {
method: 'POST',
headers: {
'X-Client-Id': '<api-key>',
'X-Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
rules: [
{paymentMethod: 'pix', percentage: 0, fixedAmount: 0},
{paymentMethod: 'credit', installmentRates: [1.99, 2.49]}
]
})
};
fetch('https://api.malga.io/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.malga.io/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee"
payload := strings.NewReader("{\n \"rules\": [\n {\n \"paymentMethod\": \"pix\",\n \"percentage\": 0,\n \"fixedAmount\": 0\n },\n {\n \"paymentMethod\": \"credit\",\n \"installmentRates\": [\n 1.99,\n 2.49\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Client-Id", "<api-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"sellerId": "9ba4c5bc-a0fe-46b9-8950-c6fdba1b3c67",
"rules": [
{
"id": "3a249406-b494-49f5-867c-86dd47ace95a",
"percentage": 0,
"fixedAmount": 0,
"paymentMethod": "pix",
"createdAt": "2026-09-29T14:49:54.612Z",
"updatedAt": "2026-09-29T14:49:54.612Z"
},
{
"id": "f18bcd0a-be5d-486e-883f-455ea501dcce",
"percentage": 1.99,
"fixedAmount": 0,
"paymentMethod": "credit",
"installment": 1,
"createdAt": "2026-09-29T14:49:54.612Z",
"updatedAt": "2026-09-29T14:49:54.612Z"
},
{
"id": "9e143ffb-5de0-4298-aa3c-f5686b8f4391",
"percentage": 2.49,
"fixedAmount": 0,
"paymentMethod": "credit",
"installment": 2,
"createdAt": "2026-09-29T14:49:54.612Z",
"updatedAt": "2026-09-29T14:49:54.612Z"
}
],
"warnings": [
"assinaturas aceitam split só em percentual, e com a taxa desta subconta ligada, uma assinatura com split por valor que inclua este seller tem as cobranças recusadas com platform_fee_requires_percentage_split quando a regra própria dele vale para o método e a parcela da cobrança"
]
}Path Parameters
Identificador do merchant
Identificador do seller, cadastrado nesta subconta
Body
- Array de regras · object[]
- Objeto com rules · object
Uma regra de platform fee.
Em pix e boleto, informe percentage, fixedAmount ou os dois.
Em credit, use uma destas formas, sem combinar formas no mesmo objeto:
- Regra avulsa:
installmentcompercentagee/oufixedAmount. - Tabela curta:
installmentRates. - Tabela longa:
installments. - Fórmula:
maxInstallmentsebase, comgrowth,surcharges,overridesecapopcionais.
Nas três formas de tabela e fórmula, a regra aceita só as chaves da forma escolhida mais paymentMethod. Uma chave desconhecida, como capp no lugar de cap, recusa a configuração inteira com 400, em vez de ser ignorada.
Na fórmula, o percentual e o valor fixo de cada parcela n, de 1 até maxInstallments, são calculados nesta ordem:
- Parte de
base.percentageebase.fixedAmount. - Aplica
growthquandoné maior ou igual agrowth.from. - Soma as
surchargescomfromInstallmentmenor ou igual an. - Limita ao
cap. - Substitui pelo
overridesda parcela, quando houver. - Arredonda o percentual para 2 casas decimais, com meio para cima.
Se alguma parcela calculada passar de 100%, a configuração inteira é recusada.
Método de pagamento ao qual a regra se aplica. A regra genérica default foi descontinuada: paymentMethod: default é recusado com 400 e PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED.
credit, pix, boleto "credit"
Percentual da taxa (0-100) com até 2 casas decimais. Ao menos um entre percentage e fixedAmount deve ser informado. Não pode ser combinado com installmentRates, installments ou fórmula.
0 <= x <= 1002.5
Valor fixo da taxa em centavos, de 0 a 2147483647. Ao menos um entre percentage e fixedAmount deve ser informado. Não pode ser combinado com installmentRates, installments ou fórmula.
0 <= x <= 214748364750
Número exato de parcelas ao qual a regra se aplica, de 1 a 24. Obrigatório na regra avulsa de credit; proibido nos demais métodos. Cada parcela tem a própria regra: installment: 3 vale só para vendas em 3x, e 2x e 3x podem ter taxas diferentes.
1 <= x <= 243
Somente credit. Tabela curta: lista de percentuais em que a posição é o número de parcelas. O primeiro item vale para 1x, o segundo para 2x, e assim por diante. Cada item vai de 0 a 100, com até 2 casas decimais. Grava uma regra por parcela, só com percentual: as parcelas gravadas por esta lista ficam sem valor fixo. Para valor fixo por parcela, use installments.
1 - 24 elements0 <= x <= 100[
2.99,
5.11,
6.86,
8.64,
10.45,
12.29,
14.45,
16.35,
18.29,
20.26,
22.26,
24.3
]
Somente credit. Tabela longa: uma entrada por parcela, com percentual, valor fixo ou os dois. Aceita parcelas salteadas, e cada parcela pode aparecer uma vez só. Cada entrada aceita apenas installment, percentage e fixedAmount: qualquer outra chave, inclusive uma dessas com grafia diferente, recusa a requisição com 400.
1 - 24 elementsShow child attributes
Show child attributes
Somente credit. Obrigatório na fórmula. Última parcela gerada pela fórmula, que grava regras de 1x até maxInstallments.
1 <= x <= 248
Somente credit. Obrigatório na fórmula. Taxa de partida de todas as parcelas, sobre a qual o crescimento e as sobretaxas são aplicados.
Show child attributes
Show child attributes
Somente credit, na fórmula. Define como o percentual cresce a partir de uma parcela. O crescimento não altera o valor fixo.
Show child attributes
Show child attributes
Somente credit, na fórmula. Sobretaxas que entram a partir de uma parcela e valem dali em diante. Sobretaxas diferentes se acumulam.
24Show child attributes
Show child attributes
Somente credit, na fórmula. Valor final de parcelas específicas, que substitui o valor calculado.
24Show child attributes
Show child attributes
Somente credit, na fórmula. Teto do percentual e do valor fixo calculados. A parcela que passa do teto fica com o valor do teto. cap.percentage é obrigatório quando growth.mode é exponential.
Show child attributes
Show child attributes
Response
Regras criadas com sucesso. A resposta traz as regras como ficaram gravadas, com uma regra por parcela no crédito.
Regras de um seller como ficaram gravadas, na resposta do POST e do PUT da rota de seller
Seller dono das regras, em minúsculas
Regras gravadas ou alteradas nesta requisição
Show child attributes
Show child attributes
Avisos fixos, em português, sobre o que uma regra de seller muda em outros fluxos. Hoje, o aviso sobre assinaturas com split por valor.
Was this page helpful?