Changelog

​

Webhooks avisam quando uma tentativa é vinculada ao pagamento

​

A API de cobranças retorna estornos sob demanda

• Consultar uma cobrança com expand[]=refunds.
• Listar cobranças com expand[]=data.refunds.
• Listar estornos com GET /v1/refunds?charge=<id>. Use este caminho para paginar todos os estornos ou consultar os registros depois de receber um webhook.

​

A página de status mostra Pagamentos

​

API

• Serviço novo payments em GET /v1/health, nos intervalos recentes, no histórico diário com service=payments e nos incidentes. Veja como pagamentos é medido.
• O status geral passa a considerar pagamentos: quem acompanha só o status geral também é avisado quando pagamentos falha.

​

Você decide se devolve um pagamento em duplicidade

​

API

• Erros novos em POST /v1/refunds: 422 refund_not_supported para boleto e 402 refund_declined quando a venda não aceita a devolução (o refund termina em failed, com failure_reason declined ou insufficient_funds). Pix com mais de 90 dias responde 409 refund_period_expired. Em nenhum desses casos algo é devolvido.
• Reembolso da cobrança em duplicidade: crie o refund com charge e reason: "duplicate". Ele não estorna a compra, que continua paga.

​

Disputa ganha devolve o dinheiro no extrato

​

API

• transactions no objeto dispute: de zero a dois movimentos do extrato, do mais antigo ao mais novo — a saída (description: "Dispute") e, na disputa ganha, a devolução (description: "Dispute reversal"). Vem na consulta, na lista, na atualização, no encerramento e em todos os eventos charge.dispute.*.
• Eventos novos: charge.dispute.funds.withdrawn quando a saída entra no extrato e charge.dispute.funds.reinstated quando a devolução entra. Para recebê-los, inclua os dois nos eventos do seu endpoint. A devolução também dispara transaction.created e, quando fica paga, transaction.paid.
• charge.disputed agora é histórico: continua true depois que a disputa acaba, ganha ou perdida. Para saber se a disputa ainda está em andamento ou se a cobrança aceita refund, use status e is_charge_refundable do dispute.

​

Repetir a criação de um pagamento devolve o mesmo pagamento

​

API

• POST /v1/payment-intents: a repetição com a mesma chave enquanto a primeira chamada roda responde 200 com o pagamento, não 409 idempotency_key_in_progress. Depois de um 5xx ou de uma resposta perdida, a repetição retoma o mesmo pagamento e, com confirm: true, confirma de novo enquanto ele aceitar confirmação. Nunca há um segundo pagamento para a mesma chave. Detalhes em Idempotência.

​

Depois do boleto, o comprador ainda pode pagar com cartão ou Pix

​

API

• Troca de meio depois do boleto: quando o comprador envia outro meio, a tentativa do boleto encerra com payment_error.code: "payment_method_switched", e checkout.session.async.payment.succeeded pode chegar com payment_data.payment_method credit_card ou pix. Se o boleto e o outro meio forem pagos, o segundo pagamento segue a regra de pagamento em dobro.

​

Depois do Pix, o comprador ainda pode pagar com cartão

​

Compra paga duas vezes? O segundo pagamento volta sozinho

​

API

• Troca do Pix pelo cartão: os eventos são os mesmos de um Pix: checkout.session.completed com payment_status: "unpaid" quando o código é gerado e checkout.session.async.payment.succeeded quando a compra é paga, agora podendo trazer payment_data.payment_method: "credit_card". A tentativa do Pix encerra com payment_error.code: "payment_method_switched", e o código continua pagável até vencer. Em assinatura, a mesma subscription fica active e cobra as próximas mensalidades no cartão. Veja o evento.
• Devolução do segundo pagamento: é um refund comum, com reason: "duplicate", na charge que não pagou a compra. Chegam refund.created, refund.updated com status: "succeeded" e charge.refunded; o Payment Intent continua succeeded pela cobrança que pagou.

​

Cartão recusado não deixa mais assinatura pendurada

​

API

​

Boleto da fatura emitido pelo seu sistema

​

Código Pix na fonte da sua marca

​

API

• Emitir o boleto da fatura: POST /v1/invoices/{id}/issue_boleto retorna o Payment Intent com PDF, linha digitável e vencimento. Repetir a chamada com um boleto ativo devolve o mesmo documento. Consulte a ação.
• font_mono saiu da aparência: branding_settings.appearance não tem mais essa chave, na leitura e na escrita da organização, nos webhooks organization.* e no estado do funil. Enviar font_mono retorna 400 parameter_unknown; o bloco completo agora tem seis chaves.

​

Boleto vale até o fim do dia de vencimento

• Terça, 23h59: o boleto sai da página.
• Se o comprador pagou na terça: a cobrança aparece como paga na quarta ou na quinta, depois da compensação.
• Se ninguém pagou: a cobrança aparece como vencida entre quinta e sexta.

​

API

• Vencimento do boleto: next_action.boleto_display_details.expires_at passa a ser o fim do dia de vencimento no fuso de Brasília (2026-10-20T23:59:59-03:00), e charge.failed com payment_code_expired só chega quando o banco confirma o vencimento.

​

Configurações reorganizadas: Pagamentos e Assinaturas e faturamento

• Pagamentos: como a venda acontece. Abas Métodos de pagamento, Checkout e Conta para saques.
• Assinaturas e faturamento: o que acontece depois da venda. Abas Assinaturas (novas tentativas quando a renovação falha, o que acontece quando elas acabam, e-mails ao assinante e cartão de uso único), Faturas (prazo, multa, juros, lembretes e parcelamento na página da fatura) e Portal do cliente.

​

Página de checkout mais clara nas configurações

• Apresentação: modelo da página, o que o resumo destaca, imagem e textos do produto, resumo do pedido e destaque do parcelamento. Cada campo tem um (i) com o efeito para o comprador.
• Dados do comprador: o que o checkout pede.
• Depois do pagamento: o que acontece quando a compra é confirmada.

​

Novas paletas de cor na aparência

​

Para plataformas: cada área de configuração segue a rede separadamente

​

API

• customer_portal.session sem configuration: o campo, que sempre voltava null, saiu do objeto. Enviar configuration ao criar a sessão deixa de retornar 400; o campo é ignorado, como qualquer campo não suportado. Objeto da sessão do portal.
• Novos valores de cor em branding_settings.appearance: gray_color aceita gray_blue, gray_cool, gray_modern, gray_neutral, gray_iron, gray_true e gray_warm. button_color e background_color aceitam moss, green_light, green, teal, cyan, blue_light, blue, blue_dark, indigo, violet, purple, fuchsia, pink, rose, orange_dark, orange, yellow, carbon, hex ou null. Envios com um nome antigo recebem parameter_invalid com a lista aceita. Os valores salvos foram convertidos assim:

​

Cartões de uso único ou não suportados deixam de perder a venda

• Compra avulsa: aprovada normalmente; nenhum cartão fica salvo.
• Assinatura: a primeira cobrança sai no cartão e as renovações chegam por fatura, por e-mail, para pagar com Pix, boleto ou cartão. O comprador vê o aviso na tela de sucesso, com um botão para cadastrar um cartão comum no portal e voltar à cobrança automática.
• Período grátis: aceito quando você liga as duas opções da configuração; o cliente começa sem cartão salvo e recebe uma fatura ao fim do período.
• Fatura: o assinante que renova por fatura paga cada mensalidade com esse cartão na própria página da fatura; a assinatura não muda.

​

API

• Cobrança sem cartão salvo: uma cobrança de cartão pode vir com payment_method: null; o snapshot do cartão continua em payment_method_details. Objeto da cobrança.
• Assinatura renovada por fatura: uma assinatura criada por checkout de cartão pode nascer com collection_method: send_invoice. Objeto da assinatura.
• Recusa ao salvar: usa o código single_use_card.

​

Notificações no painel

​

Lembretes da fatura: veja o que chegou e reenvie o que não chegou

​

Churn: quanto você perde e por quê

​

Resumo da rede no painel da plataforma

​

Domínio próprio para as páginas e os e-mails

​

Entrega de e-mails no painel da plataforma

​

Cadastro com CPF ou CNPJ preenchido sozinho

​

Cartão de uso único não trava mais a compra

​

API

• single_use_card ao salvar cartão: quando a validação sem valor recusa o cartão ao salvá-lo, em POST /v1/setup-intents/{id}/confirm, no checkout de assinatura, na página da fatura e na atualização de cartão, a resposta é 402 com type: "card_error" e code: "single_use_card". No setup intent, o mesmo código fica em last_setup_error. Antes, essa recusa saía como card_setup_failed ou generic_decline. card_setup_failed continua para a falha sem recusa identificada. Consulte os códigos de recusa.

​

Métodos de pagamento e parcelamento em uma aba só

​

Tempo do redirecionamento depois do pagamento

​

API

• checkout_experience.success_redirect: novo campo em POST /v1/checkout-sessions, POST /v1/payment-links e POST /v1/payment-links/{id}, e na leitura dos dois objetos e dos webhooks checkout.session.* e payment.link.*. { "type": "automatic", "delay_seconds": 5 } redireciona depois de 0 a 60 segundos, e 0 leva o comprador direto do checkout, sem a confirmação; { "type": "manual" } espera o clique. Na sessão, o campo sempre traz o valor que vale para ela; no link, null segue o padrão da organização. Valores fora dessas regras retornam 400. Consulte o parâmetro.

​

Aparência da marca em sete escolhas

​

API

• branding_settings virou branding_settings.appearance: em POST /v1/organizations, GET /v1/organizations, GET e POST /v1/organizations/{id} e nos webhooks organization.created e organization.updated, os campos da marca saíram de branding_settings e foram para o bloco appearance. Os campos antigos deixaram de ser aceitos e de ser devolvidos.

{
  "branding_settings": {
    "accent_color": "#278629",
    "border_style": "rounded",
    "brand_color": "#F6F9FC",
    "font_family": "geist",
    "theme": "light"
  }
}

{
  "branding_settings": {
    "appearance": {
      "background_color": "#F6F9FC",
      "button_color": "#278629",
      "font": "geist",
      "font_mono": "geist_mono",
      "gray_color": "neutral",
      "style": "squircle",
      "theme": "light"
    }
  }
}

• Organizações filhas já personalizadas: a Chargefy converteu cada marca com a tabela acima, e as páginas continuam iguais. As que nunca personalizaram a marca leem appearance: null e passam a seguir a aparência da plataforma.
• Escrita: branding_settings aceita só appearance, enviado completo — as sete chaves, com as cores podendo ser null — ou null para seguir a plataforma. Não há atualização parcial dentro do bloco. Um campo antigo retorna 400 parameter_unknown; uma chave faltando, 400 parameter_missing; um valor fora da lista, 400 parameter_invalid. Veja os quatro formatos.
• Leitura: a API devolve só o que a organização salvou, sem a aparência herdada, com as cores no formato em que foram salvas (nome ou hex).
• Webhook: quando a marca muda pela API, organization.updated traz o bloco anterior em previous_attributes.branding_settings.
• Funis de upsell: appearance do estado devolvido por Chargefy.Funnel.getState() passou a ter as mesmas sete chaves, já resolvidas e com as duas cores sempre em hex. Se a sua página lê appearance.accent_color, troque por appearance.button_color. Veja o exemplo.

​

Funil de upsell desenhado como fluxo

​

Limites de requisição por chave de API

​

Tabelas de juros por organização

​

Taxa da Chargefy em um item só no extrato

​

API

• fee_details sem provider_fee: o tipo provider_fee deixou de existir em fee_details[].type no objeto transaction de GET /v1/transactions, GET /v1/transactions/{id}, dos webhooks transaction.* e das ferramentas MCP. Onde ele aparecia, o valor vem somado ao item chargefy_fee, com a descrição Chargefy processing fee. fee_amount, net_amount e a soma dos itens não mudam. Se a sua integração trata provider_fee, some o valor dele ao de chargefy_fee. Consulte o objeto transaction.

​

Planos de taxas para plataformas

​

API

• Planos de taxas pela API: GET /v1/fee-plans e GET /v1/fee-plans/{id} listam e consultam os planos da sua plataforma, somente com a API key da plataforma. Criar e editar planos continua no painel. Consulte o objeto fee_plan.
• Plano de cada organização: organization.fee_plan traz "default" quando a organização segue o plano padrão, ou o ID do plano fixado. Ao criar ou atualizar a organização, envie null ou "default" para seguir o padrão, ou o ID de um plano para fixá-lo. Veja os exemplos.
• fee_plan só com chave de produção: o plano define o preço das vendas reais, e a organização é a mesma em teste e em produção. Enviar fee_plan com chave de teste, mesmo null ou "default", retorna 400 livemode_mismatch com param: "fee_plan"; em teste, omita o campo.
• Eventos: fee.plan.created e fee.plan.updated chegam aos endpoints com events_from: "platform", com organization igual à organização da plataforma. A troca do plano de uma organização continua em organization.updated, com previous_attributes.fee_plan.
• Para quem integrou com a documentação de 26 de setembro: saíram o campo is_active e o filtro is_active; cada item de rates ganhou id, que muda quando a condição é editada; fee_plan passou a aceitar null; os erros invalid_fee_plan e fee_plan_not_found passaram a ser invalid_request e resource_missing, com param: "fee_plan", e fee_plan_unavailable e fee_plan_changed deixaram de existir; a chamada sem API key de plataforma responde 403 permission_denied. Os IDs de plano mudaram e passaram a ter 8 caracteres Base58, com letras maiúsculas e minúsculas, como plan_k6F3mqMZ: releia os planos e o fee_plan das organizações antes de reutilizar IDs guardados.

​

Exporte os dados com os filtros que você escolheu

​

Recebeu por fora? Marque a fatura como paga

​

Acompanhe os checkouts das suas contas conectadas

​

Links de pagamento sem sair da plataforma

​

A busca do painel sempre à mão

​

Cartão novo só entra pelo navegador

​

API

• POST /v1/tokens e o objeto token foram removidos: a tokenização pelo servidor nunca foi aceita pelo processador em produção, então o endpoint só devolvia erro. Ele agora responde 410 endpoint_removed. Quem tokenizava no navegador com createPaymentToken() passa a usar confirmSetup(), que já entrega o payment_method pronto. Veja o Chargefy.js.
• token_id e card_id deixam de existir em setup intents: POST /v1/setup-intents e POST /v1/setup-intents/{id}/confirm aceitam cartão pelo backend apenas como payment_method (pm_*) já salvo; confirm: true no create exige payment_method. Cartão novo entra pelo navegador, com pk_* e client_secret. Consulte a confirmação.

​

Contas conectadas: do cadastro à operação pelo painel

​

Melhorias

• Acompanhamento da ativação: a ativação financeira verifica o cadastro necessário para uma conta começar a receber. O detalhe da organização passou a apresentar esse processo em uma linha do tempo, com o histórico em ordem cronológica e a etapa atual em destaque. A indicação O que fazer agora e o link de cadastro ajudam a orientar o responsável quando há uma pendência. Entenda o cadastro hospedado.
• Localização de cadastros pendentes: a lista de organizações ganhou filtros de tipo de conta e situação cadastral. Os rótulos e cores de ativação também foram padronizados entre as telas. A equipe consegue separar as contas que precisam de acompanhamento e interpretar o mesmo status ao abrir seus detalhes.
• Consulta ao painel de uma conta: o acesso às contas passou a incluir navegação pelo seletor e a ação Acessar dashboard no detalhe da organização conectada. Quando o usuário possui acesso de consulta, o painel apresenta essa experiência com leitura restrita. A mudança facilita acompanhar a operação de uma conta a partir do contexto da plataforma.
• Identidade visual consistente entre páginas: a personalização da marca já existia. A melhoria unificou sua aplicação no checkout, confirmação, fatura, portal do cliente e páginas de cadastro e revisão. Cores, tema e elementos visuais passam a seguir a marca configurada para cada experiência, reduzindo diferenças de aparência entre as etapas que o cliente percorre.
• Fonte e cantos aplicados à página inteira: a escolha da fonte passou a alcançar títulos, textos, preços, campos e botões. O perfil de cantos — arredondado, pílula ou reto — também foi estendido aos componentes da página. Em Configurações → Marca, a mesma escolha passa a orientar o conjunto da experiência, evitando misturas de tipografia e formatos. Veja os ajustes de marca.
• Valor líquido na lista de recebíveis: os recebíveis mostram os valores de vendas que a conta tem a receber. A lista passou a destacar o valor após as taxas e ganhou ajustes nos filtros. A mudança facilita conferir o dinheiro previsto para a conta sem calcular manualmente os descontos sobre cada valor bruto. Entenda a composição dos recebimentos.
• Data prevista para o depósito: o acompanhamento dos recebíveis passou a incluir uma previsão de quando o dinheiro deve chegar à conta, atualizada a partir das informações de repasse. Isso dá mais contexto para planejar o caixa. A previsão continua separada da confirmação do depósito: a data esperada, por si só, não indica que o dinheiro já entrou.
• Referência das assinaturas por cliente: a identificação das assinaturas foi ajustada para usar uma sequência própria por cliente. As listas da plataforma também passaram a exibir essa referência. Para quem atende uma pessoa com mais de um contrato, fica mais fácil distinguir suas assinaturas e localizar aquela que está sendo discutida. Conheça a gestão de assinaturas.
• Filtros nos indicadores de checkout: as análises de checkout passaram a aceitar recortes por produto, link de pagamento, meio de pagamento e status. Por exemplo, é possível acompanhar apenas os checkouts de um produto ou as compras pagas com Pix. A melhoria permite investigar um segmento da operação diretamente nos indicadores.
• Identificação de registros nas listas: as referências de cobranças, pagamentos e recursos de contas conectadas ficaram mais visíveis nas listagens. A mudança ajuda a cruzar informações entre telas e reconhecer o registro citado em um atendimento, sem depender apenas de nomes que podem se repetir.

​

API

• Formato do número da assinatura: o campo number passou de uma sequência por organização, como SUB-0042, para uma sequência por cliente, como SUB-K7M2-001. O prefixo é o mesmo usado nas faturas do cliente, mas a contagem das assinaturas é independente. Se sua integração valida ou interpreta esse campo, ajuste-a para aceitar o formato atual e sequências com mais de três dígitos. Consulte o campo number.
• interest_payer substitui has_interest no parcelamento do cartão: em payment_method_options.credit_card.installments, o campo interest_payer ("buyer" ou "organization") declara quem paga o juro do parcelamento em Payment Intents, Checkout Sessions, Payment Links e em cada opção de Payment Previews. has_interest foi removido sem alias: enviá-lo retorna 400 com param apontando o campo e a mensagem has_interest was removed; use interest_payer ("buyer" | "organization").
• installment_interest_amount passa a ser o juro da venda, seja quem for que o pague: antes o campo era o juro cobrado do comprador e ficava 0 quando a organização o assumia. Agora traz o mesmo valor nos dois casos; interest_payer diz de quem ele sai.
• O total do comprador depende de quem paga o juro: com interest_payer: "buyer", amount = principal_amount + surcharge_amount + installment_interest_amount; com interest_payer: "organization", amount = principal_amount + surcharge_amount e o juro é descontado do líquido da organização. Nas transactions, o componente installment_interest de fee_details aparece nos dois casos. Entenda quem paga os juros.
• Organizações filhas de plataformas também podem assumir o juro: a restrição que impedia organization em contas operadas por uma plataforma deixou de existir.

​

Gestão da equipe dentro do painel da plataforma

​

Melhorias

• Comparação da aparência antes de salvar: a edição da marca ganhou uma prévia ao vivo, e as opções de fonte passaram a ser exibidas na própria tipografia. A personalização continua na mesma área de configurações; a melhoria está em conseguir comparar o resultado das escolhas enquanto edita, com menos idas e vindas entre as configurações e a página de pagamento. Conheça as opções de marca.

​

Mais contexto para acompanhar cada checkout

​

Correções e ajustes

• Aplicação e limpeza de filtros: o painel de filtros passou a fechar após a aplicação e ganhou a opção de limpar todas as condições. A busca e os filtros já existiam; o ajuste reduz os passos para conferir o resultado ou voltar à listagem sem filtros.

​

Melhorias

• Consulta das tentativas de pagamento: o detalhe de um pagamento passou a mostrar as cobranças associadas a ele, e a listagem ganhou filtros para recusados e expirados. A melhoria facilita investigar as tentativas feitas pelo comprador quando uma compra não é concluída. Entenda o acompanhamento das cobranças.
• Rascunho durante a ativação da plataforma: o uso de domínio próprio já fazia parte da personalização. O assistente passou a permitir informar o endereço desejado e salvá-lo como rascunho. Assim, a equipe pode continuar a preparação da plataforma e concluir a configuração do domínio depois, quando tiver acesso aos ajustes necessários.
• Diagnóstico e histórico da configuração: a área de domínio próprio ganhou uma linha do tempo e um diagnóstico dos registros de DNS e do certificado de segurança. A ação Verificar configuração permite conferir os ajustes. Isso torna mais claro o que falta para o endereço ficar pronto e ajuda a retomar a ativação após corrigir uma pendência. Veja como configurar o domínio.
• Simulação das condições comerciais: a configuração de taxas na ativação ganhou um simulador de lucro e de valores mínimos permitidos. Ele mostra o efeito das condições escolhidas sobre o valor que fica para a plataforma em uma venda. A equipe pode comparar cenários antes de concluir a configuração e avaliar sua margem com os números à vista.
• Canais de contato na ativação: o assistente passou a coletar os canais de contato da plataforma junto das demais informações do negócio. A mudança reúne os dados de atendimento na preparação inicial da conta, facilitando completar o cadastro da plataforma em um mesmo fluxo.
• Leitura da atividade em calendário: o indicador de checkouts iniciados ganhou uma visualização em calendário, para comparar o movimento entre os dias. A preferência de visualização dos gráficos também passou a ser lembrada ao voltar ao dashboard. A melhoria ajuda quem acompanha a operação regularmente a retomar a leitura no formato que escolheu.

​

API

• Opções de fonte na configuração da marca: o campo branding.font_family passou a aceitar fontes como Manrope, DM Sans e Newsreader, e o padrão passou a ser geist. O valor bitter foi removido das opções aceitas. Se sua integração envia esse valor ao criar ou atualizar uma organização, substitua-o por uma das fontes disponíveis. Consulte as opções de fonte.

​

Prévia e controle do portal do cliente nas configurações

​

Correções e ajustes

• Avisos para equipes de contas conectadas: o vínculo com uma plataforma estava silenciando notificações mesmo quando a conta conectada tinha membros próprios. O envio foi corrigido para preservar os avisos destinados à equipe daquela conta. Pessoas que operam diretamente a conta continuam recebendo suas notificações, independentemente desse vínculo.

​

Melhorias

• Disponibilidade inicial do link público: cada organização passou a receber o link do portal já ativo, com endereços separados para teste e produção. O link pode ser desativado e reativado nas configurações. Ele abre a página onde o cliente informa seu e-mail para receber acesso, simplificando o compartilhamento do portal.
• Preparação da experiência no assistente de ativação: os ajustes de marca, domínio e checkout passaram a fazer parte do cadastro inicial da plataforma. São configurações de recursos que já existiam, reunidas no assistente para que a equipe prepare a experiência oferecida aos seus clientes durante a ativação. Entenda a marca da plataforma.