> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog da API

> Mantenha-se atualizado com as mudanças e histórico de versões da API

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

**10 de Nov, 2026**

## Saques idempotentes pelo `externalId`

`POST /v2/payouts/create` e `POST /v2/sub-accounts/withdraw` agora tratam o `externalId` como chave de idempotência, como o `POST /v2/pix/send`.

* Repetir o `POST` com o mesmo `externalId` e o mesmo `amount`, por exemplo depois de um timeout, devolve o saque que já existe, em qualquer status, e não manda outro Pix.
* Com o mesmo `externalId` e outro `amount`, a API responde `externalId já usado em outro envio com valor diferente`.
* Saques e envios de Pix da loja dividem os mesmos `externalId`. Um `externalId` usado no saque de uma subconta não vale para a loja nem para outra subconta: a API responde `externalId já usado em um envio de outro saldo (da loja ou de outra subconta)`.
* No `POST /v2/payouts/create`, o `externalId` continua opcional. Sem ele, cada chamada cria um saque novo.

Veja [Saques](https://docs.abacatepay.com/pages/dinheiro/saques.md#idempotência-pelo-externalid) e [Subcontas](https://docs.abacatepay.com/pages/dinheiro/subcontas-e-split.md#regras-do-saque-da-subconta).

**02 de Nov, 2026**

## Subcontas e split no PIX

Marketplaces agora podem separar o saldo de cada vendedor dentro da própria conta.

* `POST /v2/sub-accounts/create` cadastra o vendedor pelo CPF ou CNPJ. `GET /v2/sub-accounts/get` e `GET /v2/sub-accounts/list` trazem o saldo de cada subconta.
* Novo campo `data.splits` em `POST /v2/transparents/create` com `method: "PIX"`: quando o PIX é pago, cada parte vai para a subconta indicada.
* `POST /v2/sub-accounts/withdraw` saca o saldo da subconta por PIX, sempre para a chave CPF/CNPJ do titular.
* Novas permissões `SUB_ACCOUNT:CREATE`, `SUB_ACCOUNT:READ` e `SUB_ACCOUNT:WITHDRAW`.

O recurso precisa ser habilitado pelo suporte. Veja [Subcontas](https://docs.abacatepay.com/pages/sub-accounts/reference.md).

**27 de Out, 2026**

## Pix por chave fixa

Receba Pix numa chave fixa da sua conta, sem gerar cobrança. O recurso é liberado conta a conta e funciona só em produção.

* A chave fica em **Cobranças → Chave Pix** no dashboard, com a lista dos Pix recebidos.
* Cada Pix recebido dispara o webhook v2 `pix_key.received`, com valor, taxa e pagador. O reembolso, feito pelo dashboard, dispara `pix_key.refunded`.
* A taxa é a mesma do Pix por QR Code da conta.

Veja [Receber Pix por chave fixa](https://docs.abacatepay.com/pages/guides/pix-chave-fixa.md).

**20 de Out, 2026**

## Cupom em assinatura: só no cartão

Cupom em assinatura vale só quando ela é cobrada só no cartão e o produto não tem período de teste.

* Com `PIX` (Pix Automático), o campo de cupom some do checkout e o cupom é recusado, porque o mandato fixa o valor.
* Com `trialDays`, também não há cupom.
* A criação pela API continua aceitando `coupons`; a regra vale na hora do pagamento.

Veja [Cupons em assinatura](https://docs.abacatepay.com/pages/subscriptions/reference.md#cupons-em-assinatura).

**20 de Out, 2026**

## Upsell identificado no webhook

O `checkout.completed` do pagamento de um upsell agora se distingue do da compra:

* `isUpSell: true` no evento do upsell (`false` nos demais).
* `items` traz só o produto de upsell, em vez de repetir os itens da compra.
* `paidAmount` soma a compra e o upsell. Antes, ficava só com o preço do upsell.
* Com `completionUrl`, a tela de sucesso espera o cliente tocar em **Continuar** enquanto a oferta estiver aberta.

Veja o guia [Oferecer um upsell depois do pagamento](https://docs.abacatepay.com/pages/guides/upsell.md).

**20 de Out, 2026**

## Cartão: repasse da taxa ao cliente

Novo campo `card.passFeesToCustomer` em `POST /v2/checkouts/create` e `POST /v2/payment-links/create`: o cliente paga a taxa do cartão e você recebe o preço cheio.

* O checkout mostra o total de cada opção de parcela, já com o acréscimo.
* O acréscimo pago vem em `customerFee` (centavos) no `GET /v2/checkouts/get` e no webhook `checkout.completed`, que traz em `amount` o total pago.
* Só vale no cartão. PIX, boleto, Apple Pay e Google Pay cobram o preço normal, e assinatura não aceita.

Veja [Repassar a taxa ao cliente](https://docs.abacatepay.com/pages/payment/installments.md#repassar-a-taxa-ao-cliente).

**20 de Out, 2026**

## Checkout com cupom de 100% fecha como `REDEEMED`

Com um cupom que zera o valor, o cliente fecha o checkout sem pagar, no PIX e no cartão. Antes, o pagamento falhava.

* O checkout passa a `status: "REDEEMED"`.
* O webhook `checkout.completed` chega com esse status e `amount: 0`.
* Num link de pagamento, o link continua `ACTIVE`.

Veja [Cupons](https://docs.abacatepay.com/pages/coupons/reference.md).

**20 de Out, 2026**

## Correções em clientes, saques e checkouts

* `POST /v2/customers/create` passa a gravar `metadata` e `address`, que antes eram descartados. Os valores de `metadata` precisam ser texto: número ou objeto é recusado.
* `GET /v2/payouts/list` e `GET /v2/pix/list` listam só saques e PIX enviados. Antes, traziam também pagamentos recebidos e reembolsos.
* `interest` e `fine` vêm `null` quando não foram configurados, nos checkouts e no boleto transparente. Antes, vinham `{}`.

Veja [Criar um cliente](https://docs.abacatepay.com/pages/client/create.md).

**20 de Out, 2026**

## Comprovante preenchido no transparente e nos webhooks

O `receiptUrl` vinha sempre `null` em alguns lugares. Agora traz o link do comprovante em:

* `GET /v2/transparents/get` e `GET /v2/transparents/list`, no PIX, no boleto e no cartão.
* Webhooks `transparent.*`, `payout.*` e `transfer.*`.
* `payment.receiptUrl` dos webhooks de assinatura.

Cobranças pagas antes de 13/10/2026 continuam com `receiptUrl: null`.

**19 de Out, 2026**

## Portal do cliente

Novo endpoint `POST /v2/customer-portal/create`: gera um link para o seu cliente gerenciar sozinho o que comprou num checkout.

* O cliente entra com um código enviado ao e-mail dele.
* Ele vê os pagamentos, pede reembolso (automático), cancela a assinatura e troca o cartão.
* Um link por cliente e checkout; chamar de novo devolve o mesmo link.

Veja [Portal do cliente](https://docs.abacatepay.com/pages/customer-portal/reference.md).

**16 de Out, 2026**

## Checkout: flags para pular as etapas de dados do cliente

O link do checkout aceita duas flags para o cliente ir direto ao pagamento:

```
https://app.abacatepay.com/pay/bill_abc123xyz?skip_customer=true&skip_address=true
```

| Flag | O que faz |
| - | - |
| `skip_customer=true` | Tira a etapa de dados pessoais. A cobrança sai sem os dados do cliente. |
| `skip_address=true` | Tira a etapa de endereço. |

* **PIX:** quem pagou chega pelo banco, em `payerInformation` no webhook.
* **Cartão:** o cliente da cobrança é o titular, com o CPF informado no formulário do cartão.
* **Boleto, Apple Pay e Google Pay:** somem com `skip_customer`, porque precisam dos dados de quem paga.
* **Assinatura:** as flags não valem.
* Não precisa mudar nada na API: as flags vão direto no link.

Veja [Pular as etapas de dados do cliente](https://docs.abacatepay.com/pages/payment/reference.md#pular-as-etapas-de-dados-do-cliente).

**12 de Out, 2026**

## Cartão no checkout transparente

Dá para cobrar cartão de crédito dentro do seu site, sem redirecionar o cliente, com `method: "CARD"` em `POST /v2/transparents/create`.

* O formulário de cartão vem do [abacatepay.js](https://docs.abacatepay.com/pages/transparents/abacatepay-js.md) e usa a [chave pública](https://docs.abacatepay.com/pages/transparents/public-key.md) (`pk_...`), que pode ficar no navegador.
* A primeira cobrança usa o token `ctok_` gerado no navegador, que vale 60 segundos e uma cobrança.
* A resposta traz o `cardToken`, que permite [cobrar o mesmo cartão de novo](https://docs.abacatepay.com/pages/guides/cartao-salvo.md) sem o cliente digitar nada.
* Parcelamento de 1 a 12x com `installmentCount`.

Disponível para as contas com cartão liberado. Comece pelo [passo a passo](https://docs.abacatepay.com/pages/guides/cartao-transparente.md).

**29 de Set, 2026**

## Extrato na API

A rota que traz todas as transações da conta agora está documentada: [Listar extrato](https://docs.abacatepay.com/pages/bank-statement/list.md), `GET /v2/bank-statement/list`.

* Retorna tudo o que movimentou o saldo: pagamentos recebidos, saques, PIX enviados, estornos, taxas, antecipações e bloqueios por disputa.
* Cada transação traz suas movimentações em `movements`, com `balanceEffect` (`credit`, `debit` ou `none`) indicando o efeito no saldo disponível.
* Filtros: `status`, `method`, `kind`, `search` e período com `startDate`/`endDate`.
* Requer a permissão `BANK_STATEMENT:READ` na chave de API.

Veja a [referência do extrato](https://docs.abacatepay.com/pages/bank-statement/reference.md) para o formato completo.

**23 de Set, 2026**

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

> [!WARNING]
>
> **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](https://docs.abacatepay.com/pages/subscriptions/checkouts-get.md): `GET /v2/subscriptions/checkouts/get`
* [Listar checkouts de assinatura](https://docs.abacatepay.com/pages/subscriptions/checkouts-list.md): `GET /v2/subscriptions/checkouts/list`
* [Deletar checkout de assinatura](https://docs.abacatepay.com/pages/subscriptions/checkouts-delete.md): `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_...`.

```json theme={null}
{
  "id": "subs_abc123xyz",
  "checkoutId": "bill_abc123xyz",
  "customerId": "cust_abc123xyz",
  "status": "ACTIVE"
}
```

Veja a [referência de assinaturas](https://docs.abacatepay.com/pages/subscriptions/reference.md) para o fluxo completo.

***

**23 de Set, 2026**

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

***

**18 de Set, 2026**

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

> [!WARNING]
>
> **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:**

```ts theme={null}
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](https://docs.abacatepay.com/pages/webhooks.md#entrega-e-retentativas) para detalhes completos.

***

**11 de Set, 2026**

## 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:**

```json theme={null}
{
  "method": "PIX",
  "data": {
    "amount": 10000,
    "ensureSameTaxId": true,
    "customer": {
      "name": "Daniel Lima",
      "email": "daniel_lima@abacatepay.com",
      "taxId": "111.444.777-35",
      "cellphone": "(11) 4002-8922"
    }
  }
}
```

Consulte [Criar cobrança PIX](https://docs.abacatepay.com/pages/transparents/create.md) para detalhes completos.

***

**4 de Ago, 2026**

## 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:**

```http theme={null}
GET /v2/customers/list?startDate=2026-01-01&endDate=2026-01-31&limit=50
```

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

Consulte [Paginação e filtro por data](https://docs.abacatepay.com/pages/reference/introduction.md#paginação-e-filtro-por-data) para detalhes completos.

***

**27 de Jul, 2026**

## 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:**

```json theme={null}
{
  "methods": ["BOLETO"],
  "dueDate": "2026-08-15",
  "items": [{ "id": "prod_abc123", "quantity": 1 }]
}
```

**Exemplo — Transparente:**

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

Consulte [Data de vencimento do boleto](https://docs.abacatepay.com/pages/payment/reference.md#data-de-vencimento-do-boleto) e [Criar cobrança Boleto](https://docs.abacatepay.com/pages/transparents/boleto.md).

***

**9 de Jun, 2026**

## 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:

```http theme={null}
POST /v2/pix/send
```

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

Consulte a [documentação de Enviar PIX](https://docs.abacatepay.com/pages/pix/create.md) para mais detalhes e tipos de chave aceitos.

> [!WARNING]
>
> 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.

***

**2 de Jun, 2026**

## 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:**

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

***

**18 de Mai, 2026**

## 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:**

```json theme={null}
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"
}
```

```json theme={null}
// 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](https://docs.abacatepay.com/pages/products/reference.md) para mais detalhes.

***

**16 de Mai, 2026**

## 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`.

***

**15 de Mai, 2026**

## 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`

```json theme={null}
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.

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

> [!NOTE]
>
> 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.

***

**14 de Mai, 2026**

## 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:CREATE`

**Body (todos os endpoints):**

```json theme={null}
{
  "id": "char_abc123xyz",
  "reason": "Solicitação do cliente"
}
```

**Resposta:**

```json theme={null}
{
  "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
}
```

> [!NOTE]
>
> 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.

***

**4 de Mai, 2026**

## 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](https://docs.abacatepay.com/pages/subscriptions/reference.md) para exemplos completos e detalhes de cada endpoint.

***

**29 de Abr, 2026**

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

***

**20 de Abr, 2026**

## 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**.

***

**17 de Abr, 2026**

## 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:**

```json theme={null}
// POST /v2/transparents/create
{
  "method": "BOLETO",
  "data": {
    "amount": 10000,
    "customer": {
      "name": "João Silva",
      "taxId": "111.444.777-35",
      "email": "joao@exemplo.com"
    }
  }
}
```

***

**26 de Mar, 2026**

## 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:**

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

**Resposta:**

```json theme={null}
{
  "id": "bill_abc123",
  "metadata": {
    "orderId": "order_xyz",
    "source": "mobile"
  },
  ...
}
```

***

**19 de Mar, 2026**

## 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:**

```json theme={null}
{
  "event": "subscription.completed",
  "data": {
    "subscription": { ... },
    "customer": { ... },
    "payment": { ... },
    "payerInformation": { ... }
  }
}
```

**Nova estrutura:**

```json theme={null}
{
  "id": "log_abc123xyz",
  "event": "subscription.completed",
  "data": {
    "subscription": { ... },
    "customer": { ... },
    "payment": { ... },
    "payerInformation": { ... },
    "checkout": { ... }
  }
}
```

***

**6 de Mar, 2026**

## 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](https://docs.abacatepay.com/pages/v1/introduction.md)

***

**Antes da API v2**

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

![](https://c.tenor.com/hTqHcjxGcgAAAAAC/tenor.gif)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.