Skip to main content
Esta seção documenta os endpoints da API da AbacatePay v2. Todos os recursos seguem as mesmas convenções de autenticação, formato de resposta e tratamento de erros descritas aqui. Leia esta página uma vez — ela evita a maioria dos erros de integração.

Autenticação

Como gerar e usar suas chaves de API.

Dev mode

Testar sem risco antes de ir para produção.

Webhooks

Receber notificações de eventos em tempo real.

​
Base URL

Todas as requisições da v2 usam o seguinte endereço:
O ambiente (desenvolvimento ou produção) é determinado pela chave de API usada — não pela URL.

​
Autenticação

Toda requisição deve incluir sua chave de API no header Authorization:
Requisições sem chave ou com chave inválida retornam 401 Unauthorized. Consulte a página de autenticação para criar e gerenciar suas chaves.

​
Formato de resposta

Todos os endpoints retornam JSON com a mesma estrutura:
Em caso de erro:
Sempre verifique success antes de acessar data. Nunca assuma que a requisição funcionou apenas pelo status HTTP.

​
Códigos de status HTTP

​
Permissões

Cada chave de API pode ter permissões granulares por recurso. Se você receber 403, verifique se a chave usada tem a permissão necessária para o endpoint. Consulte a página de autenticação para ver todas as permissões disponíveis.

​
Paginação e filtro por data

Endpoints de listagem suportam paginação por cursor e filtro por intervalo de datas de criação (createdAt).

​
Paginação por cursor

A API ainda não envia o objeto pagination nas respostas de listagem. O envelope retornado hoje é apenas { data, error, success }. Para avançar, use o id do último item da página como after.
Envelope retornado hoje:
Para avançar, passe after com o id do último item recebido:

​
Filtro por data

Os dois parâmetros são opcionais e podem ser usados isoladamente ou combinados com limit, after e before.
As datas são interpretadas no fuso horário America/Sao_Paulo. Por exemplo, startDate=2026-01-15 inclui registros a partir de 15/01/2026 00:00 (horário de Brasília).
Endpoints com suporte a paginação e filtro de data: clientes, cupons, produtos, checkouts, links de pagamento, assinaturas, webhooks, saques, PIX enviados, pagamentos transparentes e demais rotas */list da v2.

​
Erros mais comuns

Verifique o tipo dos valores. A API é tipada: amount é sempre inteiro em centavos (1000 = R$ 10,00), não decimal. IDs de produtos e clientes são strings, não números.
Confirme que o header está exatamente como Authorization: Bearer SUA_CHAVE — com espaço entre Bearer e a chave, sem aspas extras.
A chave existe mas não tem a permissão necessária. Vá no dashboard → Integração → edite a chave → adicione a permissão do recurso que está tentando acessar.
Exemplo: criar uma assinatura com um produto que não tem cycle definido. Os campos estão corretos individualmente, mas a combinação não faz sentido. A mensagem de erro no campo error da resposta descreve o problema específico.
Erros 5xx são temporários. Implemente retentativas com backoff exponencial (ex: aguarde 1s, depois 2s, depois 4s). Se persistir por mais de alguns minutos, entre em contato com o suporte.

​
Dicas gerais

Use Dev mode para testes

Chaves de desenvolvimento simulam pagamentos sem cobranças reais.

Armazene a chave em variável de ambiente

Nunca comite sua chave de API no código. Use process.env, .env ou um gerenciador de segredos.

Idempotência em webhooks

Sempre registre o ID do evento recebido e descarte duplicatas.

Backoff em erros 5xx

Implemente retentativas com espera crescente para falhas temporárias.