Skip to main content
POST

Authorizations

​
X-Client-Id
string
header
required
​
X-Api-Key
string
header
required

Path Parameters

​
merchantId
string<uuid>
required

Identificador do merchant

Body

application/json

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:

  1. Parte de base.percentage e base.fixedAmount.
  2. Aplica growth quando n é maior ou igual a growth.from.
  3. Soma as surcharges com fromInstallment menor ou igual a n.
  4. Limita ao cap.
  5. Substitui pelo overrides da parcela, quando houver.
  6. 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:
​
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
​
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.

​
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.

​
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
​
overrides
object[]

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

Maximum array length: 24
​
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.

Response

Regras criadas com sucesso. A resposta traz as regras como ficaram gravadas, com uma regra por parcela no crédito.

​
id
string<uuid>

Identificador único da regra de platform fee

Example:

"74739f85-1bfa-40ae-a003-1c464c8e3c94"

​
percentage
number<float> | null

Percentual da taxa aplicado

Example:

2.5

​
fixedAmount
integer | null

Valor fixo da taxa em centavos

Example:

50

​
paymentMethod
enum<string>

Método de pagamento ao qual a regra se aplica

Available options:
credit,
pix,
boleto
Example:

"credit"

​
installment
integer | null

Número exato de parcelas da regra, de 1 a 24. Presente apenas em regras de credit. Cada parcela tem no máximo uma regra ativa. Uma regra de credit sem installment vem da conversão da antiga regra default e vale para toda parcela sem regra própria.

Example:

3

​
createdAt
string<date-time>

Data de criação da regra

Example:

"2024-01-15T10:30:00.000Z"

​
updatedAt
string<date-time>

Data da última atualização da regra

Example:

"2024-01-15T10:30:00.000Z"