Changelog da API

​

Checkout Transparente: campo receiptUrl na resposta

• 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

{
  "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

• 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

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
}

​

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

• 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

​

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

​

Ciclo trimestral

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

​

PIX Automático para assinaturas

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

​

Reembolsos via API

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

{
  "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
}

​

Assinaturas: cancelar, alterar plano e registrar uso

• 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

​

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

• 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.

​

API v2 disponível para todos

• 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

​

Checkout Transparente: rotas de Boleto e Boleto Transparente

• 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

// 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

• 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

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

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

​

Webhooks de Assinatura: novo campo checkout no payload

• 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)

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

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

​

Nova versão da API

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