curl --request PUT \
--url https://api.cakto.com.br/public_api/installment-interest/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"installments": [
{
"installments": 123,
"interestPercentage": 1.5
}
],
"active": true
}
'import requests
url = "https://api.cakto.com.br/public_api/installment-interest/"
payload = {
"installments": [
{
"installments": 123,
"interestPercentage": 1.5
}
],
"active": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({installments: [{installments: 123, interestPercentage: 1.5}], active: true})
};
fetch('https://api.cakto.com.br/public_api/installment-interest/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cakto.com.br/public_api/installment-interest/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'installments' => [
[
'installments' => 123,
'interestPercentage' => 1.5
]
],
'active' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api.cakto.com.br/public_api/installment-interest/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"installments\": [\n {\n \"installments\": 123,\n \"interestPercentage\": 1.5\n }\n ],\n \"active\": true\n}"
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.put("https://api.cakto.com.br/public_api/installment-interest/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"installments\": [\n {\n \"installments\": 123,\n \"interestPercentage\": 1.5\n }\n ],\n \"active\": true\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.cakto.com.br/public_api/installment-interest/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n \"installments\": [\n {\n \"installments\": 123,\n \"interestPercentage\": 1.5\n }\n ],\n \"active\": true\n}", false);
var response = await client.PutAsync(request);
Console.WriteLine("{0}", response.Content);
Configurar Juro Adicional
Define o juro adicional de parcelamento que você cobra do comprador, de 2x a 12x. A chamada substitui a tabela inteira e passa a valer no próximo pagamento.
curl --request PUT \
--url https://api.cakto.com.br/public_api/installment-interest/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"installments": [
{
"installments": 123,
"interestPercentage": 1.5
}
],
"active": true
}
'import requests
url = "https://api.cakto.com.br/public_api/installment-interest/"
payload = {
"installments": [
{
"installments": 123,
"interestPercentage": 1.5
}
],
"active": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({installments: [{installments: 123, interestPercentage: 1.5}], active: true})
};
fetch('https://api.cakto.com.br/public_api/installment-interest/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cakto.com.br/public_api/installment-interest/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'installments' => [
[
'installments' => 123,
'interestPercentage' => 1.5
]
],
'active' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api.cakto.com.br/public_api/installment-interest/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"installments\": [\n {\n \"installments\": 123,\n \"interestPercentage\": 1.5\n }\n ],\n \"active\": true\n}"
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.put("https://api.cakto.com.br/public_api/installment-interest/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"installments\": [\n {\n \"installments\": 123,\n \"interestPercentage\": 1.5\n }\n ],\n \"active\": true\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.cakto.com.br/public_api/installment-interest/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n \"installments\": [\n {\n \"installments\": 123,\n \"interestPercentage\": 1.5\n }\n ],\n \"active\": true\n}", false);
var response = await client.PutAsync(request);
Console.WriteLine("{0}", response.Content);
Escopo
write payments
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 emGET /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.
Quando a mudança passa a valer
A resposta 200 já é o estado novo
GET. Não é um eco do que você mandou: se algo foi normalizado, é ali que aparece.O próximo checkout carregado já mostra o valor novo
Os pedidos já pagos não mudam
- 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
[]) zera todas.Mande apenas as faixas que quer cobrar — não é preciso repetir as 11.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
| Campo | Faixa aceita | Recusa |
|---|---|---|
installments | inteiro de 2 a 12 | 1, 0, 13, 18, negativos → 400 |
interestPercentage | número não negativo, no máximo 2 casas decimais | -1, 1.234 → 400 |
installments[] | cada número de parcelas uma única vez | faixa repetida → 400 |
active | true ou false | — |
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
Parcela omitida fica sem juro
Parcela omitida fica sem juro
Lista vazia zera tudo
Lista vazia zera tudo
{"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.Desligar preserva, apagar não
Desligar preserva, apagar não
active: falsecom a tabela cheia — para de cobrar e guarda os percentuais. Religar depois é umPUTcomactive: true.installments: []— apaga os percentuais. Voltar exige redigitar tudo.
active: false.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.Repetir a mesma chamada é seguro
Repetir a mesma chamada é seguro
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.
{
"active": true,
"installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 3, "interestPercentage": 2.5 },
{ "installments": 4, "interestPercentage": null },
{ "installments": 5, "interestPercentage": null },
{ "installments": 6, "interestPercentage": 5.5 },
{ "installments": 7, "interestPercentage": null },
{ "installments": 8, "interestPercentage": null },
{ "installments": 9, "interestPercentage": null },
{ "installments": 10, "interestPercentage": null },
{ "installments": 11, "interestPercentage": null },
{ "installments": 12, "interestPercentage": 10.0 }
]
}
Respostas de erro
| Código | Quando ocorre | Corpo de exemplo |
|---|---|---|
400 | Faixa fora de 2..12, percentual negativo, mais de duas casas decimais, ou faixa repetida. | { "installments": [ { "installments": ["1x não aceita juro adicional de parcelamento. Use um valor entre 2 e 12."] } ] } |
401 | Token ausente, inválido ou expirado. | { "detail": "As credenciais de autenticação não foram fornecidas." } |
403 | Chave de API sem o escopo payments, ou sem write. Leitura exige read; escrita exige write. | { "detail": "Você não tem permissão para executar esta ação." } |
409 | Conta sem cadastro de recebimento concluído, recurso não habilitado para a conta, ou PUT sem active sobre uma tabela desligada. | { "detail": "Conta ainda não habilitada para recebimento. Conclua o cadastro no painel da Cakto para poder configurar o juro adicional de parcelamento." } |
429 | Limite de requisições excedido. Veja Limites de Requisição. | { "detail": "Request was throttled. Expected available in 42 seconds." } |
503 | Falha temporária ao gravar a configuração. | { "detail": "Não foi possível salvar o juro adicional agora. Tente novamente em instantes." } |
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:
{
"installments": ["Cada número de parcelas pode aparecer uma única vez. Repetidos: 6x."]
}
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.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
curl -X PUT 'https://api.cakto.com.br/public_api/installment-interest/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
-H 'Content-Type: application/json' \
-d '{
"active": true,
"installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 6, "interestPercentage": 5.5 },
{ "installments": 12, "interestPercentage": 10 }
]
}'
import requests
BASE = "https://api.cakto.com.br/public_api/installment-interest/"
HEADERS = {"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."}
# 1. Leia a tabela atual -- o PUT substitui tudo, então nunca escreva às cegas.
atual = requests.get(BASE, headers=HEADERS, timeout=30).json()
tabela = {
linha["installments"]: linha["interestPercentage"]
for linha in atual["installments"]
if linha["interestPercentage"] is not None
}
# 2. Altere só o que precisa.
tabela[12] = 10.0
# 3. Mande o conjunto completo de volta.
resposta = requests.put(
BASE,
headers=HEADERS,
json={
"active": True,
"installments": [
{"installments": n, "interestPercentage": p} for n, p in sorted(tabela.items())
],
},
timeout=30,
)
resposta.raise_for_status()
print(resposta.json())
const BASE = "https://api.cakto.com.br/public_api/installment-interest/";
const headers = {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn...",
"Content-Type": "application/json",
};
// 1. Leia a tabela atual -- o PUT substitui tudo.
const atual = await fetch(BASE, { headers }).then((r) => r.json());
const tabela = new Map(
atual.installments
.filter((l) => l.interestPercentage !== null)
.map((l) => [l.installments, l.interestPercentage]),
);
// 2. Altere só o que precisa.
tabela.set(12, 10.0);
// 3. Mande o conjunto completo de volta.
const resposta = await fetch(BASE, {
method: "PUT",
headers,
body: JSON.stringify({
active: true,
installments: [...tabela.entries()]
.sort((a, b) => a[0] - b[0])
.map(([installments, interestPercentage]) => ({ installments, interestPercentage })),
}),
});
if (!resposta.ok) throw new Error(`Cakto API error ${resposta.status}`);
console.log(await resposta.json());
Pausar sem apagar
curl -X PUT 'https://api.cakto.com.br/public_api/installment-interest/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
-H 'Content-Type: application/json' \
-d '{ "active": false, "installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 6, "interestPercentage": 5.5 },
{ "installments": 12, "interestPercentage": 10 }
] }'
{"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: falseainstallments: []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
Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.
Body
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.
Show child attributes
Show child attributes
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.
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.
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.
Show child attributes
Show child attributes
Was this page helpful?