Skip to main content
PUT
cURL

Escopo

Esta chamada muda o que o comprador paga.O juro adicional é somado ao valor da compra quando o comprador escolhe parcelar. Subir de 5% para 10% em 12x significa que, a partir da próxima venda parcelada em 12x, o comprador paga a mais — não é um ajuste de relatório nem de exibição.Não há confirmação em duas etapas e não há desfazer: o valor anterior não é guardado em lugar nenhum. Leia a tabela atual e guarde-a antes de escrever, se quiser poder voltar atrás.

O que é este endpoint?

É a escrita da tabela consultada em Consultar Juro Adicional: o juro que você cobra do comprador por parcelar, por cima do juro-base da Cakto que sai em GET /public_api/fees/. Vale de 2x a 12x — não existe juro adicional em 1x — e se aplica a cartão de crédito, cartão com 3DS, Google Pay e Apple Pay.
A operação escreve sempre a conta dona do token. Não existe parâmetro de produtor: não há como configurar a tabela de outra conta.

Quando a mudança passa a valer

1

A resposta 200 já é o estado novo

O corpo devolvido é a tabela como ficou gravada, no mesmo formato do GET. Não é um eco do que você mandou: se algo foi normalizado, é ali que aparece.
2

O próximo checkout carregado já mostra o valor novo

A tabela de parcelas que o comprador vê é atualizada na hora em que você grava. Não há espera de propagação.
3

Os pedidos já pagos não mudam

O juro cobrado fica registrado no pedido. Mudar a tabela não altera venda passada, não gera cobrança complementar e não gera devolução.
Checkout em voo: quem já está com a página aberta vê um valor e paga outro.A tabela exibida é lida quando o checkout carrega. O juro efetivamente cobrado é calculado no momento do pagamento. Um comprador que abriu o checkout antes da sua alteração continua vendo a tabela antiga até recarregar a página — mas, se ele finalizar depois, é a tabela nova que entra na cobrança.A diferença sai do bolso do comprador e só aparece na fatura dele. Na prática:
  • Evite mexer em horário de pico. A janela de risco é o tempo entre carregar o checkout e finalizar a compra.
  • Prefira reduzir a aumentar durante o dia. Cobrar menos do que foi exibido não gera reclamação; o contrário gera.
  • Mudou para mais? Espere alguns minutos antes de considerar a alteração “no ar” para quem já estava navegando.

Corpo da requisição

array<object>
required
A tabela inteira. Substitui a configuração anterior: parcela que não estiver nesta lista fica sem juro adicional, e uma lista vazia ([]) zera todas.Mande apenas as faixas que quer cobrar — não é preciso repetir as 11.
boolean
default:"true"
Se o juro adicional deve passar a ser cobrado. Omitido, vale true — quem envia uma tabela quer cobrá-la.Envie false para guardar a tabela sem cobrar: os percentuais são preservados e voltam a valer com um true.

O que é aceito

Não há teto de negócio. O quanto de juro cobrar é decisão sua, e esta API aceita a mesma faixa que o painel aceita — nada que você consegue configurar pela tela é recusado aqui.O que existe é um limite técnico: acima de 99999999.99 o valor não cabe no campo e a chamada volta 400. Confira o que você envia: um 1000 digitado no lugar de 10.00 é aceito, e multiplica por onze o que o comprador paga na parcela.

Substituição, não mesclagem

O corpo descreve a tabela inteira, não um remendo. Se hoje você cobra em 6x e em 12x e manda só a linha de 6x, a de 12x é apagada.É de propósito: sem isso, remover um juro pela API seria impossível — não haveria como dizer “essa faixa não existe mais”.O caminho seguro é sempre o mesmo: leia a tabela, altere o que precisa em memória, e mande o conjunto completo de volta.
{"installments": []} remove o juro adicional de todas as faixas. A conta continua existindo e active continua valendo o que você mandou — só não há mais percentual nenhum para aplicar.
Há duas formas de parar de cobrar, e elas não são equivalentes:
  • active: false com a tabela cheia — para de cobrar e guarda os percentuais. Religar depois é um PUT com active: true.
  • installments: [] — apaga os percentuais. Voltar exige redigitar tudo.
Para uma pausa (promoção, campanha, teste), use active: false.
Para religar, mande active explicitamente. Se a sua tabela está desligada e você envia um PUT sem o campo active, a chamada volta 409 em vez de reativar.O motivo: active omitido vale true, então a chamada silenciosamente voltaria a cobrar do seu comprador — e “corrigir um percentual” não é a mesma intenção que “voltar a cobrar”. Envie active: true para religar junto com os novos percentuais, ou active: false para alterá-los mantendo a cobrança desligada.Enquanto a tabela está vigente, ou quando nunca existiu, não há ambiguidade e omitir active continua valendo true.
Mandar o mesmo corpo duas vezes deixa a conta exatamente no mesmo estado. Não existe recurso que possa ser criado em duplicidade aqui.Por isso a operação não lê o header X-Idempotency-Key — ele é ignorado, como em todo endpoint fora de Criar Cobrança. Se um 503 interromper a chamada, repita à vontade.

Resposta

200 devolve a tabela como ficou gravada, no mesmo formato de Consultar Juro Adicional: active mais as 11 faixas de 2x a 12x, com null nas que ficaram sem juro.
Confira a resposta em vez de assumir. Ela é a leitura do que ficou gravado, não a repetição do que você enviou — é onde uma faixa apagada por omissão aparece.

Respostas de erro

Como ler o 400

Os erros por campo vêm em installments, na mesma posição do item que você enviou — o terceiro item da sua lista gera o terceiro elemento do array de erros. O erro de faixa repetida é da lista inteira e vem como texto direto:
409 e 503 pedem reações opostas — não trate os dois como “deu erro, tenta de novo”.409 tem três motivos, e o detail diz qual: a conta ainda não concluiu o cadastro de recebimento, o recurso não está habilitado para ela, ou você mandou um PUT sem active sobre uma tabela desligada. Nenhum dos três se resolve repetindo a chamada — o primeiro se resolve no Painel Cakto, o segundo com o suporte, e o terceiro reenviando com active explícito.503 é transitório: repita com backoff. A operação é idempotente, então repetir não tem custo. Se persistir, é incidente do nosso lado.
Um 400 também pode chegar com detail em vez de installments, quando a recusa vem do serviço interno de taxas. É problema do corpo enviado: repetir igual não vai passar.

Exemplo de requisição

Pausar sem apagar

{"active": false, "installments": []} não é o mesmo que a chamada acima: ele desliga e apaga. Para religar depois, você teria que redigitar a tabela.

Boas práticas

  • Leia, altere, escreva. Nunca monte o corpo do zero a partir de uma tabela que você acha que está lá.
  • Guarde a tabela anterior antes de gravar. Não há histórico do lado da Cakto: o valor que você substituir não é recuperável.
  • Prefira active: false a installments: [] quando o objetivo é pausar.
  • Não escreva em laço. Esta configuração muda raramente e cada escrita chega ao comprador. Se você está gravando várias vezes por dia, provavelmente o que você quer é medir o resultado, não reconfigurar.
  • Depois de mudar para mais, confira o efeito no ganho em Ganhos com Juro de Parcelamento — juro alto derruba conversão no parcelado, e o total pode cair mesmo com o percentual maior.

Authorizations

Authorization
string
header
required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Body

installments
object[]
required

A tabela inteira. Substitui a configuração anterior: parcela que não estiver nesta lista fica sem juro adicional, e uma lista vazia zera todas. Mande apenas as faixas que quer cobrar; não é preciso repetir as 11.

active
boolean
default:true

Se o juro adicional deve passar a ser cobrado. Omitido, vale true — quem envia uma tabela quer cobrá-la. Envie false para guardar a tabela sem cobrar; os percentuais são preservados e voltam a valer com um true.

Response

A tabela como ficou depois da escrita, no mesmo formato do GET. A operação substitui a configuração inteira e pode ser repetida: mandar o mesmo corpo de novo deixa a conta no mesmo estado.

active
boolean
required

Se o juro adicional está sendo cobrado hoje. Com false nada é somado ao valor do comprador, mesmo que installments traga percentuais: desligar preserva a tabela em vez de apagá-la, para que religar não exija redigitar. Uma conta que nunca configurou juro adicional também responde false.

installments
object[]
required

A tabela completa de 2x a 12x, sempre com as 11 faixas e sempre na mesma ordem. Faixa sem juro configurado aparece com interestPercentage: null.