Changelog

​

Incompatível

​

Adicionado

• canceledBy diz quem fez o último cancelamento: subscriber (o assinante, pelo portal), producer (o painel), api (a API pública) ou system (régua de cobrança, disputa, reembolso, cobrança recusada).
• cancellationFeedback traz o motivo que o assinante escolheu ao cancelar pelo portal: too_expensive, not_using, not_as_expected, access_problem ou other.

​

Adicionado

​

Adicionado

• GET /public_api/disputes/: as contestações por aba (awaiting, in_review, won, lost, expired), com o estado da defesa e o próximo prazo;
• GET /public_api/disputes/{id}/: prazo, regras de envio e, depois do envio, a carta, os documentos e o andamento;
• POST /public_api/disputes/{id}/defense/: a defesa em multipart/form-data, com os PDFs, a carta ao banco e o aceite;
• POST /public_api/disputes/{id}/complement/: a resposta ao pedido de complemento do Compliance.

​

Adicionado

​

Adicionado

{
  "detail": "Este negócio ainda não foi aprovado. Ações que alteram dados ou movimentam dinheiro ficam bloqueadas até a aprovação.",
  "code": "business_not_approved"
}

• Onde vale: POST /public_api/withdrawals/, PUT /public_api/installment-interest/, POST /public_api/refunds/{id}/approve/ e POST /public_api/orders/{id}/refund/.
• O que continua liberado: todas as consultas (GET), inclusive saldo, taxas e saques.
• O que fazer: trate pelo code, não pelo texto. Repetir a chamada não resolve; a escrita passa a funcionar quando o negócio for aprovado, sem trocar a chave.

​

Documentado

​

Incompatível

"coupon": {
  "code": "dez",
  "discount": 10.0,
  "discountType": "fixed",
  "currency": "BRL",
  "couponType": "default",
  "applyOnBumps": false
}

• Nada muda nos cupons que já existiam: todos vêm "percentage", com o mesmo número.
• Quem sente: quem calcula o desconto multiplicando o preço por coupon.discount / 100. Leia discountType antes, ou use o discount do pedido, que sempre foi o valor descontado em dinheiro e não mudou.

​

Adicionado

• Cupom fixed vale só na oferta principal (nunca em order bump), só em oferta da mesma moeda e até 80% do preço da oferta. Fora disso, o cupom é ignorado e o pagamento segue sem desconto, como já acontece com cupom inválido ou expirado.
• Cupom first_charge vale só em oferta de assinatura (em oferta única é ignorado) e só com cartão, Pix ou Pix Automático. Com outro método, a criação devolve 400 com {"detail": "Este cupom não vale para esse meio de pagamento."}.
• No Pix Automático com cupom first_charge, o comprador paga a 1ª cobrança com desconto e o mandato fica autorizado pelo valor cheio das renovações.

​

Incompatível

  "available": "1250.40",
- "pending": "4100.05",
- "reserved": "462.00",
+ "pending": "3890.15",
+ "reserved": "412.00",
  "heldByRefund": "89.90",
+ "refundBlocked": "289.90",
+ "refundBlockedFromPending": "120.00",
+ "refundBlockedFromReserved": "50.00",

• Nada mudou de nome nem de tipo. Continuam string decimal, na mesma posição. O que mudou é o número, e ele fica menor quando há retenção — por isso este aviso: uma mudança assim não quebra o parsing e passa despercebida numa conferência rápida.
• Quem sente: quem concilia pending ou reserved contra um histórico próprio, ou soma os campos para exibir um total. Conta sem pedido de reembolso em processamento não muda de número.
• Para reconstituir os valores anteriores, use as duas fatias publicadas junto:
  pending_antigo  = pending  + refundBlockedFromPending  + heldByRefund
  reserved_antigo = reserved + refundBlockedFromReserved
  
  No exemplo acima: 3890.15 + 120.00 + 89.90 = 4100.05 e 412.00 + 50.00 = 462.00. As fórmulas fecham exatamente sobre os valores da mesma resposta, sem tolerância de arredondamento: se na sua conciliação não fecharem, é inconsistência a investigar — registre a chamada e fale com o suporte.
• O + heldByRefund da primeira linha não é erro de digitação. Até esta mudança, a parte já liberada do bloqueio era contada ao mesmo tempo em pending e em heldByRefund — o mesmo dinheiro em dois campos. Reconstituir o valor antigo exige devolver essa duplicata, que é justamente o que a mudança apagou.
• Não use refundBlocked - heldByRefund no lugar das fatias. Essa diferença mistura o que saiu de pending, o que saiu de reserved e o retido que nunca esteve em nenhum dos dois — ela não é a parcela de campo nenhum, e erra em quase todos os casos.
• Com refundBlocked: null as duas fatias vêm null junto com ele, e pending e reserved não sofreram desconto nenhum: pending_antigo = pending + heldByRefund e reserved_antigo = reserved. Com a retenção desligada heldByRefund é "0.00"; quando a apuração falhou, ele traz a fatia já descontada de available, que a resposta antiga também somava em pending.

​

Adicionado

• refundBlocked pode vir null, e null não é zero. Significa que não há número a publicar — a retenção não está ativa para a sua conta, ou a apuração falhou naquela chamada. Zero de verdade vem "0.00". Tratar null como zero anuncia ao produtor que nada está bloqueado, o que pode ser falso.
• As duas fatias acompanham esse null. Sem apuração não há fatia a publicar, e "0.00" ali afirmaria que nada saiu daquele campo.
• heldByRefund não acompanha o null: ele mantém o próprio valor, que é "0.00" com a retenção desligada e a fatia já descontada de available quando a apuração falhou.
• refundBlocked não concilia 1:1 com o valor das vendas em análise. Numa venda parcialmente antecipada que ainda não liberou, o bloqueio é só o resto — R$30,00 numa venda de R$ 50,00 com R$ 20,00 já antecipados. Depois que a venda libera, e na venda antecipada por inteiro, o bloqueio é o valor cheio da venda, e fica também em heldByRefund.
• Detalhe e exemplos em Saldo.

​

Adicionado

• Nenhuma ação é necessária para quem não quer o evento. Os demais eventos de pedido não mudaram: o bloco só existe no refund_requested.
• Para receber, assine o evento no webhook (painel ou Atualizar Webhook).

• GET /public_api/refunds/: Listar Reembolsos, com filtro por status, data do pedido de reembolso e produto.
• GET /public_api/refunds/{id}/: Consultar Reembolso.
• POST /public_api/refunds/{id}/approve/: Aprovar Reembolso, que antecipa um reembolso pedido pelo comprador. Só alcança solicitação aberta: se o comprador desistiu, responde 409 e não estorna nada. Repetir a chamada é seguro.

​

Incompatível

{ "currency": ["Venda em moeda estrangeira não está habilitada para esta conta."] }

• Quem sente: conta sem a venda internacional habilitada que criava ou duplicava produto em dólar (ou em outra moeda que não o real) pela API ou pelo MCP.
• Produto que já existe continua editável. A moeda de um produto nunca pôde ser trocada depois da criação, então editar não passa por esta regra.
• Produto em real não muda, inclusive o criado sem currency no corpo, que nasce em BRL.

​

Adicionado

  "utm_source": "instagram",
  "sck": null,
+ "callback": "8f31c9e7",
  "fbc": null,

• Nenhuma ação é necessária. É adição de campo: o payload não mudou de forma, nada foi renomeado e nada saiu. Um handler que ignora chaves desconhecidas continua funcionando.
• A lista de campos fixos do evento de pedido foi de 43 para 44 — ver Guia de Webhooks.

​

Corrigido

- { "count": 2, "total_pages": 1, "page": 1, "page_size": 10, "results": [...] }
+ { "count": 2, "next": null, "previous": null, "results": [...] }

• Se você integrou a listagem de saques nas primeiras horas de hoje, troque page_size por limit e leia a próxima página por next em vez de calcular a partir de total_pages. É a única ação necessária, e só afeta a listagem — solicitar e consultar saque não mudaram.
• O teto de limit nesta operação é 1000, como nas demais listagens ampliadas.

​

Adicionado

• POST /public_api/withdrawals/ — solicita o saque.
• GET /public_api/withdrawals/{id}/ — estado do pedido.
• GET /public_api/withdrawals/ — histórico, paginado.

• withdrawals_read — consulta e listagem
• withdrawals_write — solicitar saque

• Não cadastra nem altera chave Pix. O saque vai sempre para a chave já cadastrada no painel; pixKey e account no corpo são ignorados. Quem tem a chave de API decide quanto sacar, nunca para onde.
• Não paga na hora. Todo saque pedido pela API entra na fila de análise com status: "pending". 201 significa pedido registrado, não dinheiro transferido — acompanhe pela consulta.

• X-Idempotency-Key obrigatória no POST. Sem ela a requisição é recusada com 400: num endpoint que move dinheiro, um retry de timeout sem chave de idempotência vira um segundo saque. A resposta fica guardada por 24h; repetir a mesma chave devolve o mesmo resultado.
• 2 solicitações por hora, por chave de API. Acima disso, 429 com Retry-After.

​

Adicionado

• GET /public_api/balance/ — quanto está disponível para saque agora e quanto ainda vai liberar.
• GET /public_api/balance/schedule/ — quanto libera em cada dia.

• available pode ser negativo. Retenção por reembolso, chargeback e MED descontam do disponível sem piso, e o resultado é dívida real. Cliente que trate saldo como “sempre ≥ 0” esconde exatamente o que o produtor precisa ver.
• A agenda filtra por data de liberação, não pela data da venda. releaseDate__gte e releaseDate__lte recortam quando o dinheiro cai; para recortar vendas por criação, use GET /public_api/orders/. Sem os dois parâmetros a resposta traz os próximos 30 dias, e a janela não passa de 365 dias.
• Dia sem valor não aparece na agenda. A lista é esparsa: para montar um calendário, preencha os buracos com zero.

​

Documentado

• multi_card e card_pix no enum de paymentMethod. Os dois métodos já chegavam nos seus webhooks; a referência é que listava só os demais. Quem validava o enum como fechado tratava pedido real como valor inválido.
• offer do order bump pode vir null — o schema declarava o campo como sempre presente.
• Descrição de paymentMethod em GET /public_api/fees/: a lista é a das taxas configuradas e inclui método que a cobrança não aceita.

​

Incompatível

{ "paymentMethod": ["Método de pagamento não suportado."] }

• Quem sente: quem emite boleto pela API. Migre para pix ou pix_auto, que aceitam o mesmo payload sem os campos dueDate e boleto.
• POST /public_api/subscriptions/{id}/change-payment-method/ também recusa boleto, pelo mesmo motivo. Assinatura que hoje cobra por boleto precisa ser migrada de método.
• Boleto já emitido não é cancelado por esta mudança: o que existe segue com o mesmo status e a mesma baixa. O que muda é a emissão de novos.

​

Corrigido

• Nada a fazer. Quem tratava esse 400 pode remover o tratamento; quem estava bloqueado volta a cobrar sem mudar payload.
• O erro ContaBankingAusente deixou de existir no schema.

​

Incompatível

{ "number": ["Número de cartão inválido: o dígito verificador não confere. Confira se algum dígito foi trocado — este número não é cobrável em nenhuma adquirente."] }

• Só é recusado o que já não era cobrável. Todo cartão termina num dígito verificador calculado pelo algoritmo de Luhn; número que não fecha essa conta não existe, e nenhuma adquirente autoriza. Cartão real continua tokenizando normalmente.
• Quem sente: quem envia número gerado ou digitado sem conferência — teste automatizado com PAN fictício, principalmente. Se a sua suíte usa número inventado, troque por um que feche o Luhn (4111 1111 1111 1111 e 5555 5555 5555 4444 fecham).
• Espaço e hífen continuam aceitos: a validação normaliza antes de conferir.
• Como o pagamento por cartão só aceita cardToken, isso fecha a porta para o número inválido em todo o fluxo — não há outro caminho de PAN na API.
• A validação não diz que o cartão existe, está ativo ou tem saldo. Recusa por saldo, limite ou antifraude continua vindo da adquirente como sempre.

​

Adicionado

​

Corrigido

​

Adicionado

• GET /public_api/installment-interest/ — a sua tabela de juro adicional.
• PUT /public_api/installment-interest/ — configura essa tabela.
• GET /public_api/installment-interest/earnings/ — quanto de juro foi cobrado e quanto ficou com você num período.

• A faixa é de 2x a 12x, sempre com as onze faixas na resposta e sempre na mesma ordem. Não existe juro adicional em 1x. Parcela sem juro configurado vem com interestPercentage: null — null não é zero.
• interestPercentage é number em pontos percentuais (1.5 é 1,5%), como toda porcentagem no contrato.
• active é quem decide se algo é cobrado. Com active: false a tabela continua guardada e nada é somado ao comprador — desligar preserva os percentuais em vez de apagá-los. Sempre cruze os dois campos antes de calcular o valor de uma parcela.
• O PUT substitui a tabela inteira: parcela que não estiver no corpo fica sem juro, e uma lista vazia zera todas. Mandar o mesmo corpo duas vezes deixa a conta no mesmo estado, então a chamada é segura de repetir — e por isso ela não lê o header X-Idempotency-Key.
• O PUT muda o que o comprador paga, a partir do próximo pagamento parcelado. Pedidos já pagos não mudam. O checkout que o comprador já tem aberto continua exibindo a tabela antiga até recarregar, mas a cobrança usa a tabela nova — os detalhes estão em Configurar Juro Adicional.
• Não há teto de negócio no percentual — o quanto cobrar é decisão sua, e a API aceita a mesma faixa que o painel. O limite é técnico (99999999.99, o que cabe no campo) e o percentual aceita no máximo duas casas decimais.
• Reativar é explícito. active omitido vale true, então um PUT sem active sobre uma tabela desligada volta 409 em vez de religar a cobrança em silêncio. Mande active: true para religar, ou active: false para mexer nos percentuais mantendo desligado. Com a tabela vigente, ou nunca configurada, omitir segue valendo true.
• 409 tem três motivos, distinguíveis pelo detail: conta sem cadastro de recebimento concluído, recurso não habilitado para a conta, ou a reativação implícita acima. Nenhum dos três se resolve repetindo a chamada.

• Hoje traz uma linha: Taxa de serviço, amount "0.99", todos os métodos (paymentMethod: null), devolvida ao comprador no reembolso (refundable: true). O valor é por pedido, não por parcela, e não varia com o valor da venda.
• Leia a lista, não assuma os R$ 0,99. Em parte das contas essa taxa é cobrada do produtor em vez do comprador, ou não é cobrada — nesses casos ela não aparece, e customerFees: [] é resposta válida.
• É lista, e não um campo fixo, justamente para a composição poder mudar sem quebrar quem já integra.
• Se você monta a tela de preço do comprador, o total dele é o produto mais amount. Se você calcula o seu líquido, customerFees não entra na conta.

• A resposta traz charged e earned lado a lado, e eles não são o mesmo número. charged é o juro que o comprador pagou nos seus pedidos; earned é a fatia que ficou com você depois do rateio por comissão. Num produto com coprodutor a 30%, earned é 70% de charged. Somar o juro dos pedidos e chamar de ganho superestima quem divide receita.
• Os dois vêm como string decimal ("1000.00"), como todo dinheiro no contrato novo.
• A janela é obrigatória por consequência: sem startDate/endDate a consulta responde os últimos 30 dias, e o período pedido não pode passar de 92 dias (400 acima disso). Os campos startDate e endDate da resposta ecoam a janela que foi realmente aplicada — confira, principalmente se você não mandou nenhuma das duas.
• Só entram pedidos pagos, e uma consulta responde sobre uma moeda só (currency, padrão BRL).
• O total de um período passado pode mudar. Não há registro de reversão: se um pedido daquele período for reembolsado ou sofrer chargeback depois, ele sai do total. Se você armazenar o valor, reconcilie em vez de tratá-lo como fechado.

​

Incompatível

​

Corrigido

• Campo de antifraude com o nome errado. Era publicado em camelCase; o contrato só aceita antifraud_profiling_attempt_reference, em snake_case. Quem copiava o exemplo recebia 400.
• Obrigatoriedade errada do antifraude. Estava marcado como obrigatório nos cinco métodos de pagamento. Só é exigido em credit_card e threeDs.
• Objeto pix com nomes errados. A referência dizia expiresAt e qrCodeBase64; o real é expirationDate e qrCode. expirationDate também não é date-time: vem como 2026-04-29 01:30:00+00:00, com espaço.
• Resposta de criar produto descrevia o serializer errado, mostrando 7 campos onde a API devolve 59.
• Listagem de checkouts documentava paginação dentro de paginação, envelope que a API nunca devolveu. O correto é um envelope só.

​

Adicionado

• Corpo com dois campos: paymentMethods (lista de paymentMethod, percentage, fixed, releaseDays) e creditCardInstallments (lista de installments, interestPercentage).
• paymentMethods traz sempre os dez métodos, na mesma ordem: pix, pix_auto, boleto, credit_card, threeDs, picpay, pagaleve, googlepay, applepay, openfinance_nubank. Método sem taxa vigente configurada vem com os três valores em null — null não é zero.
• fixed vem como string decimal ("2.49"), e percentage e interestPercentage como number em pontos percentuais (4.99 é 4,99%). Não é inconsistência: é o padrão novo, explicado abaixo.
• 409 tem um único motivo nesta operação: conta sem cadastro de recebimento concluído. 503 é falha temporária ao consultar as taxas, e pode ser repetida com backoff.

​

Padrão de valores, daqui pra frente

​

Documentado

• Cartão no enum de paymentMethod. credit_card e threeDs sempre foram aceitos, mas a referência listava só pix, pix_auto e boleto. Os objetos card e threeDSecure e o campo installments passaram a constar.
• Pré-requisito de conta Cakto Banking. Cobrar por pix, pix_auto ou boleto exige conta aberta e ativa; cartão não exige. Ver Pré-requisitos.
• Corpo entregue nos webhooks, campo a campo, incluindo o fato de data ter duas formas: checkout_abandonment não traz id nem status, e quebra handler que deduplica por data.id. Ver Webhooks.
• Respostas de erro 400, 403 e 404 em 16 operações que não as declaravam.
• Campos que a referência omitia: currency em ofertas e produtos, id no cliente do pedido e no order bump, errors no histórico de eventos de webhook, e mais oito campos de produto. Já vinham na resposta; agora estão descritos.