> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Taxas e Prazos
> Consulte as taxas e os prazos de recebimento vigentes da sua conta, por método de pagamento, e a tabela de juros do parcelamento no cartão. É a mesma informação da tela Taxas e Prazos do painel.
#### Escopo
```bash theme={null}
read payments
```
## O que é este endpoint?
É a versão consultável por API da tela **Taxas e Prazos** do painel. Para cada método de pagamento, ele devolve os três números que a tela mostra:
* **o percentual** cobrado sobre a venda aprovada — o `4,99%` da linha do cartão;
* **o valor fixo** somado a ele — o `+ R$ 2,49 por venda aprovada`;
* **o prazo de recebimento em dias** — o selo `Recebimento: 15 dias`.
Vem junto a tabela de **juro do parcelamento no cartão**, de 1x a 18x.
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.
***
## Para que serve
Aplique percentual e fixo sobre o valor da oferta para mostrar ao seu time, ou ao seu cliente, quanto de fato entra por venda em cada método.
Use o prazo de recebimento para estimar quando o dinheiro de uma venda fica disponível e planejar o caixa do mês.
Compare custo e prazo lado a lado. Pix costuma custar menos e liberar antes; cartão custa mais e libera depois, mas converte melhor no parcelado.
Use a tabela de 1x a 18x para exibir, na sua própria interface, o juro de cada opção de parcela.
***
## De onde vem cada número na tela
Os nomes na API são os mesmos que você já usa em `paymentMethod` de [`POST /public_api/payments/`](/api-reference/payments/create-pix). Como o painel usa rótulos comerciais, esta é a correspondência:
| No painel | `paymentMethod` na API |
| ---------------------------------------------------------- | ---------------------- |
| Cartão | `credit_card` |
| Pix | `pix` |
| Pix Automático | `pix_auto` |
| Boleto | `boleto` |
| PicPay | `picpay` |
| Apple Pay | `applepay` |
| Google Pay | `googlepay` |
| **Parcelamento no Pix** | `pagaleve` |
| 3DS — exibido no painel em "Taxa para autenticação segura" | `threeDs` |
| Nubank via Open Finance — não aparece nessa tela | `openfinance_nubank` |
A lista vem **completa e sempre na mesma ordem**, com os dez métodos, mesmo os que sua conta não usa. Método sem taxa vigente configurada vem com os três valores em `null` — é o mesmo caso em que o painel escreve **"Não configurado"**. Pode iterar a lista sem medo de ela mudar de tamanho entre chamadas.
***
## A taxa que o comprador paga
Tudo em `paymentMethods` sai **do seu repasse**. `customerFees` é a exceção: são taxas que a Cakto cobra **do comprador**, somadas ao total que ele paga no checkout. Elas não reduzem o seu líquido.
Hoje há exatamente uma:
| | |
| ------------ | ------------------------------------------- |
| Nome | **Taxa de serviço** |
| Valor | **R\$ 0,99** por pedido, fixo |
| Métodos | todos (`paymentMethod: null`) |
| No reembolso | volta para o comprador (`refundable: true`) |
O valor é por **pedido**, não por parcela, e não muda com o valor da venda.
**Não some `customerFees` no seu cálculo de líquido.** O erro simétrico também custa dinheiro: se você monta a tela de preço para o comprador, o total dele é o valor do produto **mais** `amount` — quem esquece mostra um preço menor do que o cobrado.
**A lista reflete a sua conta, e pode vir vazia.** Em algumas contas esta taxa é cobrada do produtor em vez do comprador, ou não é cobrada — nesses casos ela simplesmente não aparece em `customerFees`. Por isso leia a lista em vez de assumir os R\$ 0,99: `customerFees: []` é uma resposta válida e significa que nenhuma taxa é cobrada do seu comprador.
Esta é também a razão de `customerFees` ser uma **lista** e não um campo fixo: a composição pode mudar sem quebrar quem já integra.
***
## Como ler os valores
`4.99` significa **4,99%**, e não 0,0499. Para aplicar sobre o valor da venda, divida por 100:
```
taxa = valor * (percentage / 100) + fixed
```
O `0.0` do Pix é taxa percentual zero de verdade — a cobrança daquele método é só o valor `fixed`.
`null` quer dizer **"sem taxa vigente configurada para esse método na sua conta"**, exatamente o "Não configurado" do painel. Tratar `null` como `0` faz sua conta de líquido dar um número que a Cakto nunca prometeu. Se um método que você usa aparece `null`, fale com o [suporte](mailto:infoprodutores@cakto.com.br).
É o mesmo número do selo `Recebimento:` do painel: dias corridos, contados da criação do pedido, segundo o que está configurado hoje na sua conta.
É uma **projeção**, não uma garantia por venda: a venda pode ser processada por outra adquirente, e antecipação altera o prazo. A data efetiva de cada pedido está em `releaseDate`, no próprio pedido — veja [Obter Pedido](/api-reference/orders/retrieve).
`releaseDays: 0` é liberação no mesmo dia, o que o painel exibe como "Instantâneo".
`interestPercentage` é o juro-base que a **Cakto** cobra para aquele número de parcelas, também em pontos percentuais. `installments: 1` costuma vir `0.0` — à vista não tem juro de parcelamento.
Ele **não inclui** o juro adicional que você mesmo pode ter configurado para cobrar do comprador no parcelado. Esse é seu, vale de 2x a 12x e sai em [Consultar Juro Adicional](/api-reference/installment-interest/retrieve). São dois números somados na mesma parcela: para exibir o valor real ao comprador, some os dois; tratar este aqui como se já incluísse o seu erra a conta.
`percentage`, `fixed` e `interestPercentage` chegam como número (`2.49`), não como string. Em linguagens onde isso importa, converta para decimal antes de fazer aritmética financeira, em vez de acumular em ponto flutuante.
***
## Resposta
* `paymentMethod` — método, no mesmo vocabulário de `POST /public_api/payments/`
* `percentage` — percentual por venda aprovada, em pontos percentuais
* `fixed` — valor fixo em reais por venda aprovada
* `releaseDays` — prazo de recebimento em dias corridos
* `installments` — número de parcelas, de 1 a 18
* `interestPercentage` — juro-base da Cakto para essa parcela
* `name` — nome da taxa como o comprador vê
* `amount` — valor fixo somado ao total do comprador
* `percentage` — percentual somado ao total do comprador
* `paymentMethod` — método a que se aplica, ou `null` para todos
* `refundable` — se volta ao comprador no reembolso
### Exemplo de resposta
```json theme={null}
{
"paymentMethods": [
{ "paymentMethod": "pix", "percentage": 0.0, "fixed": "2.49", "releaseDays": 1 },
{ "paymentMethod": "pix_auto", "percentage": 8.99, "fixed": "2.49", "releaseDays": 7 },
{ "paymentMethod": "boleto", "percentage": 3.99, "fixed": "2.49", "releaseDays": 2 },
{ "paymentMethod": "credit_card", "percentage": 4.99, "fixed": "2.49", "releaseDays": 15 },
{ "paymentMethod": "threeDs", "percentage": 4.99, "fixed": "2.49", "releaseDays": 15 },
{ "paymentMethod": "picpay", "percentage": 4.99, "fixed": "2.49", "releaseDays": 15 },
{ "paymentMethod": "pagaleve", "percentage": 4.99, "fixed": "2.49", "releaseDays": 15 },
{ "paymentMethod": "googlepay", "percentage": 4.99, "fixed": "2.49", "releaseDays": 15 },
{ "paymentMethod": "applepay", "percentage": 4.99, "fixed": "2.49", "releaseDays": 15 },
{ "paymentMethod": "openfinance_nubank", "percentage": null, "fixed": null, "releaseDays": null }
],
"creditCardInstallments": [
{ "installments": 1, "interestPercentage": 0.0 },
{ "installments": 2, "interestPercentage": 2.99 },
{ "installments": 3, "interestPercentage": 4.49 },
{ "installments": 18, "interestPercentage": 21.5 }
],
"customerFees": [
{
"name": "Taxa de serviço",
"amount": "0.99",
"percentage": 0,
"paymentMethod": null,
"refundable": true
}
]
}
```
`creditCardInstallments` foi encurtado no exemplo acima. Na resposta real ele traz **as 18 linhas**, de `1` a `18`, sem buracos.
***
## 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`. | `{ "detail": "Você não tem permissão para executar esta ação." }` |
| `409` | Conta ainda sem cadastro de recebimento concluído. | `{ "detail": "Conta ainda não habilitada para recebimento. Conclua o cadastro no painel da Cakto para que a tabela de taxas e prazos exista." }` |
| `429` | Limite de requisições excedido. Veja [Limites de Requisição](/conceitos/rate-limits). | `{ "detail": "Request was throttled. Expected available in 42 seconds." }` |
| `503` | Falha temporária ao consultar as taxas. | `{ "detail": "Não foi possível consultar as taxas agora. Tente novamente em instantes." }` |
**`409` e `503` pedem reações opostas — não trate os dois como "deu erro, tenta de novo".**
`409` tem **um único motivo** nesta operação: a conta ainda não concluiu o cadastro de recebimento, então não existe tabela de taxas para responder. Repetir a chamada não resolve; quem resolve é o produtor, no [Painel Cakto](https://app.cakto.com.br/dashboard).
`503` é transitório: repita com backoff. Se persistir, é incidente do nosso lado — fale com o [suporte](mailto:infoprodutores@cakto.com.br).
***
## Exemplo de requisição
```bash cURL theme={null}
curl -X GET 'https://api.cakto.com.br/public_api/fees/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...'
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.cakto.com.br/public_api/fees/",
headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."},
timeout=30,
)
response.raise_for_status()
fees = response.json()
por_metodo = {linha["paymentMethod"]: linha for linha in fees["paymentMethods"]}
cartao = por_metodo["credit_card"]
if cartao["percentage"] is None or cartao["fixed"] is None:
raise RuntimeError("Cartão sem taxa configurada nesta conta.")
bruto = 197.00
taxa = bruto * (cartao["percentage"] / 100) + cartao["fixed"]
print(f"Líquido: R$ {bruto - taxa:.2f} em {cartao['releaseDays']} dias")
```
```javascript Node.js theme={null}
const response = await fetch("https://api.cakto.com.br/public_api/fees/", {
headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." },
});
if (!response.ok) throw new Error(`Cakto API error ${response.status}`);
const fees = await response.json();
const cartao = fees.paymentMethods.find((linha) => linha.paymentMethod === "credit_card");
if (cartao.percentage === null || cartao.fixed === null) {
throw new Error("Cartão sem taxa configurada nesta conta.");
}
const bruto = 197.0;
const taxa = bruto * (cartao.percentage / 100) + cartao.fixed;
console.log(`Líquido: R$ ${(bruto - taxa).toFixed(2)} em ${cartao.releaseDays} dias`);
```
***
## Boas práticas
* **Consulte uma vez e guarde.** Sua tabela de taxas muda raramente — normalmente só quando o plano ou o contrato muda. Chamar este endpoint a cada pedido gasta seu limite de requisições sem trazer informação nova. Guarde o resultado e atualize periodicamente.
* **Trate `null` explicitamente** antes de qualquer conta, em vez de deixar a linguagem convertê-lo para zero em silêncio.
* **Não use `releaseDays` para prometer data ao cliente final.** Para a data de um pedido específico, leia `releaseDate` em [Obter Pedido](/api-reference/orders/retrieve).
* **Não deduza a taxa a partir do valor recebido de uma venda antecipada.** Antecipação tem custo próprio, que não sai neste endpoint; a conta não vai fechar.
## OpenAPI
````yaml GET /public_api/fees/
openapi: 3.0.3
info:
title: Cakto API
version: 1.0.0
description: Documentação da API pública do Cakto.
servers:
- url: https://api.cakto.com.br
description: Cakto API
security: []
paths:
/public_api/fees/:
get:
tags:
- fees
description: >-
Taxas e prazos vigentes da conta autenticada.
Devolve, por método de pagamento, o percentual e o valor fixo cobrados
por venda
aprovada e o prazo de recebimento em dias, mais a tabela de juro-base do
parcelamento no cartão. É a mesma informação da tela "Taxas e Prazos" do
painel.
A operação lê sempre a conta dona do token: não recebe identificador de
produtor
e não há como consultar a tabela de outra conta.
Os valores descrevem a **configuração vigente** da conta, não o
resultado de uma
venda específica. O prazo real de liberação de um pedido está em
`releaseDate` do
próprio pedido: a venda pode ser processada por outra adquirente da
cascata e a
antecipação altera a data. Percentuais vêm em pontos percentuais (`4.99`
= 4,99%)
e `null` significa "sem taxa vigente configurada", nunca zero.
operationId: fees_retrieve
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FeesResponse'
examples:
Sucesso:
value:
paymentMethods:
- paymentMethod: pix
percentage: 0
fixed: 2.49
releaseDays: 1
- paymentMethod: pix_auto
percentage: 8.99
fixed: 2.49
releaseDays: 7
- paymentMethod: boleto
percentage: 3.99
fixed: 2.49
releaseDays: 2
- paymentMethod: credit_card
percentage: 4.99
fixed: 2.49
releaseDays: 15
- paymentMethod: threeDs
percentage: 4.99
fixed: 2.49
releaseDays: 15
- paymentMethod: picpay
percentage: 4.99
fixed: 2.49
releaseDays: 15
- paymentMethod: pagaleve
percentage: 4.99
fixed: 2.49
releaseDays: 15
- paymentMethod: googlepay
percentage: 4.99
fixed: 2.49
releaseDays: 15
- paymentMethod: applepay
percentage: 4.99
fixed: 2.49
releaseDays: 15
- paymentMethod: openfinance_nubank
percentage: null
fixed: null
releaseDays: null
creditCardInstallments:
- installments: 1
interestPercentage: 0
- installments: 2
interestPercentage: 2.99
- installments: 3
interestPercentage: 4.49
- installments: 4
interestPercentage: 5.99
- installments: 5
interestPercentage: 7.49
- installments: 6
interestPercentage: 8.99
- installments: 7
interestPercentage: 10.49
- installments: 8
interestPercentage: 11.99
- installments: 9
interestPercentage: 13.49
- installments: 10
interestPercentage: 14.99
- installments: 11
interestPercentage: 16.49
- installments: 12
interestPercentage: 17.99
- installments: 13
interestPercentage: 18.49
- installments: 14
interestPercentage: 19.49
- installments: 15
interestPercentage: 20.49
- installments: 16
interestPercentage: 20.99
- installments: 17
interestPercentage: 21.24
- installments: 18
interestPercentage: 21.5
description: >-
Taxas e prazos vigentes da conta autenticada, por método de
pagamento.
'401':
description: Request não autenticado devido à ausência ou invalidez do token.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedError'
examples:
Token ausente ou inválido:
$ref: '#/components/examples/UnauthenticatedErrorExample'
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
EscopoInsuficiente:
value:
detail: Você não tem permissão para executar esta ação.
description: Chave de API sem o escopo `payments`.
'409':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
ContaSemRecebimento:
value:
detail: >-
Conta ainda não habilitada para recebimento. Conclua o
cadastro no painel da Cakto para que a tabela de taxas e
prazos exista.
description: >-
A conta ainda não tem cadastro de recebimento concluído, então não
existe tabela de taxas para responder. Este é o único motivo de 409
nesta operação: é seguro tratá-lo como "finalize o cadastro", e não
vale repetir a chamada até que isso aconteça.
'503':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
TaxasIndisponiveis:
value:
detail: >-
Não foi possível consultar as taxas agora. Tente novamente
em instantes.
description: >-
Falha ao consultar o serviço interno que resolve as taxas. É
transitório na maioria dos casos e a chamada pode ser repetida com
backoff; se persistir, é incidente do lado da Cakto. A resposta
nunca repassa o corpo do erro interno.
security:
- OAuth Token: []
components:
schemas:
FeesResponse:
type: object
properties:
paymentMethods:
type: array
items:
$ref: '#/components/schemas/PaymentMethodFee'
description: >-
Taxas e prazos por método de pagamento. A lista traz sempre todos os
métodos suportados, na mesma ordem; método sem taxa configurada
aparece com os três valores em `null`.
creditCardInstallments:
type: array
items:
$ref: '#/components/schemas/CreditCardInstallmentFee'
description: Juro-base da Cakto por número de parcelas no cartão, de 1x a 18x.
customerFees:
type: array
items:
$ref: '#/components/schemas/CustomerFee'
description: >-
Taxas que a Cakto cobra do **comprador** nas vendas desta conta,
somadas ao total que ele paga. Não saem do seu repasse. A lista
reflete a sua conta: se a taxa foi transferida para você ou
isentada, ela não aparece aqui. Pode vir vazia.
required:
- creditCardInstallments
- customerFees
- paymentMethods
UnauthenticatedError:
type: object
properties:
detail:
type: string
PaymentMethodFee:
type: object
properties:
paymentMethod:
type: string
description: >-
Método de pagamento, no mesmo vocabulário usado em `paymentMethod`
de `POST /public_api/payments/`. Valores possíveis: `pix`,
`pix_auto`, `boleto`, `credit_card`, `threeDs`, `picpay`,
`pagaleve`, `googlepay`, `applepay`, `openfinance_nubank`.
percentage:
type: number
nullable: true
description: >-
Percentual cobrado sobre o valor da venda aprovada, em pontos
percentuais: `4.99` significa 4,99%, não 0,0499. `null` quando não
há taxa vigente configurada para o método na sua conta — não
confunda com zero.
fixed:
type: string
format: decimal
example: '2.49'
nullable: true
description: >-
Valor fixo em reais cobrado por venda aprovada, somado ao
percentual, como **string decimal**: `"2.49"`, não `2.49`. Converta
para um tipo decimal antes de somar — em ponto flutuante `0.1 + 0.2`
não é `0.3`, e taxa é dinheiro. `null` quando não há taxa vigente
configurada para o método; `null` não é zero.
releaseDays:
type: integer
nullable: true
description: >-
Prazo de recebimento em dias corridos, contados da criação do
pedido, segundo a configuração vigente da conta. É a projeção que o
painel exibe, não uma garantia da data de liberação de um pedido
específico: a venda pode ser processada por outra adquirente e a
antecipação altera o prazo. A data efetiva de cada pedido está em
`releaseDate` do próprio pedido. `null` quando não há prazo vigente
configurado para o método.
required:
- fixed
- paymentMethod
- percentage
- releaseDays
CreditCardInstallmentFee:
type: object
properties:
installments:
type: integer
description: Número de parcelas.
interestPercentage:
type: number
nullable: true
description: >-
Juro-base cobrado pela Cakto para esse número de parcelas, em pontos
percentuais (`2.99` = 2,99%). Não inclui o juro adicional
configurado pelo produtor. `null` quando não há juro vigente
configurado para a parcela.
required:
- installments
- interestPercentage
CustomerFee:
type: object
properties:
name:
type: string
description: 'Nome da taxa como aparece para o comprador. Hoje: `Taxa de serviço`.'
amount:
type: string
format: decimal
example: '2.49'
nullable: true
description: >-
Valor fixo somado ao total do comprador, em reais. Hoje `"0.99"` por
pedido, independentemente do valor da venda.
percentage:
type: number
nullable: true
description: >-
Percentual somado ao total do comprador, em pontos percentuais. Hoje
`0` — a taxa é só o valor fixo de `amount`.
paymentMethod:
type: string
nullable: true
description: >-
Método a que a taxa se aplica, ou `null` quando se aplica a todos.
Hoje `null`.
refundable:
type: boolean
description: Se a taxa volta para o comprador quando o pedido é reembolsado.
required:
- amount
- name
- paymentMethod
- percentage
- refundable
examples:
UnauthenticatedErrorExample:
summary: Token ausente ou inválido
description: Token ausente ou inválido
value:
detail: As credenciais de autenticação não foram fornecidas.
securitySchemes:
OAuth Token:
type: http
scheme: bearer
in: header
name: Authorization
description: >-
Token de autenticação do tipo `Bearer {access_token}`, onde
`{access_token}` é o token obtido no fluxo de
[autenticação](/authentication).
````