Atualizar regras de platform fee de um seller

curl --request PUT \
  --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 '
[
  {
    "paymentMethod": "pix",
    "fixedAmount": 25
  }
]
'

const options = {
  method: 'PUT',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{paymentMethod: 'pix', fixedAmount: 25}])
};

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  {\n    \"paymentMethod\": \"pix\",\n    \"fixedAmount\": 25\n  }\n]")

	req, _ := http.NewRequest("PUT", 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": "27ae4860-55ac-4e48-a417-1038dbdf1049",
  "rules": [
    {
      "id": "88ccd2aa-c3cb-4ff6-bca7-3bc3812da801",
      "percentage": 0,
      "fixedAmount": 25,
      "paymentMethod": "pix",
      "createdAt": "2026-09-29T14:49:54.612Z",
      "updatedAt": "2026-09-29T14:49:54.620Z"
    }
  ],
  "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"
  ]
}

Platform Fee

Atualizar regras de platform fee de um seller

Atualiza as regras próprias do seller. Aceita o mesmo corpo do POST desta rota e segue as mesmas regras do PUT /v1/merchants/{merchantId}/platform-fee, aplicadas só às regras do seller:

Regra avulsa: atualiza a regra do seller com o mesmo método e a mesma parcela, e só os campos enviados. Se o seller não tiver essa regra, retorna 404 e nada muda.
Tabela ou fórmula de credit: substitui a tabela de crédito do seller inteira. A tabela da subconta e a de outros sellers não mudam. As parcelas que ficaram de fora da nova tabela do seller passam a seguir a regra da subconta.

No crédito, o seller aceita só percentual. Um PUT que deixaria valor fixo diferente de 0 numa regra de crédito do seller é recusado com 400.

Um PUT só com percentage: 0 mantém o fixedAmount gravado e não isenta o seller. Para isentar, envie os dois campos com 0 na mesma regra.

PUT

merchants

{merchantId}

sellers

{sellerId}

platform-fee

Atualizar regras de platform fee de um seller

curl --request PUT \
  --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 '
[
  {
    "paymentMethod": "pix",
    "fixedAmount": 25
  }
]
'

const options = {
  method: 'PUT',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{paymentMethod: 'pix', fixedAmount: 25}])
};

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  {\n    \"paymentMethod\": \"pix\",\n    \"fixedAmount\": 25\n  }\n]")

	req, _ := http.NewRequest("PUT", 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": "27ae4860-55ac-4e48-a417-1038dbdf1049",
  "rules": [
    {
      "id": "88ccd2aa-c3cb-4ff6-bca7-3bc3812da801",
      "percentage": 0,
      "fixedAmount": 25,
      "paymentMethod": "pix",
      "createdAt": "2026-09-29T14:49:54.612Z",
      "updatedAt": "2026-09-29T14:49:54.620Z"
    }
  ],
  "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"
  ]
}

Authorizations

X-Client-Id

string

header

required

X-Api-Key

string

header

required

Path Parameters

merchantId

string<uuid>

required

Identificador do merchant

sellerId

string<uuid>

required

Identificador do seller, cadastrado nesta subconta

Body

application/json

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: installment com percentage e/ou fixedAmount.
Tabela curta: installmentRates.
Tabela longa: installments.
Fórmula: maxInstallments e base, com growth, surcharges, overrides e cap opcionais.

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.percentage e base.fixedAmount.
Aplica growth quando n é maior ou igual a growth.from.
Soma as surcharges com fromInstallment menor ou igual a n.
Limita ao cap.
Substitui pelo overrides da 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.

paymentMethod

enum<string>

required

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.

Available options:

credit,

pix,

boleto

Example:

"credit"

percentage

number<float>

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.

Required range: 0 <= x <= 100

Example:

2.5

fixedAmount

integer

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.

Required range: 0 <= x <= 2147483647

Example:

50

installment

integer

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.

Required range: 1 <= x <= 24

Example:

3

installmentRates

number<float>[]

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.

Required array length: 1 - 24 elements

Required range: 0 <= x <= 100

Example:

[
  2.99,
  5.11,
  6.86,
  8.64,
  10.45,
  12.29,
  14.45,
  16.35,
  18.29,
  20.26,
  22.26,
  24.3
]

installments

object[]

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.

Required array length: 1 - 24 elements

Show child attributes

maxInstallments

integer

Somente credit. Obrigatório na fórmula. Última parcela gerada pela fórmula, que grava regras de 1x até maxInstallments.

Required range: 1 <= x <= 24

Example:

8

base

object

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

growth

object

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

surcharges

object[]

Somente credit, na fórmula. Sobretaxas que entram a partir de uma parcela e valem dali em diante. Sobretaxas diferentes se acumulam.

Maximum array length: 24

Show child attributes

overrides

object[]

Somente credit, na fórmula. Valor final de parcelas específicas, que substitui o valor calculado.

Maximum array length: 24

Show child attributes

cap

object

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

Response

Regras atualizadas com sucesso, como ficaram gravadas

Regras de um seller como ficaram gravadas, na resposta do POST e do PUT da rota de seller

sellerId

string<uuid>

required

Seller dono das regras, em minúsculas

rules

object[]

required

Regras gravadas ou alteradas nesta requisição

Show child attributes

warnings

string[]

required

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.

Visão Geral

Sub-keys

Cards

Tokens

3DS2 Malga

Charges

Sessions

Purchases

Subscriptions

Customers

Merchants

Providers

Vendors

Sellers

Payouts

Plans

Prepayment

Receipts

Flows

Webhooks

Settings

Atualizar regras de platform fee de um seller

Authorizations

Path Parameters

Body

Response