Alteração no formato dos identificadores de cobranças
O Asaas realizará uma atualização no formato dos identificadores de cobranças (Payment) retornados pela API.
Com essa alteração, os identificadores de novas cobranças poderão conter o caractere underscore (_), mantendo o mesmo tamanho atual.
A mudança estará disponível no Sandbox a partir de 9 de novembro de 2026 e será disponibilizada gradualmente em Produção entre 23 e 27 de novembro de 2026.
O que muda?
O identificador público das cobranças passará a incluir um segmento numérico separado por underscore (_).
Formato atual:
pay_a1B2c3D4e5F6g7H8
Novo formato:
pay_1_a1B2c3D4e5F6g7
O segmento numérico poderá variar de 1 a 9.
O tamanho total do identificador permanece o mesmo, com 20 caracteres. A alteração ocorre apenas na sua composição.
O que muda para a integração?
Os endpoints da API e o funcionamento das cobranças permanecem inalterados.
Entretanto, integrações que realizam validações específicas sobre o formato dos identificadores poderão precisar de ajustes.
Recomendamos verificar se sua integração:
- Aceita o caractere underscore (
_) nos identificadores de cobranças. - Utiliza expressões regulares ou validações que consideram apenas letras e números após o prefixo
pay_. - Realiza extração ou manipulação de partes do identificador com base em posições fixas.
- Armazena os identificadores em campos com restrições sobre os caracteres permitidos.
Importante: os identificadores devem ser tratados como valores opacos, sem depender de sua estrutura interna ou de um formato específico.
E as cobranças já existentes?
Os identificadores das cobranças existentes permanecerão inalterados.
Durante e após a liberação gradual, os dois formatos poderão coexistir. Por isso, é importante que as integrações estejam preparadas para processar ambos.
Cronograma de liberação
A atualização seguirá o seguinte cronograma:
- 09/11/2026: disponibilização do novo formato para 100% das contas em Sandbox, permitindo que os clientes realizem testes de compatibilidade.
- 09/11 a 20/11/2026: período para testes e adequação das integrações antes da liberação em Produção.
- 23/11/2026: início da liberação gradual em Produção, por grupos de clientes.
- 27/11/2026: previsão de conclusão da liberação para todos os clientes em Produção.
Recomendamos utilizar o período de testes no Sandbox para revisar as validações relacionadas aos identificadores de cobranças e garantir a compatibilidade com o novo formato antes da atualização em Produção.