Changelog da API - AbacatePay

Acompanhe as atualizações e o histórico de versões da API. Este changelog é atualizado continuamente com melhorias, correções e mudanças relevantes. Sugestões de features ou melhorias podem ser enviadas pela área de Roadmap no dashboard. Feedbacks também são bem-vindos no nosso Discord (#dev).

Atualizações Recentes

Assinaturas: checkout e assinatura agora têm rotas separadas

Quando você cria uma assinatura, existem dois objetos:

Objeto	ID	Quando passa a existir
Checkout de assinatura	`bill_...`	Ao chamar `POST /v2/subscriptions/create`
Assinatura	`subs_...`	Quando o cliente paga o checkout

Até agora, o checkout de assinatura não aparecia em nenhuma listagem. A partir de hoje, ele tem rotas próprias.

Ação necessária se você busca ou exclui checkouts de assinatura pelas rotas de checkout. Essas rotas passam a retornar erro para checkout de assinatura:

Antes	Agora
`GET /v2/checkouts/get`	`GET /v2/subscriptions/checkouts/get`
`GET /v2/payment-links/get`	`GET /v2/subscriptions/checkouts/get`
`POST /v2/checkouts/delete`	`POST /v2/subscriptions/checkouts/delete`
`POST /v2/payment-links/delete`	`POST /v2/subscriptions/checkouts/delete`

Os parâmetros e o formato da resposta não mudam.

Novas rotas:

Buscar checkout de assinatura: GET /v2/subscriptions/checkouts/get
Listar checkouts de assinatura: GET /v2/subscriptions/checkouts/list
Deletar checkout de assinatura: POST /v2/subscriptions/checkouts/delete (não cancela as assinaturas já criadas)

Da assinatura para o checkout:

Toda assinatura agora traz o campo checkoutId.
Um checkout pode gerar várias assinaturas, uma por cliente que pagou. Para encontrá-las, use GET /v2/subscriptions/list?checkoutId=bill_....

{
  "id": "subs_abc123xyz",
  "checkoutId": "bill_abc123xyz",
  "customerId": "cust_abc123xyz",
  "status": "ACTIVE"
}

Veja a referência de assinaturas para o fluxo completo.

Correções em checkouts e assinaturas

GET /v2/subscriptions/get: os filtros externalId e customerId agora funcionam.
Rotas de busca exigem um identificador: /checkouts/get, /payment-links/get e /subscriptions/get pedem id, externalId ou customerId. Antes, sem nenhum deles, retornavam um registro qualquer.
customerId inexistente não retorna mais erro 500.
Filtro method: method=PIX agora também traz checkouts que aceitam PIX junto com outros métodos.
Status atualizado mais rápido: o cache das rotas de busca caiu de 1 hora para 60 segundos.
Reembolso de assinatura: a mensagem de erro agora diz que esse reembolso não é suportado pela API v2, em vez de indicar outra rota.

Webhooks: retentativas automáticas

Quando seu endpoint de webhook fica fora do ar ou responde com erro temporário, a AbacatePay agora reenvia o evento automaticamente até ele ser entregue.O que mudou:

Falhas temporárias são retentadas em 5s, 5min, 30min, 2h, 5h e 10h — até 7 tentativas em cerca de 18 horas
Geram retentativa: timeout de 30 segundos, erro de conexão/DNS/TLS, 5xx, 408 e 429
Não geram retentativa: 3xx e os demais 4xx (ex.: 400, 401, 404). 410 Gone continua desativando o webhook
Todas as tentativas de um evento chegam com o mesmo id no corpo, para você ignorar duplicatas
Cada tentativa aparece nos logs do webhook no dashboard
Desativar ou excluir o webhook descarta as retentativas pendentes
O reenvio manual pelo dashboard continua fazendo uma única tentativa
Vale para webhooks v1 e v2, em Dev mode e em Produção

Ação recomendada: se seu endpoint ainda não trata eventos repetidos, passe a guardar o id de cada evento processado e responda 200 OK sem reprocessar quando ele chegar de novo. Sem isso, um endpoint que voltou do ar pode processar o mesmo pagamento mais de uma vez.

Exemplo:

const eventId = req.body.id; // o mesmo em todas as tentativas

if (await db.events.findOne({ id: eventId })) {
  return res.status(200).json({ ok: true });
}

await processEvent(req.body);
await db.events.insert({ id: eventId, processedAt: new Date() });

return res.status(200).json({ ok: true });

Consulte Entrega e retentativas para detalhes completos.

PIX transparente: travar o pagador (`ensureSameTaxId`)

Agora é possível exigir que o PIX seja pago pelo mesmo CPF/CNPJ informado no cliente da cobrança. Se outra pessoa tentar pagar o QR Code, o pagamento é recusado.O que mudou:

Novo campo opcional ensureSameTaxId (boolean, padrão false) em POST /v2/transparents/create com method: "PIX"
Exige customer com taxId; sem isso a API retorna ensureSameTaxId requires a customer with taxId
Depende do provedor de PIX da conta — se o provedor ativo não suportar a trava, a API retorna ensureSameTaxId is not supported by the current PIX provider
Ignorado em boleto e não aplicado em devMode

Exemplo:

{
  "method": "PIX",
  "data": {
    "amount": 10000,
    "ensureSameTaxId": true,
    "customer": {
      "name": "Daniel Lima",
      "email": "daniel_lima@abacatepay.com",
      "taxId": "123.456.789-01",
      "cellphone": "(11) 4002-8922"
    }
  }
}

Consulte Criar cobrança PIX para detalhes completos.

Listagem: filtro por data (`startDate` / `endDate`)

Todos os endpoints de listagem da API v2 agora suportam filtro por intervalo de datas de criação, além da paginação por cursor já existente.O que mudou:

Novos query params opcionais startDate e endDate (YYYY-MM-DD) em todas as rotas GET /v2/*/list
Compatível com limit, after e before — paginação e filtro de data podem ser usados juntos
As datas são interpretadas no fuso horário America/Sao_Paulo (início do dia para startDate, fim do dia para endDate)
Validações aplicadas automaticamente:
- startDate não pode ser posterior a endDate
- Nenhuma data pode ser anterior a 2024-01-01
- Nenhuma data pode ser superior a 1 ano no futuro em relação à data atual

Endpoints afetados:Clientes, cupons, produtos, checkouts, links de pagamento, assinaturas, webhooks, saques, PIX enviados, checkouts transparentes e demais rotas */list da v2.Exemplo:

GET /v2/customers/list?startDate=2026-01-01&endDate=2026-01-31&limit=50

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "hasMore": false,
    "next": null,
    "before": null
  },
  "error": null
}

Consulte Paginação e filtro por data para detalhes completos.

Boleto: data de vencimento customizável (`dueDate`)

Agora é possível definir a data de vencimento do boleto via API. Antes o vencimento era sempre de 3 dias úteis.O que mudou:

Novo campo opcional dueDate (YYYY-MM-DD) em POST /v2/checkouts/create e POST /v2/transparents/create (com method: "BOLETO")
Se omitido, o vencimento padrão continua sendo 3 dias úteis
Regras: só válido com boleto; não pode ser data no passado; máximo de 365 dias no futuro
A resposta do checkout expõe dueDate (string | null)
No transparente, a resposta continua com expiresAt (ISO datetime no fim do dia do dueDate)

Exemplo — Checkout:

{
  "methods": ["BOLETO"],
  "dueDate": "2026-08-15",
  "items": [{ "id": "prod_abc123", "quantity": 1 }]
}

Exemplo — Transparente:

{
  "method": "BOLETO",
  "data": {
    "amount": 5000,
    "dueDate": "2026-08-15",
    "customer": {
      "name": "Cliente",
      "taxId": "11144477735",
      "email": "cliente@email.com"
    }
  }
}

Consulte Data de vencimento do boleto e Criar cobrança Boleto.

Saques via API v1: validação de titularidade obrigatória

A partir de hoje, saques criados via API v1 passam a ter a titularidade do destinatário validada. Não será mais permitido enviar dinheiro para uma chave PIX cujo CPF/CNPJ seja diferente do CPF/CNPJ da sua conta AbacatePay.O que mudou:

Saques via POST /v1/payouts/create agora rejeitam chaves PIX cujo taxId do titular seja diferente do taxId da conta autenticada
Tentativas de saque para chaves de terceiros retornam erro 400 com a mensagem indicando a incompatibilidade de titularidade

O que fazer se você precisa enviar dinheiro a terceiros?Use a rota de Enviar PIX da API v2, que foi projetada exatamente para esse caso de uso:

POST /v2/pix/send

{
  "amount": 10000,
  "description": "Pagamento fornecedor #42",
  "externalId": "pix-123",
  "pixKey": "contato@fornecedor.com",
  "pixKeyType": "EMAIL"
}

Consulte a documentação de Enviar PIX para mais detalhes e tipos de chave aceitos.

Se o seu sistema usa POST /v1/payouts/create para transferir valores a terceiros, a integração precisa ser atualizada para POST /v2/pix/send. Chamadas que tentarem enviar para uma chave com taxId diferente passarão a falhar a partir de hoje.

Checkout Transparente: campo `receiptUrl` na resposta

Os endpoints de checkout transparente agora retornam o campo receiptUrl no objeto de resposta, em todos os métodos de pagamento (PIX, Boleto e Cartão).O que mudou:

Adicionado campo receiptUrl (string | null) às respostas de POST /v2/transparents/create, GET /v2/transparents/get e GET /v2/transparents/list
O campo é null enquanto a cobrança está pendente e é preenchido automaticamente com a URL do comprovante após o pagamento ser confirmado

Exemplo de resposta após pagamento confirmado:

{
  "data": {
    "id": "pix_char_abc123xyz",
    "status": "PAID",
    "receiptUrl": "https://app.abacatepay.com/receipts/pix_char_abc123xyz",
    ...
  },
  "success": true,
  "error": null
}

Produtos digitais: arquivo para download

Produtos agora suportam um PDF vinculado para entrega digital. Após o pagamento ser confirmado, o comprador recebe acesso automático ao arquivo — sem nenhuma etapa manual da sua parte.Casos de uso: e-books, ingressos, licenças de software, apostilas, certificados.O que mudou:

Novo campo opcional fileUrl em POST /v2/products/create — informe a URL pública de um PDF (máximo 20 MB); a AbacatePay baixa e armazena o arquivo de forma segura
Novo campo hasFile (boolean) no modelo Product — retornado em todos os endpoints de produto; indica se há arquivo vinculado
O URL real do arquivo nunca é exposto pela API — segurança por padrão

Exemplo:

POST /v2/products/create
{
  "externalId": "ebook-guia-completo",
  "name": "E-book: Guia Completo de Vendas Online",
  "price": 4990,
  "currency": "BRL",
  "fileUrl": "https://exemplo.com/guia-completo.pdf"
}

// Resposta
{
  "data": {
    "id": "prod_abc123xyz",
    "name": "E-book: Guia Completo de Vendas Online",
    "hasFile": true,
    "price": 4990,
    ...
  },
  "success": true,
  "error": null
}

Consulte a documentação de produtos para mais detalhes.

Correção: `imageUrl` de produto agora funciona via API

O campo imageUrl em POST /v2/products/create não estava sendo processado corretamente. A imagem era recebida mas ignorada — o produto era criado sem imagem mesmo quando uma URL válida era enviada.O que foi corrigido:

A API agora baixa a imagem da URL fornecida e a armazena internamente (assim como já ocorre com fileUrl)
O campo foi renomeado de image para imageUrl no contrato da API, corrigindo uma inconsistência que impedia o campo de ser reconhecido
Validações adicionadas: a URL deve apontar para um arquivo de imagem válido; tamanho máximo de 5 MB

Se você tentou criar produtos com imagem via API e o campo não era persistido, basta recriar ou atualizar o produto com imageUrl.

Assinaturas: novo ciclo trimestral (`QUARTERLY`) e PIX Automático

Duas melhorias no fluxo de assinaturas foram lançadas hoje.

Ciclo trimestral

O valor QUARTERLY foi adicionado ao campo cycle de produtos e ao campo frequency.cycle de assinaturas. Use para cobranças a cada 3 meses.Ciclos disponíveis: WEEKLY · MONTHLY · QUARTERLY · SEMIANNUALLY · ANNUALLY

POST /v2/products/create
{
  "externalId": "plano-trimestral",
  "name": "Plano Trimestral",
  "price": 12990,
  "currency": "BRL",
  "cycle": "QUARTERLY"
}

PIX Automático para assinaturas

Lojas com o recurso PIX Automático habilitado podem agora criar assinaturas com methods: ["PIX"]. Anteriormente, assinaturas aceitavam apenas cartão de crédito.

POST /v2/checkouts/create
{
  "items": [{ "id": "prod_abc123", "quantity": 1 }],
  "methods": ["PIX"],
  ...
}

PIX Automático para assinaturas está disponível mediante habilitação no dashboard. Entre em contato com o suporte caso seu plano ainda não tenha acesso.

Reembolsos via API

Três novos endpoints permitem solicitar reembolso diretamente pela API, cobrindo os três fluxos de cobrança da plataforma.

Endpoint	Uso
`POST /v2/checkouts/refund`	Reembolsa uma cobrança de checkout único (`bill_`, `char_`, `pix_char_` ou `card_`)
`POST /v2/payment-links/refund`	Reembolsa um pagamento de link de pagamento (`char_`, `pix_char_` ou `card_`)
`POST /v2/transparents/refund`	Reembolsa uma cobrança de checkout transparente

Permissão necessária: REFUND:CREATEBody (todos os endpoints):

{
  "id": "char_abc123xyz",
  "reason": "Solicitação do cliente"
}

Resposta:

{
  "data": {
    "id": "ref_abc123xyz",
    "status": "PENDING",
    "amount": 4990,
    "reason": "Solicitação do cliente",
    "originalId": "char_abc123xyz",
    "createdAt": "2026-05-14T14:30:00.000Z"
  },
  "success": true,
  "error": null
}

Use o id correto para cada rota: bill_ refere-se ao checkout, enquanto char_, pix_char_ e card_ referem-se à cobrança individual. Passar o ID errado retorna uma mensagem de erro indicando qual rota usar.

Assinaturas: cancelar, alterar plano e registrar uso

Três novos endpoints de gerenciamento de assinaturas foram adicionados à API v2, completando o ciclo de vida de cobranças recorrentes.O que mudou:

POST /v2/subscriptions/cancel — cancela uma assinatura ativa imediatamente, interrompendo todas as cobranças futuras
POST /v2/subscriptions/change-plan — troca o produto principal da assinatura (upgrade ou downgrade); o novo valor começa a ser cobrado no próximo ciclo
POST /v2/subscriptions/record-usage — registra unidades de uso de produtos pay-as-you-go vinculados à assinatura; o total é incluído na próxima cobrança do ciclo

Permissões necessárias:

Endpoint	Permissão
`POST /subscriptions/cancel`	`SUBSCRIPTION:DELETE`
`POST /subscriptions/change-plan`	`SUBSCRIPTION:CREATE`
`POST /subscriptions/record-usage`	`SUBSCRIPTION:CREATE`

Consulte a documentação de assinaturas para exemplos completos e detalhes de cada endpoint.

Webhooks de Assinatura: novos eventos `subscription.plan_changed` e `subscription.payment_failed`

Dois novos eventos de webhook foram adicionados ao fluxo de assinaturas, dando mais visibilidade sobre o ciclo de vida das cobranças recorrentes dos seus clientes.O que mudou:

subscription.plan_changed — disparado quando o cliente muda de plano dentro de uma assinatura ativa (upgrade ou downgrade). O payload inclui o objeto subscription atualizado com o novo valor e frequência.
subscription.payment_failed — disparado quando uma tentativa de cobrança recorrente falha (ex: cartão recusado, saldo insuficiente). O payload inclui o objeto payment com o status FAILED e o campo reason indicando o motivo da falha.

Por que isso importa?Antes, quando um pagamento falhava ou um plano era alterado, seu sistema dependia de consultas ativas à API para detectar a mudança. Agora você recebe a notificação automaticamente, podendo reagir em tempo real — enviar um e-mail de cobrança, pausar acesso, ou registrar a troca de plano sem nenhuma consulta adicional.Eventos disponíveis em assinaturas:

Evento	Quando é disparado
`subscription.completed`	Assinatura criada e ativada
`subscription.renewed`	Cobrança recorrente paga com sucesso
`subscription.cancelled`	Assinatura cancelada
`subscription.plan_changed`	Plano da assinatura alterado
`subscription.payment_failed`	Tentativa de cobrança recorrente falhou

API v2 disponível para todos

A API v2 está agora disponível publicamente para todos os integradores, encerrando a fase beta. Não é mais necessário entrar em contato com o suporte para obter acesso.O que mudou:

A API v2 deixa de ser exclusiva para clientes selecionados e passa a ser o padrão para todos
Novos cadastros já têm acesso à v2 diretamente, sem nenhuma etapa adicional
Toda a documentação oficial passa a referenciar a v2 como versão atual

Próximos passos recomendados:Se você ainda utiliza a v1, recomendamos iniciar a migração para a v2. A v1 continuará funcionando até 1º de março de 2028.

Checkout Transparente: rotas de Boleto e Boleto Transparente

Adicionadas as rotas de Boleto e Boleto Transparente ao Checkout Transparente, permitindo a criação de cobranças via boleto bancário diretamente pela API.O que mudou:

Adicionado suporte ao método BOLETO na rota POST /v2/transparents/create
Boleto passa a ser uma opção de pagamento no fluxo de checkout transparente

Exemplo de uso:

// POST /v2/transparents/create
{
  "method": "BOLETO",
  "data": {
    "amount": 10000,
    "customer": {
      "name": "João Silva",
      "taxId": "123.456.789-00",
      "email": "joao@exemplo.com"
    }
  }
}

Checkouts e Assinaturas: suporte ao campo `metadata` na criação

As rotas de criação de cobrança passam a aceitar e persistir um campo metadata customizado enviado pelo integrador.O que mudou:

Adicionado campo metadata (objeto chave-valor) no body das rotas:
- POST /v2/checkouts/create
- POST /v2/subscriptions/create
O metadata enviado é salvo e retornado no objeto de cobrança dentro do campo metadata

Exemplo de uso:

// POST /v2/checkouts/create
{
  "items": [{ "id": "prod_abc123", "quantity": 1 }],
  "metadata": {
    "orderId": "order_xyz",
    "source": "mobile"
  },
  ...
}

Resposta:

{
  "id": "bill_abc123",
  "metadata": {
    "orderId": "order_xyz",
    "source": "mobile"
  },
  ...
}

Webhooks de Assinatura: novo campo `checkout` no payload

Os eventos de assinatura (subscription.completed, subscription.renewed, subscription.cancelled) passam a retornar um novo campo checkout dentro de data, contendo o objeto completo do checkout associado à cobrança.O que mudou:

Adicionado campo checkout em data com os detalhes do checkout associado à cobrança (id, url, amount, items, status, methods, etc.)
Adicionado campo id no nível raiz do payload (identificador único do log do webhook)

Estrutura anterior:

{
  "event": "subscription.completed",
  "data": {
    "subscription": { ... },
    "customer": { ... },
    "payment": { ... },
    "payerInformation": { ... }
  }
}

Nova estrutura:

{
  "id": "log_abc123xyz",
  "event": "subscription.completed",
  "data": {
    "subscription": { ... },
    "customer": { ... },
    "payment": { ... },
    "payerInformation": { ... },
    "checkout": { ... }
  }
}

Nova versão da API

A API v2 está em beta e passa a ser o novo padrão oficial. Tudo que é novo daqui pra frente roda nela.O que isso significa na prática?Todas as features novas — Checkout Transparente, Cartão de crédito, Assinatura ou qualquer novidade que vier — estarão disponíveis somente na API v2. Se você quiser usar o que há de mais recente, v2 é o caminho.Como usar a API v2?A API v2 está disponível para clientes selecionados até o fim da fase beta. Se você quiser participar do beta, entre em contato com o nosso suporte ao cliente.Posso usar v1 e v2 ao mesmo tempo?Pode, sim. As duas convivem em paralelo. Mas a gente recomenda migrar para a v2 o quanto antes: mais estabilidade e acesso a todas as funcionalidades novas.E a API v1?A API v1 segue funcionando e será mantida até 1º de março de 2028. Depois dessa data ela será descontinuada. Então vale ir se organizando e fazendo a migração com calma.Se você ainda precisa consultar a documentação da v1 durante a migração:

Em produção, selecione a versão v1 no seletor de versões no topo desta documentação ou acessar o link

Esquecemos os updates antes da v2. Prometemos que todo novo update aparecerá por aqui.

​Atualizações Recentes

​Assinaturas: checkout e assinatura agora têm rotas separadas

​Correções em checkouts e assinaturas

​Webhooks: retentativas automáticas

​PIX transparente: travar o pagador (ensureSameTaxId)

​Listagem: filtro por data (startDate / endDate)

​Boleto: data de vencimento customizável (dueDate)

​Saques via API v1: validação de titularidade obrigatória

​Checkout Transparente: campo receiptUrl na resposta

​Produtos digitais: arquivo para download

​Correção: imageUrl de produto agora funciona via API

​Assinaturas: novo ciclo trimestral (QUARTERLY) e PIX Automático

​Ciclo trimestral

​PIX Automático para assinaturas

​Reembolsos via API

​Assinaturas: cancelar, alterar plano e registrar uso

​Webhooks de Assinatura: novos eventos subscription.plan_changed e subscription.payment_failed

​API v2 disponível para todos

​Checkout Transparente: rotas de Boleto e Boleto Transparente

​Checkouts e Assinaturas: suporte ao campo metadata na criação

​Webhooks de Assinatura: novo campo checkout no payload

​Nova versão da API

Atualizações Recentes

Assinaturas: checkout e assinatura agora têm rotas separadas

Correções em checkouts e assinaturas

Webhooks: retentativas automáticas

PIX transparente: travar o pagador (`ensureSameTaxId`)

Listagem: filtro por data (`startDate` / `endDate`)

Boleto: data de vencimento customizável (`dueDate`)

Saques via API v1: validação de titularidade obrigatória

Checkout Transparente: campo `receiptUrl` na resposta

Produtos digitais: arquivo para download

Correção: `imageUrl` de produto agora funciona via API

Assinaturas: novo ciclo trimestral (`QUARTERLY`) e PIX Automático

Ciclo trimestral

PIX Automático para assinaturas

Reembolsos via API

Assinaturas: cancelar, alterar plano e registrar uso

Webhooks de Assinatura: novos eventos `subscription.plan_changed` e `subscription.payment_failed`

API v2 disponível para todos

Checkout Transparente: rotas de Boleto e Boleto Transparente

Checkouts e Assinaturas: suporte ao campo `metadata` na criação

Webhooks de Assinatura: novo campo `checkout` no payload

Nova versão da API