Consultar Juro Adicional

cURL

curl --request GET \
  --url https://api.cakto.com.br/public_api/installment-interest/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "active": true,
  "installments": [
    {
      "installments": 2,
      "interestPercentage": 1.5
    },
    {
      "installments": 3,
      "interestPercentage": 2.5
    },
    {
      "installments": 4,
      "interestPercentage": 3.5
    },
    {
      "installments": 5,
      "interestPercentage": 4.5
    },
    {
      "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
    }
  ]
}

GET

public_api

installment-interest

cURL

curl --request GET \
  --url https://api.cakto.com.br/public_api/installment-interest/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "active": true,
  "installments": [
    {
      "installments": 2,
      "interestPercentage": 1.5
    },
    {
      "installments": 3,
      "interestPercentage": 2.5
    },
    {
      "installments": 4,
      "interestPercentage": 3.5
    },
    {
      "installments": 5,
      "interestPercentage": 4.5
    },
    {
      "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
    }
  ]
}

Escopo

    read payments

O que é este endpoint?

Quando o comprador parcela no cartão, dois juros diferentes entram na mesma parcela:

Quem define	Onde consultar	O que é
A Cakto	`GET /public_api/fees/`, em `creditCardInstallments`	O juro-base do parcelamento, de 1x a 18x.
Você	este endpoint, de 2x a 12x	O juro adicional que você decide cobrar do comprador por cima daquele.

Este endpoint devolve o seu: a tabela de percentuais por número de parcelas e o campo active, que diz se ela está sendo aplicada hoje. É a versão consultável por API do que você configura no painel.

A operação lê sempre a conta dona do token. Não existe parâmetro de produtor: não há como consultar a tabela de outra conta, e mandar um identificador na query não muda o resultado.

Não existe juro adicional em 1x. A faixa vai de 2 a 12, e é assim nos dois lados: o painel não oferece 1x e a API recusa (400). Se você monta um simulador que vai de 1x a 18x, some o juro adicional só a partir de 2x — e só até 12x.

Para que serve

Montar o simulador de parcelas

Some este juro ao juro-base de GET /public_api/fees/ para exibir, na sua interface, exatamente o que o comprador vai ver no checkout da Cakto.

Conferir o que está configurado

Leia antes de mexer. active: false com percentuais preenchidos é uma tabela guardada e desligada — situação fácil de confundir com “não configurado”.

Auditar antes de escrever

Como o PUT substitui a tabela inteira, ler primeiro é o que evita apagar uma faixa por omissão.

Explicar o valor da parcela

Quando o comprador pergunta por que a parcela ficou acima do preço dividido, a diferença sai daqui e do juro-base da Cakto.

Como ler os valores

active é quem decide se algo é cobrado

Com active: false, nada é somado ao valor do comprador — mesmo que installments venha cheio de percentuais.Desligar preserva a tabela em vez de apagá-la, para que religar não exija redigitar. Isso significa que uma resposta com active: false e interestPercentage: 5.5 é perfeitamente normal: é uma configuração guardada, inativa.Cruze sempre os dois campos antes de calcular o valor de uma parcela. Ler só interestPercentage faz você exibir um juro que a Cakto não está cobrando.

null não é zero

interestPercentage: null quer dizer “não há juro adicional configurado nessa parcela”. 0 quer dizer “configurado como 0%”. Na conta do comprador os dois dão o mesmo resultado, mas na hora de escrever eles são diferentes: um PUT com null remove a faixa, um PUT com 0 grava zero.

A lista vem completa e sempre na mesma ordem

São sempre as 11 faixas, de 2 a 12, mesmo que só uma esteja configurada e mesmo na conta que nunca configurou nada. A lista não encolhe conforme o preenchimento.Pode iterar sem medo de ela mudar de tamanho entre chamadas, e pode indexar por installments sem checar se a chave existe.

percentage vem em pontos percentuais, não em fração

1.5 significa 1,5%, e não 0,015. É a mesma convenção de todo percentual no contrato, incluindo o percentage e o interestPercentage de GET /public_api/fees/.O valor chega como número JSON (1.5), não como string. Em linguagens onde isso importa, converta para decimal antes de fazer aritmética financeira.

Como somar com o juro-base da Cakto

Os dois juros incidem sobre a mesma venda parcelada e se somam em pontos percentuais:

juro_total(n) = fees.creditCardInstallments[n].interestPercentage
              + (active ? installment-interest[n].interestPercentage ?? 0 : 0)

De 13x a 18x só existe o juro-base da Cakto — sua tabela não chega lá. Em 1x, idem.

Vale para todo método que parcela

O mesmo percentual se aplica a cartão de crédito, cartão com 3DS, Google Pay e Apple Pay. Não há tabela por método: é uma tabela só, por número de parcelas.Métodos sem parcelamento — Pix, boleto — não têm juro adicional nenhum.

Resposta

Exemplo de resposta

{
  "active": true,
  "installments": [
    { "installments": 2, "interestPercentage": 1.5 },
    { "installments": 3, "interestPercentage": 2.5 },
    { "installments": 4, "interestPercentage": 3.5 },
    { "installments": 5, "interestPercentage": 4.5 },
    { "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 }
  ]
}

Nesse exemplo o produtor cobra juro adicional de 2x a 6x e em 12x. De 7x a 11x não há juro adicional — o comprador paga só o juro-base da Cakto.

Respostas de erro

Código	Quando ocorre	Corpo de exemplo
`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 `read`.	`{ "detail": "Você não tem permissão para executar esta ação." }`
`429`	Limite de requisições excedido. Veja Limites de Requisição.	`{ "detail": "Request was throttled. Expected available in 42 seconds." }`

Esta leitura não tem 409, e a diferença para GET /public_api/fees/ é proposital.Lá, uma conta sem cadastro de recebimento concluído responde 409 porque devolver “sem taxas” faria você calcular líquido = bruto: seria erro de dinheiro. Aqui, “você não cobra juro adicional nenhum” é a resposta verdadeira para essa conta, e não induz erro de cálculo nenhum. Ela vem como 200 com active: false e a tabela toda em null.O 409 existe só na escrita, onde é acionável de verdade: sem cadastro concluído não há onde gravar.

Exemplo de requisição

curl -X GET 'https://api.cakto.com.br/public_api/installment-interest/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...'

import requests

HEADERS = {"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."}

adicional = requests.get(
    "https://api.cakto.com.br/public_api/installment-interest/",
    headers=HEADERS,
    timeout=30,
).json()

base = requests.get(
    "https://api.cakto.com.br/public_api/fees/",
    headers=HEADERS,
    timeout=30,
).json()

juro_base = {
    linha["installments"]: linha["interestPercentage"]
    for linha in base["creditCardInstallments"]
}
juro_seu = {
    linha["installments"]: linha["interestPercentage"]
    for linha in adicional["installments"]
}

preco = 197.00
for parcelas in range(1, 19):
    extra = juro_seu.get(parcelas) or 0 if adicional["active"] else 0
    total_juro = (juro_base.get(parcelas) or 0) + extra
    com_juro = preco * (1 + total_juro / 100)
    print(f"{parcelas}x de R$ {com_juro / parcelas:.2f}  (total R$ {com_juro:.2f})")

const headers = { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." };

const [adicional, base] = await Promise.all([
  fetch("https://api.cakto.com.br/public_api/installment-interest/", { headers }).then((r) => r.json()),
  fetch("https://api.cakto.com.br/public_api/fees/", { headers }).then((r) => r.json()),
]);

const juroBase = new Map(base.creditCardInstallments.map((l) => [l.installments, l.interestPercentage]));
const juroSeu = new Map(adicional.installments.map((l) => [l.installments, l.interestPercentage]));

const preco = 197.0;
for (let parcelas = 1; parcelas <= 18; parcelas++) {
  const extra = adicional.active ? juroSeu.get(parcelas) ?? 0 : 0;
  const totalJuro = (juroBase.get(parcelas) ?? 0) + extra;
  const comJuro = preco * (1 + totalJuro / 100);
  console.log(`${parcelas}x de R$ ${(comJuro / parcelas).toFixed(2)}`);
}

Boas práticas

Consulte uma vez e guarde. Sua tabela muda quando você mesmo a muda, e nunca sozinha. Chamar a cada carregamento de página gasta seu limite de requisições sem trazer informação nova.
Sempre cruze active com interestPercentage. É o erro mais fácil de cometer aqui, e ele aparece na tela do comprador.
Trate null explicitamente antes de qualquer conta, em vez de deixar a linguagem convertê-lo para zero em silêncio.
Leia antes de escrever. O PUT substitui a tabela inteira: parcela que você não mandar fica sem juro.
Para saber quanto esse juro já rendeu, use Ganhos com Juro de Parcelamento — o percentual configurado não diz nada sobre o que foi efetivamente cobrado nem sobre quanto ficou com você.

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.

Response

Juro adicional de parcelamento configurado na conta autenticada, de 2x a 12x. A conta que nunca configurou nada responde 200 com active: false e todos os percentuais em null — nada é cobrado.

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.

Show child attributes

Comece aqui

Conceitos

Cakto SDK

CaktoMCP

Pagamentos

Pedidos

Webhooks

Produtos

Checkouts

Ofertas

Order Bumps

Clientes

Taxas e Prazos

Juro de Parcelamento

Assinaturas

Consultar Juro Adicional

Escopo

O que é este endpoint?

Para que serve

Montar o simulador de parcelas

Conferir o que está configurado

Auditar antes de escrever

Explicar o valor da parcela

Como ler os valores

Resposta

Exemplo de resposta

Respostas de erro

Exemplo de requisição

Boas práticas

Authorizations

Response

​Escopo

​O que é este endpoint?

​Para que serve

Montar o simulador de parcelas

Conferir o que está configurado

Auditar antes de escrever

Explicar o valor da parcela

​Como ler os valores

​Resposta

​Exemplo de resposta

​Respostas de erro

​Exemplo de requisição

​Boas práticas

Authorizations

Response

Escopo

O que é este endpoint?

Para que serve

Como ler os valores

Resposta

Exemplo de resposta

Respostas de erro

Exemplo de requisição

Boas práticas