Changelog

Ao criar uma cobrança avulsa de PIX, boleto ou cartão, o pagador recebe o e-mail com o link de pagamento se tiver contato cadastrado, no mesmo padrão das assinaturas. Antes era preciso montar um link de checkout e mandar por fora.

O que mudou:

• A criação de cobrança avulsa envia e-mail quando o cliente tem e-mail
• Cópias (CC) já configuradas na conta também valem nesse fluxo

Exemplo de criação de PIX avulso com cliente:

POST /v1/charges/pix
{
  "amount": 49.90,
  "customer": { "name": "Ana Silva", "email": "ana@email.com", "document": "12345678909" }
}

O prazo de cartão (D+N) é contado em dias corridos. Se a data cair no sábado ou no domingo, o item continua nesse dia no calendário e não é mais empurrado para a segunda, como acontecia antes. O que muda é o reconhecimento. Enquanto for fim de semana o valor fica como a receber, e o recebimento é dado como concluído no próximo dia útil. Feriados não entram nessa regra.

O que mudou:

• A data prevista aceita sábado e domingo
• No fim de semana o recebível fica pendente e o crédito é reconhecido na segunda
• Feriados não alteram a data nem o reconhecimento

A data do calendário não é mais adiada para o dia útil seguinte. Quem conciliava esperando só dias úteis precisa considerar sábado e domingo.

Assinaturas com o ciclo já quitado apareciam como atrasadas, o que disparava cobrança e aviso indevidos. A marcação de inadimplência confere o pagamento do ciclo antes.

A recorrência era aberta no dia em que a cobrança foi criada, e não no vencimento combinado, então o pagador via a data errada. A cobrança segue o vencimento do ciclo da assinatura.

O cliente não é apagado de vez. Ele fica oculto nas telas e nas listagens, e o documento e o e-mail dele podem ser cadastrados de novo. O histórico de cobranças continua no lugar. Se ainda houver assinatura em aberto, a exclusão é recusada, para o cliente não sumir com uma recorrência viva.

O que mudou:

• A exclusão oculta o cliente das listagens
• Assinatura em aberto bloqueia a operação

Se ainda existir assinatura ativa, a API responde 400. Cancele as assinaturas antes de excluir.

Exemplo de erro com assinatura aberta:

{
  "message": "Cliente possui 1 assinatura(s) em aberto. Cancele antes de excluir.",
  "code": "CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS"
}

A automação de cobrança por WhatsApp ganhou duas proteções. O vendedor consegue disparar um aviso na hora, sem esperar o próximo horário programado. A régua também deixou de mandar boleto de valor abaixo do mínimo aceito pela instituição, mensagem que chegava ao cliente com um boleto impossível de pagar.

O que mudou:

• É possível avisar uma cobrança pendente na hora
• Mensagem de boleto não sai abaixo do valor mínimo da instituição

Em alguns fluxos a taxa de saída de PIX (R$ 0,47 por padrão) deixava de ser cobrada, e a conta recebia o valor cheio. A taxa voltou a ser deduzida assim que o saque ou a transferência é confirmado, com o desconto no extrato junto da operação.

O que mudou:

• A taxa configurada na conta é cobrada no saque e na transferência
• O lançamento entra no extrato após a confirmação

O pagador que tinha o cartão recusado ainda no checkout conseguia trocar de cartão e concluir a compra, mas ficava uma cobrança automática agendada para o dia seguinte, e o cliente era cobrado duas vezes. A recusa dentro do checkout não gera mais essa retentativa.

Em alguns fluxos a resposta vinha sem o código do QR Code, e o pagador ficava sem como pagar. Toda cobrança PIX agora devolve o código para escanear ou colar no aplicativo do banco. Na mesma correção, o PIX Automático em conta de testes deixou de tocar em dinheiro de verdade.

O que mudou:

• A resposta da cobrança PIX traz o código copia e cola
• No ambiente de testes, taxa e divisão de valores ficam só no extrato local

Exemplo de recorte da resposta:

{
  "chargeId": "cha_01abc",
  "pix": { "qrCode": "00020126...BR.GOV.BCB.PIX..." }
}

Emitir, consultar, cancelar e reemitir nota seguem o mesmo caminho, e não mais um caminho por operação. A prefeitura é escolhida pela cidade da configuração da conta, e o relatório mostra número, série e situação de todas as notas na mesma lista.

O que mudou:

• Listar e emitir nota
• Consultar, cancelar e reemitir
• Relatório com número, série e status

Quando o pagamento do upgrade era recusado, a retentativa cobrava o valor do plano antigo e a assinatura ficava no plano errado mesmo depois de pagar.

Quem tivesse o código de uma cobrança de outra conta conseguia saber que ela existia pela resposta da API. A resposta virou idêntica à de um código inexistente, tanto na consulta quanto no cancelamento, no reenvio de aviso e no boleto. Nada muda para quem acessa as próprias cobranças.

Rotas de detalhe, cancelamento, aviso e boleto da cobrança.

A resposta é 404, igual a uma cobrança que não existe.

{
  "message": "Cobranca nao encontrada",
  "code": "CHARGE_NOT_FOUND"
}

Um item cobrado à parte dentro da assinatura fazia a recorrência achar que o ciclo tinha virado, antecipando a próxima fatura. Também foram corrigidos o arredondamento em duas casas e o vencimento do ajuste proporcional avulso, que caía no ciclo seguinte.

Contas PJ criam a assinatura já com a adesão ao PIX Automático, sem passar por um cadastro separado. O pagador autoriza a recorrência uma vez, pelo QR Code que fica na cobrança de adesão, e as cobranças seguintes são debitadas sozinhas. O valor mínimo de adesão é R$ 4,99 (contas internas são isentas), e o cancelamento encerra a recorrência no fim do período já pago.

O que mudou:

• Criação de assinatura aceita PIX Automático
• Valor mínimo de adesão de R$ 4,99
• O QR Code de autorização fica na cobrança de adesão
• O cancelamento vale a partir do fim do período atual

Exemplo:

POST /v1/subscriptions
{
  "customerId": "cus_01abc",
  "priceId": "price_01xyz",
  "paymentType": "pix_automatico"
}

Cobranças de ajuste proporcional, avulsas dentro da assinatura e de cartão na fatura às vezes nasciam sem a taxa registrada. O vendedor via um valor a receber maior do que o real e o extrato não fechava. Todos esses fluxos gravam o valor bruto, a taxa e o valor líquido.

O que mudou:

• A cobrança passa a trazer valor bruto, taxa e valor líquido

O pagador que estava no cartão ou no boleto muda para PIX Automático sem cancelar e recriar a assinatura, inclusive quando ela está atrasada, o que ajuda a recuperar a recorrência. A troca para PIX Automático inicia a adesão, e o detalhe da assinatura guarda o histórico de trocas. O vendedor também consegue limitar quais meios o pagador enxerga na fatura.

O que mudou:

• Troca de meio com a assinatura ativa ou inadimplente
• Destino PIX Automático inicia a adesão
• Histórico de trocas no detalhe da assinatura
• Meios permitidos na fatura são configuráveis

Até então o desconto de quem pagava adiantado era um só, herdado da configuração de boleto, e quem quisesse premiar o PIX acabava mexendo no boleto junto. Cada meio tem o seu desconto. Juros e multa continuam existindo só no boleto.

O que mudou:

• PIX tem desconto próprio
• Boleto mantém juros, multa e o desconto dele

Quem abre subcontas não precisa mais configurar as taxas uma a uma. PIX, boleto, cartão, nota fiscal e taxa de saque vêm da conta principal no momento da abertura. Se a principal não tiver alguma dessas taxas definida, vale o padrão da plataforma (PIX R$ 0,67).

O que mudou:

• Taxas herdadas da conta principal
• Taxa de abertura de subconta de R$ 15 por padrão

O ciclo com fatura vencida gerava uma segunda fatura, e o pagador ficava com duas cobranças do mesmo período em aberto.

Quem tinha em mãos o código de uma cobrança ou de uma assinatura precisava procurar pelo nome do cliente. O mesmo campo de busca aceita os dois códigos, o que resolve conciliação e atendimento. Os filtros de produto, preço, status, período e meio de pagamento continuam funcionando junto.

O que mudou:

• A busca também acha cobrança e assinatura pelo código
• Filtros de produto, preço, status e período seguem disponíveis

Exemplo:

GET /v1/charges?search=cha_01abc&limit=15

GET /v1/charges?search=sub_01xyz&limit=15

Quem tem uma chave PIX em outra instituição consegue pedir a portabilidade para a ValidaPay. Quem já tem a chave aqui aprova ou recusa o pedido de saída, e o andamento fica visível enquanto o pedido corre.

O que mudou:

• Solicitar portabilidade
• Listar e consultar o pedido
• Confirmar (somente quem é o dono atual da chave) ou cancelar

Só o dono atual da chave confirma a portabilidade. Qualquer outra conta tem a confirmação recusada.

Exemplo de solicitação:

POST /v1/wallet/pix-claims
{
  "pixKey": "ana@email.com",
  "pixKeyType": "EMAIL"
}

A atualização de cliente aceitava trocar o documento, o que transformava o cadastro em outra pessoa e bagunçava o histórico de cobranças. Só nome, e-mail, telefone e endereço podem mudar. Os demais campos são ignorados, e um documento diferente do cadastrado é recusado.

O que mudou:

• Campos permitidos de nome, e-mail, telefone e endereço
• CPF/CNPJ permanece o do cadastro

Ajustes que antes exigiam cancelar e criar de novo são feitos na própria assinatura. Mudar o dia de vencimento gera o ajuste proporcional do período e fica registrado no histórico. O cancelamento agendado aparece na listagem até a data chegar.

O que mudou:

• Novo dia de vencimento com ajuste proporcional
• E-mails em cópia nas notificações
• Cancelamento para o fim do período, com aviso por webhook

A cobrança antecipada fecha o ciclo antes do vencimento, e clicar duas vezes não gera duas cobranças. A cobrança diária, para quem trabalha com recorrência de curto prazo, depende de liberação na conta. O ciclo também mostra a taxa e o valor líquido previstos, então o vendedor sabe quanto vai receber antes do pagamento.

O que mudou:

• Cobrança antecipada com um clique e uma cobrança
• Cobrança diária exige permissão na conta
• Ciclo passa a mostrar taxa e valor líquido previstos

O rateio por percentual arredondava errado e podia deixar sobra ou falta de centavos. Os destinatários também deixaram de ser identificados pelo número interno da conta e passaram a usar o código público. Por fim, a divisão saiu do limite da cobrança avulsa, e cada cobrança de assinatura é rateada do mesmo jeito.

O que mudou:

• Destinatário identificado pelo código público da conta
• Divisão também nas cobranças de assinatura

Quando havia mais de um ciclo em aberto, a retentativa podia quitar o período errado, e o mês pago continuava aparecendo em atraso.

Quando um PIX recebido é bloqueado por suspeita de fraude, o valor deixa de entrar no saldo disponível e aparece como saldo retido, com uma linha própria no extrato. Antes o dinheiro simplesmente não aparecia e o vendedor não sabia o motivo. Quando o bloqueio cai, o crédito liberado, ou a devolução ao pagador, entra como um lançamento à parte, e o registro do bloqueio continua no histórico.

• Saldo retido enquanto o bloqueio estiver ativo
• O extrato mostra a retenção e, depois, a liberação

Quem migra de outro sistema sobe a base por planilha, sem cadastrar um a um. A planilha de clientes aceita endereço completo e valida o CEP mesmo quando o logradouro não vem preenchido. As assinaturas importadas entram já com o dia de vencimento certo e com o ajuste proporcional calculado.

• Clientes com nome, documento, e-mail, endereço e CEP
• Assinaturas com vencimento e pró-rata corretos na carga

O vendedor encerra uma disputa, corrige a defesa enviada e acompanha quanto tempo falta para o prazo acabar, com alerta quando ele está perto do fim. As evidências mostram quem é o cliente e quem contestou, o que evita defender a transação errada.

Testes com rateio e cobrança de taxa chegavam a movimentar a conta real. Tudo fica registrado só no extrato do ambiente de testes.

Quem integra pelo webhook distingue o cancelamento agendado do cancelamento imediato e reage na hora, mantendo o acesso do cliente até a data, por exemplo. O evento chega no mesmo formato dos demais avisos de assinatura.

A assinatura que passa do vencimento sem pagamento aparece como inadimplente, e não mais como simplesmente ativa. O vendedor encerra na hora quando nada foi pago ou a vigência acabou, ou agenda o encerramento para o fim do período já pago. Nesse segundo caso o integrador recebe um aviso por webhook. Cada pagamento também registra a data em que o ciclo foi quitado.

• Status de inadimplência na assinatura
• Aviso de cancelamento agendado
• Data do último pagamento do ciclo

Atende o caso em que o cliente perdeu a mensagem ou pediu o link de novo. O reenvio sai na hora, sem esperar o próximo horário da régua.

Quem estava integrando não conseguia testar o checkout com as credenciais da aplicação, porque a chamada era recusada mesmo com as credenciais certas. O token precisa ir no cabeçalho de autorização e ter o escopo da rota.

Recursos que não valem para todo cliente dependem de liberação na conta. Transferência PIX, automação de cobrança por WhatsApp e cobrança diária só aparecem para quem tem a permissão ativa.

Toda saída de dinheiro por PIX tem uma taxa fixa, de R$ 0,47 por padrão e ajustável por conta. Ela é descontada depois que a operação é confirmada e aparece no extrato junto com ela. A conta também nasce com um limite diário de transferência, de R$ 3.000 por padrão.

• Taxa padrão de saída de R$ 0,47
• Limite diário de transferência de R$ 3.000

A troca para um plano mais barato no boleto não era aplicada e o cliente seguia sendo cobrado pelo plano antigo. Na mesma correção, o item cobrado à parte voltou a ser listado na fatura da assinatura.

Contas com mais de uma adquirente de cartão viam sempre a que está marcada como padrão, ainda que o pagamento tivesse passado por outra. Isso atrapalhava a conciliação e a análise de recusas. A cobrança registra a adquirente que de fato processou.

A régua deixou de mandar tudo no mesmo horário. O aviso antes do vencimento, o do dia e o da cobrança em atraso saem em momentos diferentes. O pagador também recebe a confirmação do pagamento pelo próprio WhatsApp, sem precisar procurar o comprovante.

Procurar por "ana silva" não achava o cliente cadastrado como "Ana Silva".

Assinaturas antigas ou encerradas saem da lista do dia a dia sem serem apagadas. Ciclos, cobranças e avisos já emitidos continuam disponíveis para consulta e conciliação.

Os relatórios eram gerados como texto separado por ponto e vírgula, mas com nome de arquivo de Excel. Abrir dava aviso de arquivo corrompido e as colunas saíam embaralhadas. O arquivo agora é uma planilha real.

Útil para quem já tem o CNPJ do cliente no próprio cadastro e não guardou o número da conta na ValidaPay.

• GET /v1/accounts/cnpj/{cnpj}

Se a resposta se perde ou o cliente clica duas vezes, repetir a chamada com a mesma chave de idempotência devolve a cobrança já criada, em vez de gerar outra e cobrar o cliente em dobro.

• Cabeçalho Idempotency-Key

A emissão deixou de ser exclusiva das assinaturas. A nota sai assim que o pagamento é confirmado ou em um horário programado.

O fluxo inteiro pode ser percorrido antes de colocar a integração no ar, da criação da cobrança à simulação do pagamento e à conferência do saldo, sem dinheiro de verdade envolvido.

Sem esses dados, quem integra precisava fazer uma segunda consulta só para montar comprovante e conciliação.

A cobrança de ajuste proporcional nascia sem a taxa registrada, e o valor a receber ficava maior do que o real.

Atende casos em que quem paga não é quem recebe o serviço, como o financeiro da empresa em cópia. O e-mail informado no checkout tem prioridade sobre os demais.

Quando o cliente troca de plano no meio do período, a diferença é somada à próxima fatura, sem virar uma cobrança extra imediata. Evita mandar duas cobranças no mesmo mês.

O cliente digita o cartão uma vez e as próximas compras e renovações usam o cartão guardado, sem os dados passarem de novo pelo lojista. Junto veio uma melhora no atendimento. Quando o pagamento é recusado, a API devolve o motivo informado pela adquirente, e não uma mensagem genérica.

Quem tem a própria tela de pagamento não precisa mandar o cliente para o checkout da ValidaPay. A cobrança feita assim tem o mesmo tratamento, com taxa igual, análise de fraude e o mesmo nome na fatura do cartão.

Algumas rotas exigiam um usuário logado, o que travava integrações que rodam sem ninguém na frente da tela.

Uma padronização anterior deixou algumas rotas fora do ar e integrações pararam de funcionar. Elas foram restauradas. Na mesma revisão, a criação de sessão de checkout passou a exigir autenticação, que antes ficava aberta.

Boletos saíam com vencimento e valor diferentes dos enviados na criação da cobrança.

Quando o pagador corrigia algum dado na tela, o desconto aplicado sumia e ele pagava o valor cheio.

O valor estornado aparece no calendário e é descontado do que o vendedor tem a receber, então a previsão de recebimento fica correta. O estorno passa pela mesma adquirente que processou a cobrança original.

Chegou a alternativa ao cartão para recorrência. O pagador autoriza uma vez, pelo QR Code, e as parcelas seguintes são debitadas na conta dele sem nova ação. As cobranças respeitam a data de início combinada e, se uma falhar, o sistema tenta de novo dentro do intervalo permitido antes de dar o ciclo por perdido.

• QR Code de autorização
• Cobranças no vencimento combinado
• Novas tentativas automáticas

O vendedor vê as contestações abertas contra ele e responde com documentos e comprovantes pelo próprio produto, sem depender do suporte. Reembolsos também geram aviso para quem integra por webhook.

O número do pedido ou do contrato viaja junto da cobrança e volta no extrato, o que permite bater o recebimento com o registro interno sem depender de valor e data.

O extrato mostrava movimentações que não aconteceram, e o saldo exibido não batia com o real.

O aviso de cobrança começou a sair pelo WhatsApp, canal com mais leitura que o e-mail. O boleto enviado vence no próprio dia e continua pagável por até 30 dias.

Antes cada meio tinha o seu caminho e o seu formato. A criação virou uma só, mudando apenas o meio de pagamento, o que simplifica a integração de quem oferece as três opções.

Facilita acompanhar o desempenho de um produto específico ou de uma faixa de preço sem exportar tudo.

O cartão pode ser direcionado para a adquirente com a melhor condição, e a subconta tem a opção de simplesmente seguir a escolha da conta principal.

Pagamentos do fim do dia apareciam no dia seguinte e o fechamento diário não fechava.

Recusas chegavam como códigos sem explicação, que o vendedor não sabia repassar ao cliente.

Sem taxa configurada, a criação de cobrança no ambiente de testes falhava e travava a integração logo no começo.

O vendedor vê o que ainda vai cair na conta e o que já entrou, separado por cobrança avulsa e assinatura, sem depender só do saldo do dia.

O checkout carrega informações do sistema do vendedor junto da compra, oferece um item adicional no momento do pagamento e mantém logo e cores configurados no produto para todos os preços, sem repetir a configuração em cada um.

Antes a assinatura dependia de alguém logado no produto, o que impedia automatizar a venda pelo sistema do próprio cliente.

A conta envia PIX para uma chave informada. Consultar a chave antes só mostra os dados do destinatário para conferência, sem mandar centavos de teste como acontecia.

O vendedor define a penalidade por atraso e o desconto para quem paga adiantado, e o boleto já sai com essas regras. Na época o PIX ainda seguia a mesma configuração. Em agosto ele ganhou um desconto próprio.

Cobrança enviada por engano ou pedido desistido deixavam o cliente com um boleto válido em mãos. Com o cancelamento, o pagamento não é mais aceito.

O extrato trazia lançamentos fora do período e de tipos não selecionados.

Cupons com valor ou percentual de desconto podem ser criados, acompanhados pelo uso e aplicados tanto no checkout quanto em uma cobrança criada pela integração.

O pagador escolhe pagar por PIX ou por boleto no mesmo documento, e quem integra recebe o arquivo pronto para exibir ou enviar.

Pedidos de devolução falhavam porque o recebimento correspondente não era localizado.

Cada período da assinatura ganhou uma fatura, com os itens do plano e a diferença proporcional de mudanças feitas no meio do caminho.

Corrigir e-mail, telefone ou endereço exigia criar outro cadastro, o que duplicava o cliente e dividia o histórico.

Um produto complementar aparece na tela de pagamento e, se o cliente aceitar, entra na mesma cobrança.

Quem já usa o ValidaPix vê os recebimentos da ValidaPay lá, sem exportar e importar arquivo.

Recebimentos feitos fora de uma cobrança, direto na chave PIX da conta, não tinham taxa, o que deixava o custo inconsistente entre os fluxos. Se a conta tiver crédito de isenção, a taxa continua não sendo cobrada até o volume acabar.

O recebimento entrava sem o desconto da taxa, e o valor creditado ficava acima do combinado.

O vendedor define por quantos dias o PIX continua pagável depois do vencimento. Os dados de quem pagou e de quem recebeu ficam registrados na cobrança, o que ajuda na conciliação e em disputas.

O pedido é feito pelo próprio produto e fica registrado para análise, sem depender de contato com o suporte.

Informações como número do pedido ou identificador do carrinho podem ser anexadas à cobrança e voltam na consulta e no aviso de pagamento.

Atende campanhas e negociações comerciais. As cobranças não pagam taxa enquanto o crédito não acaba, e depois voltam à taxa normal.

Primeira entrega do canal. O aviso de cobrança começou a sair pelo WhatsApp além do e-mail.

Ao salvar, só parte das taxas era gravada, e as demais voltavam ao valor anterior sem aviso.

O endereço que recebe os avisos pode exigir credencial, para que só a ValidaPay consiga enviar eventos para ele.

Os filtros eram ignorados e as páginas repetiam registros, o que impedia varrer a lista inteira.

Sem esse evento, o sistema do vendedor não ficava sabendo da devolução e mantinha o pedido como pago.

Permite vender sem ter um plano ou uma cobrança montada antes. Basta enviar o link e definir o valor na hora.

Primeira entrega da emissão e do acompanhamento de notas dentro da ValidaPay.

Quando o valor foi rateado, a devolução também recolhe a parte de cada destinatário, em vez de sair só da conta principal.

Cada lançamento diz quanto foi de taxa e quem estava do outro lado da operação, e a lista pode ser exportada para conferência e contabilidade.

Padronização dos campos de cobrança, que estavam diferentes entre a listagem e o detalhe.

Contas com muitos clientes tinham lentidão e falha ao abrir a lista. Ela agora vem por páginas.

Quem opera com subcontas vê o saldo de cada uma sem trocar de acesso, e o webhook avisa a abertura de uma nova subconta.

Esses valores ficavam fora do rateio, então a conta principal absorvia o custo e os destinatários recebiam a mais.

Vendas avulsas também aceitam parcelamento, e não apenas as recorrentes.

O pagamento confirmava no banco, mas o saldo na ValidaPay não acompanhava, e o dinheiro parecia não ter entrado.

A página de changelog é alimentada por este arquivo e mostra, para cada mudança, a data, o tipo (novidade, melhoria, correção ou segurança) e o que foi afetado.