# Visão Geral
Source: https://docs.abacatepay.com/pages/ai/overview

Ferramentas e contexto especializado para integrar a AbacatePay com IA.

<div>
  # AbacatePay + IA

  <p>
    Use a AbacatePay diretamente em agentes de IA, editors assistidos e ferramentas de automação — sem magia, sem atrito.
  </p>
</div>

## O que está disponível

<CardGroup>
  <Card title="MCP Server" icon="plug" href="/pages/ai/mcp">
    Exponha toda a API da AbacatePay como ferramentas nativas para Claude Desktop, Cursor e qualquer cliente MCP. Crie cobranças, consulte clientes e gerencie assinaturas direto de uma conversa.
  </Card>

  <Card title="Skills" icon="book-open" href="/pages/ai/skills">
    Pacotes de contexto especializado que ensinam agentes de IA a integrar corretamente com a AbacatePay — regras de negócio, padrões técnicos e exemplos prontos.
  </Card>
</CardGroup>

***

## Para quem é cada ferramenta

|                    | MCP Server                          | Skills                                           |
| ------------------ | ----------------------------------- | ------------------------------------------------ |
| **Objetivo**       | Executar ações na API via IA        | Fornecer contexto para a IA gerar código correto |
| **Ideal para**     | Automações, assistentes, agentes    | IDEs com AI coding (Cursor, Claude Code)         |
| **Formato**        | Ferramentas MCP chamadas em runtime | Arquivos de contexto lidos pelo editor           |
| **Requer API key** | Sim                                 | Não                                              |

***

## Ecossistema

<CardGroup>
  <Card title="Documentação Oficial" icon="book" href="https://docs.abacatepay.com">
    Guia completo da API AbacatePay.
  </Card>

  <Card title="SDK Node.js" icon="box" href="https://www.npmjs.com/package/@abacatepay/sdk">
    Integração ergonômica de alto nível.
  </Card>

  <Card title="REST Client" icon="repeat" href="https://www.npmjs.com/package/@abacatepay/rest">
    Cliente HTTP tipado de baixo nível.
  </Card>
</CardGroup>


# Chaves de API
Source: https://docs.abacatepay.com/pages/authentication

Aprenda como funcionam as chaves de API e como utilizá-las para acessar a AbacatePay

<Tip>
  A **chave de API** é sua credencial de acesso à AbacatePay. Ela identifica sua conta e autoriza cada requisição enviada para a nossa API. **Sem uma chave válida, nenhum pedido será aceito.**
</Tip>

Toda requisição para a API da AbacatePay deve incluir sua chave no header `Authorization`. A chave também define o ambiente — uma chave de Dev mode simula transações, uma chave de Produção processa valores reais. Você não muda de URL para mudar de ambiente; muda a chave.

## O que você pode fazer com suas chaves

As chaves de API são gerenciadas diretamente pelo dashboard. Com elas, você pode:

* Ver todas as chaves ativas
* Criar novas chaves para diferentes projetos
* Revogar chaves comprometidas ou que não são mais usadas

<Card title="Dev mode x Produção">
  Todas as requisições usam o mesmo endpoint [api.abacatepay.com](https://api.abacatepay.com).\
  O ambiente é definido **pela chave utilizada**:

  * Chaves criadas em **Dev mode** → transações simuladas
  * Chaves criadas em **Produção** → transações reais

  Saiba mais sobre o ambiente de testes <a href="./devmode">aqui</a>.
</Card>

<Card title="Erro de Autenticação (401)">
  Você receberá um **HTTP 401** quando:

  * A chave não for enviada no header
  * A chave estiver incorreta
  * A chave tiver sido revogada
</Card>

## Permissões da chave de API

Além de identificar sua conta, a chave de API define **quais recursos** você pode acessar. Quase todos os endpoints da API exigem que a chave tenha a permissão correspondente; sem ela, a requisição será recusada (por exemplo, com **403 Forbidden**).

Ao criar ou gerenciar chaves no dashboard, você pode atribuir apenas as permissões necessárias para cada integração — por exemplo, uma chave só para leitura de clientes ou outra só para criar cobranças. Isso melhora a segurança e o princípio do menor privilégio.

**Exceção:** o endpoint de **MRR** (`/public-mrr/mrr`) é público e não exige permissão de chave.

### Permissões disponíveis

| Recurso  | Permissões                                                       |
| -------- | ---------------------------------------------------------------- |
| Checkout | `CHECKOUT:CREATE`, `CHECKOUT:READ`, `CHECKOUT:DELETE`            |
| Coupon   | `COUPON:CREATE`, `COUPON:READ`, `COUPON:UPDATE`, `COUPON:DELETE` |
| Customer | `CUSTOMER:CREATE`, `CUSTOMER:READ`, `CUSTOMER:DELETE`            |
| Product  | `PRODUCT:CREATE`, `PRODUCT:READ`, `PRODUCT:DELETE`               |
| Store    | `STORE:READ`, `STORE:CREATE`, `STORE:DELETE`                     |
| Withdraw | `WITHDRAW:CREATE`, `WITHDRAW:READ`                               |
| Connect  | `CONNECT:READ`, `CONNECT:CREATE`, `CONNECT:DELETE`               |

Cada endpoint da documentação indica qual permissão é necessária no topo da página.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized — o que verificar">
    Causas mais comuns, em ordem de frequência:

    1. O header `Authorization: Bearer SUA_CHAVE` não está sendo enviado
    2. A chave foi copiada com espaços extras ou caracteres invisíveis
    3. A chave foi revogada no dashboard
    4. Você está usando uma chave de Dev mode em uma URL que exige produção (ou vice-versa)

    Para confirmar que a chave está funcionando, teste diretamente:

    ```bash theme={null}
    curl https://api.abacatepay.com/v2/stores/get \
      -H "Authorization: Bearer SUA_CHAVE"
    ```
  </Accordion>

  <Accordion title="403 Forbidden — permissão ausente">
    A chave existe e é válida, mas não tem a permissão para o recurso solicitado. Acesse o dashboard, edite a chave e adicione a permissão necessária. Consulte a tabela de permissões acima para saber qual adicionar.
  </Accordion>

  <Accordion title="Chave de Dev mode vs Produção — qual estou usando?">
    No dashboard, as chaves de Dev mode têm um indicador visual. Se você não tem certeza, verifique o campo `devMode` em qualquer resposta da API — `true` significa Dev mode, `false` significa Produção.
  </Accordion>
</AccordionGroup>

## Boas práticas de segurança

<Card>
  * Armazene suas chaves em variáveis de ambiente
  * Nunca publique sua chave em repositórios ou grupos
  * A AbacatePay **nunca** solicitará sua chave
  * Revogue imediatamente qualquer chave que possa ter vazado
</Card>

***

## Como criar uma chave de API

Siga os passos abaixo no dashboard:

<Steps>
  <Step title="Acesse a seção de Integração">
    <Card>
      <img alt="Interface da plataforma AbacatePay mostrando o botão de criação de chave" />

      <Card title="Clique em 'Criar Chave'">
        Inicie a criação de uma nova chave de API.
      </Card>
    </Card>
  </Step>

  <Step title="Adicione uma descrição">
    <Card>
      <img alt="Formulário de criação de chave com campo de descrição" />

      <Card title="Identifique a chave">
        Use nomes claros, como “Loja Principal” ou “Ambiente de testes”.
      </Card>
    </Card>
  </Step>

  <Step title="Copie a chave gerada">
    <Card>
      <img alt="Lista de chaves com opção para copiar" />

      <Card title="Guarde com segurança">
        Copie a chave e salve em um local seguro ou gerenciador de segredos.
      </Card>
    </Card>
  </Step>
</Steps>

Depois disso, você já pode enviar requisições:

```bash theme={null}
curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  --data '{
    "amount": 1000,
    "method": "PIX"
  }'
```

<Card title="Nota Importante">
  O mesmo endpoint [api.abacatepay.com](https://api.abacatepay.com) é usado para o ambiente de desenvolvimento e produção. O ambiente é determinado automaticamente pela chave de API utilizada na requisição.
</Card>


# Autenticação & Perfis
Source: https://docs.abacatepay.com/pages/cli/auth

Comandos de login, logout, perfis múltiplos e gerenciamento de autenticação na AbacatePay CLI.

Comandos para gerenciar a autenticação e sessão na AbacatePay CLI.

***

### `abacatepay login`

Realiza a autenticação na AbacatePay. Abre o navegador para login via OAuth ou permite autenticação direta com API key.

```bash theme={null}
abacatepay login [flags]
```

| Flag      | Alias | Descrição                   | Padrão  |
| --------- | ----- | --------------------------- | ------- |
| `--name`  | -     | Nome do perfil a ser criado | `""`    |
| `--key`   | -     | Sua API key da AbacatePay   | `""`    |
| `--local` | `-l`  | Usa servidor de teste       | `false` |

<Tip>
  Use `--name` para criar múltiplos perfis e alternar entre diferentes contas ou ambientes.
</Tip>

**Exemplos:**

```bash theme={null}
# Login interativo via navegador
abacatepay login

# Login com API key específica
abacatepay login --key "abc_prod_xxxxx"

# Login criando um perfil nomeado
abacatepay login --name producao --key "abc_prod_xxxxx"
```

<CodeGroup>
  ```text text theme={null}
  ╭────────────────────────────╮
  │                            │
  │  🥑 Signed in successfully │
  │                            │
  │  Profile: default          │
  │  User: João Silva          │
  │  Email: joao@empresa.com   │
  │                            │
  ╰────────────────────────────╯
  ```

  ```json json theme={null}
  {
    "profile": "default",
    "user": "João Silva",
    "email": "joao@empresa.com",
    "status": "authenticated"
  }
  ```

  ```text table theme={null}
  ┌─────────┬──────────────────┐
  │ Profile │ default          │
  │ User    │ João Silva       │
  │ Email   │ joao@empresa.com │
  │ Status  │ Authenticated    │
  └─────────┴──────────────────┘
  ```
</CodeGroup>

***

### `abacatepay logout`

Encerra a sessão atual e remove as credenciais do perfil ativo.

```bash theme={null}
abacatepay logout
```

<CodeGroup>
  ```text text theme={null}
  ╭─────────────────────────────╮
  │                             │
  │  🥑 Signed out successfully │
  │                             │
  │  Profile: default           │
  │                             │
  ╰─────────────────────────────╯
  ```

  ```json json theme={null}
  {
    "title": "Signed out successfully",
    "profile": "default"
  }
  ```
</CodeGroup>

<Warning>
  Após o logout, você precisará fazer login novamente para usar comandos que requerem autenticação.
</Warning>

***

### `abacatepay whoami`

Exibe informações do usuário autenticado e o perfil ativo.

```bash theme={null}
abacatepay whoami
```

<CodeGroup>
  ```text text theme={null}
  ╭───────────────────────────╮
  │                           │
  │  🥑 User Information      │
  │                           │
  │  Status: Authenticated    │
  │  Profile: salve3          │
  │  User: Mock User          │
  │  Email: mock@example.com  │
  │                           │
  │                           │
  ╰───────────────────────────╯
  ```

  ```json json theme={null}
  {
    "profile": "salve3",
    "user": "Mock User",
    "email": "mock@example.com",
    "status": "authenticated"
  }
  ```

  ```text table theme={null}
  ┌─────────┬──────────────────┐
  │ Profile │ salve3           │
  │ User    │ Mock User        │
  │ Email   │ mock@example.com │
  │ Status  │ Authenticated    │
  └─────────┴──────────────────┘
  ```
</CodeGroup>

***

### `abacatepay status`

Verifica o status da conexão e autenticação com a AbacatePay.

```bash theme={null}
abacatepay status
```

<Tip>
  Use `abacatepay status` como diagnóstico rápido quando encontrar problemas de conectividade.
</Tip>

<CodeGroup>
  ```text text theme={null}
  ╭────────────────────────────╮
  │                            │
  │  🥑 Connected successfully │
  │                            │
  │  Profile: default          │
  │  Status: Online            │
  │                            │
  ╰────────────────────────────╯
  ```

  ```json json theme={null}
  {
    "profile": "default",
    "status": "online"
  }
  ```

  ```text table theme={null}
  ┌─────────┬─────────┐
  │ Profile │ default │
  |─────────|─────────|
  │ Status  │ Online  │
  └─────────┴─────────┘
  ```
</CodeGroup>

***

## Perfis

Comandos para gerenciar múltiplos perfis de autenticação.

***

### `abacatepay profile list`

Lista todos os perfis configurados na máquina.

```bash theme={null}
abacatepay profile list
```

<CodeGroup>
  ```text text theme={null}
  ✓ Configured Profiles

    * default (active)
      producao
      staging
  ```

  ```json json theme={null}
  {
    "profiles": [
      {
        "name": "default",
        "key": "abc_prod..."
      },
      {
        "name": "producao",
        "key": "abc_prod..."
      },
      {
        "name": "staging",
        "key": "abc_dev..."
      }
    ],
    "active": "default"
  }
  ```

  ```text table theme={null}
  ┌───────────┬────────────┬────────┐
  │ Name      │ API Key    │ Active │
  ├───────────┼────────────┼────────┤
  │ default   │ abc_prod...│ 🥑     │
  │ producao  │ abc_prod...│        │
  │ staging   │ abc_dev... │        │
  └───────────┴────────────┴────────┘
  ```
</CodeGroup>

***

### `abacatepay profile delete`

Remove um perfil salvo. Não é possível remover o perfil ativo.

```bash theme={null}
abacatepay profile delete <name>
```

```bash theme={null}
abacatepay profile delete staging
```

```text theme={null}
Profile 'staging' successfully removed.
```

<Warning>
  Não é possível deletar o perfil ativo. Use `abacatepay switch` para mudar para outro perfil antes de deletar.
</Warning>

***

### `abacatepay switch`

Alterna para outro perfil existente.

```bash theme={null}
abacatepay switch <name>
```

<Tip>
  Requer conexão com a internet para verificar o status online.
</Tip>

```bash theme={null}
abacatepay switch producao
```

```text theme={null}
Now using profile: producao
```

***


# Casos de Uso
Source: https://docs.abacatepay.com/pages/cli/cases

Cenários práticos de uso da AbacatePay CLI em desenvolvimento, testes e automação.

Cenários práticos demonstrando o uso da AbacatePay CLI em diferentes situações.

***

### Teste rápido de integração local

Teste sua integração localmente antes de ir para produção.

```bash theme={null}
# 1. Autentique em modo teste
abacatepay -l login

# 2. Inicie o listener
abacatepay -l listen --forward-to http://localhost:3000/webhooks

# 3. Em outro terminal, crie uma cobrança e simule o pagamento
abacatepay -l payments create pix
abacatepay -l payments simulate pix_xxx
```

***

### Debug de webhooks

Diagnostique problemas com webhooks usando verificação local e modo verbose.

```bash theme={null}
# Capture com verbose para ver detalhes
abacatepay -v listen --forward-to http://localhost:3000/webhooks

# Verifique a assinatura manualmente se falhar
abacatepay verify \
  --secret "whsec_seu_secret" \
  --payload '{"id":"evt_123",...}' \
  --signature "t=123456,v1=abc..."
```

***

### Automação em CI/CD

Integre a CLI em pipelines de CI/CD usando output JSON e variáveis de ambiente.

```bash theme={null}
# Output JSON para scripts
PAYMENT_ID=$(abacatepay -o json payments create pix | jq -r '.data.id')

# Simular e verificar
abacatepay payments simulate $PAYMENT_ID
STATUS=$(abacatepay -o json payments check $PAYMENT_ID | jq -r '.data.status')

if [ "$STATUS" = "PAID" ]; then
  echo "Pagamento confirmado!"
fi
```

<Tip>
  Em CI/CD, sempre use `-o json` para output estruturado e parseável. Evite depender de formatação de texto que pode mudar entre versões.
</Tip>

***

### Múltiplas contas/ambientes

Alterne entre contas e ambientes (produção, sandbox, desenvolvimento).

```bash theme={null}
# Criar perfis diferentes
abacatepay login --name producao --key "abc_prod_xxx"
abacatepay login --name sandbox --key "abc_dev_xxx"

# Alternar entre perfis
abacatepay switch producao
abacatepay whoami

abacatepay switch sandbox
abacatepay -l listen
```

<Warning>
  Sempre verifique o perfil ativo antes de executar comandos destrutivos ou criar cobranças reais. Use `abacatepay status` para confirmar.
</Warning>

***


# Configuração
Source: https://docs.abacatepay.com/pages/cli/flags

Flags globais, formatos de output e configuração da AbacatePay CLI.

## Global Flags

Flags disponíveis em todos os comandos:

| Flag        | Alias | Tipo   | Padrão  | Descrição                                 |
| ----------- | ----- | ------ | ------- | ----------------------------------------- |
| `--verbose` | `-v`  | bool   | `false` | Habilita logging detalhado (nível debug)  |
| `--local`   | `-l`  | bool   | `false` | Usa servidor de teste                     |
| `--output`  | `-o`  | string | `text`  | Formato de saída: `text`, `json`, `table` |

```bash theme={null}
# Exemplo combinando flags
abacatepay -v -l -o json payments create pix
```

A CLI suporta três formatos de saída, configuráveis via `--output` ou `-o`.

### text (padrão)

Formato legível para uso interativo no terminal.

```bash theme={null}
abacatepay whoami
```

```text theme={null}
╭───────────────────────────╮
│                           │
│  🥑 User Information      │
│                           │
│  Status: Authenticated    │
│  Profile: salve3          │
│  User: Mock User          │
│  Email: mock@example.com  │
│                           │
│                           │
╰───────────────────────────╯
```

### json

Formato estruturado para scripts, pipelines e CI/CD.

```bash theme={null}
abacatepay -o json whoami
```

```json theme={null}
{
  "profile": "salve3",
  "user": "Mock User",
  "email": "mock@example.com",
  "status": "authenticated"
}
```

Combine com `jq` para filtrar dados:

```bash theme={null}
abacatepay -o json logs list | jq '.logs[] | select(.msg=="webhook_forwarded")'
```

### table

Formato tabular para visualização de listas.

```bash theme={null}
abacatepay -o table profile list
```

```text theme={null}
┌───────────┬────────────┬────────┐
│ Name      │ API Key    │ Active │
├───────────┼────────────┼────────┤
│ default   │ abc_prod...│ 🥑     │
│ staging   │ abc_dev... │        │
└───────────┴────────────┴────────┘
```

***

A CLI suporta dois ambientes: **produção** (padrão) e **teste**.

### Produção (padrão)

```bash theme={null}
abacatepay login
```

Conecta automaticamente com `wss://ws.abacatepay.com/ws`.

### Servidor de Teste

```bash theme={null}
abacatepay login -l
```

Conecta com o servidor de teste em `ws://191.252.202.128:8080/ws`.

<Warning>
  O ambiente de teste usa dados fictícios. Nunca use credenciais reais no modo `-l`.
</Warning>

***

O token da sua conta é armazenado no keyring nativo do sistema:

* **macOS**: Keychain
* **Windows**: Credential Manager
* **Linux**: gnome-keyring ou kwallet

<Accordion title="Problema ao salvar token no Linux?">
  Instale o keyring no seu sistema:

  ```bash theme={null}
  # Debian/Ubuntu
  sudo apt install gnome-keyring

  # Fedora
  sudo dnf install gnome-keyring
  ```

  Então tente novamente:

  ```bash theme={null}
  abacatepay login
  ```
</Accordion>

***

Os logs são salvos em `~/.abacatepay/logs/`:

* **abacatepay.log** - Log geral (JSON)
* **transactions.log** - Webhooks recebidos e encaminhados

Rotação automática: 10MB por arquivo, 5 backups, 30 dias de retenção.

```bash theme={null}
# Ver erros
cat ~/.abacatepay/logs/abacatepay.log | jq 'select(.level=="ERROR")'

# Ver webhooks recebidos
cat ~/.abacatepay/logs/transactions.log | jq 'select(.msg=="webhook_received")'

# Tempo médio de encaminhamento
cat ~/.abacatepay/logs/transactions.log | jq 'select(.msg=="webhook_forwarded") | .duration_ms' | jq -s 'add/length'
```

***


# Visão Geral
Source: https://docs.abacatepay.com/pages/cli/overview

Ferramenta oficial de linha de comando da AbacatePay para desenvolvimento, testes e automações.

A **AbacatePay CLI** é a ferramenta oficial de linha de comando para interagir com a plataforma AbacatePay diretamente do terminal.

Projetada para **desenvolvedores**, permite criar cobranças, escutar webhooks, simular pagamentos e automatizar fluxos — tudo sem sair do terminal.

***

## Principais Capacidades

<CardGroup>
  <Card title="Autenticação" icon="key" href="./auth">
    Login via OAuth, múltiplos perfis e gerenciamento de sessões.
  </Card>

  <Card title="Webhooks" icon="webhook" href="./webhooks">
    Escute, encaminhe e depure webhooks em tempo real.
  </Card>

  <Card title="Pagamentos" icon="wallet" href="./payments">
    Crie, consulte e simule cobranças pelo terminal.
  </Card>

  <Card title="Automação" icon="gear" href="./cases">
    Output em JSON, não-interativo e scriptável.
  </Card>

  <Card title="Configuração" icon="sliders" href="./flags">
    Flags globais, formatos de output e ambientes.
  </Card>

  <Card title="Utilitários" icon="wrench" href="./utils">
    Verificação de webhooks, atualização e debugging.
  </Card>
</CardGroup>

***

## Instalação

### Go (recomendado)

```bash theme={null}
go install github.com/AbacatePay/abacatepay-cli@latest
```

### Homebrew (macOS / Linux)

```bash theme={null}
brew install --build-from-source github.com/AbacatePay/abacatepay-cli
```

**Verificar instalação:**

```bash theme={null}
abacatepay --version
```

<Steps>
  <Step title="Autentique-se">
    ```bash theme={null}
    abacatepay login
    ```

    O navegador abrirá para autenticação OAuth. Após autorizar, informe a URL do seu servidor local para receber webhooks.
  </Step>

  <Step title="Inicie o listener">
    ```bash theme={null}
    abacatepay listen --forward-to http://localhost:3000/webhooks/abacatepay
    ```

    Você também pode rodar apenas `abacatepay listen` para configurar o encaminhamento via menu interativo.
  </Step>

  <Step title="Crie uma cobrança de teste">
    Em outro terminal:

    ```bash theme={null}
    abacatepay payments create pix
    ```

    Você também pode rodar apenas `abacatepay payments create` para escolher via menu, ou usar a flag `-i` para preencher os dados manualmente.
  </Step>
</Steps>

***

## Design & Filosofia

A AbacatePay CLI foi projetada para ser:

* **Explícita** — Nada de mágica escondida
* **Scriptável** — Output estruturado e previsível
* **Compatível com CI/CD** — Totalmente não-interativa com flags
* **Rápida** — Inicialização rápida e footprint mínimo

<CardGroup>
  <Card title="Unix-friendly" icon="terminal">
    Output simples, fácil de parsear e integrar.
  </Card>

  <Card title="Sem dependências pesadas" icon="feather">
    Binário único, sem runtime adicional.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="REST Client" icon="repeat" href="../ecosystem/rest">
    Camada HTTP leve e tipada para integrações avançadas.
  </Card>

  <Card title="SDKs Oficiais" icon="boxes-stacked" href="../sdks">
    Bibliotecas oficiais para diferentes linguagens.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Repositório Open Source" icon="github" href="https://github.com/abacatepay/abacatepay-cli">
    Código-fonte, issues e contribuições.
  </Card>

  <Card title="Ecossistema AbacatePay" icon="boxes-stacked" href="../ecosystem">
    Veja o ecossistema completo da AbacatePay.
  </Card>
</CardGroup>

<Card title="Open source de verdade" icon="heart">
  A AbacatePay CLI é mantida pela equipe AbacatePay e pela comunidade.
</Card>


# Pagamentos
Source: https://docs.abacatepay.com/pages/cli/payments

Comandos para criação, consulta e simulação de pagamentos PIX na AbacatePay CLI.

Os comandos de pagamentos permitem criar, verificar e simular cobranças diretamente pela linha de comando.

***

### `abacatepay payments create`

Cria uma nova cobrança de pagamento. Suporta PIX QR Code e Checkout.

Por padrão, cria um pagamento com dados fictícios (mock). Use o modo interativo para especificar os detalhes manualmente.

```bash theme={null}
abacatepay payments create [pix|checkout] [flags]
```

| Flag            | Alias | Descrição                                  | Padrão  |
| --------------- | ----- | ------------------------------------------ | ------- |
| `--interactive` | `-i`  | Ativa o modo interativo para inserir dados | `false` |

<Tip>
  Se você não especificar o método (`pix` ou `checkout`), a CLI exibirá um menu interativo para seleção.
</Tip>

**Exemplos:**

```bash theme={null}
# Criar PIX com dados mock
abacatepay payments create pix

# Criar checkout no modo interativo
abacatepay payments create checkout -i

# Selecionar método interativamente
abacatepay payments create
```

<CodeGroup>
  ```text text theme={null}
  ╭────────────────────────╮
  │                        │
  │ 🥑 PIX Payment Created │
  │                        │
  │  ID:      pix_abc123xyz│
  │  Status:  PENDING      │
  │                        │
  ╰────────────────────────╯
  ```

  ```json json theme={null}
  {
    "data": {
      "id": "pix_abc123xyz",
      "brCode": "00020126580014br.gov.bcb.pix0136...",
      "status": "PENDING"
    }
  }
  ```

  ```text table theme={null}
  ┌────────────────┬──────────┐
  │ ID             │ Status   │
  ├────────────────┼──────────┤
  │ pix_abc123xyz  │ PENDING  │
  └────────────────┴──────────┘
  ```
</CodeGroup>

***

### `abacatepay payments check`

Consulta o status atual de um pagamento PIX pelo ID.

```bash theme={null}
abacatepay payments check <payment-id>
```

```bash theme={null}
abacatepay payments check pix_abc123xyz
```

<CodeGroup>
  ```text text theme={null}
  ╭─────────────────────────╮
  │                         │
  │  🥑 PIX Status Check    │
  │                         │
  │  ID:      pix_abc123xyz │
  │  Status:  PAID          │
  │                         │
  ╰─────────────────────────╯
  ```

  ```json json theme={null}
  {
    "data": {
      "id": "pix_abc123xyz",
      "status": "PAID"
    }
  }
  ```
</CodeGroup>

<Info>
  Status possíveis: `PENDING` (aguardando), `PAID` (pago), `EXPIRED` (expirado).
</Info>

***

### `abacatepay payments simulate`

Simula o pagamento de uma cobrança PIX em ambiente de sandbox.

```bash theme={null}
abacatepay payments simulate <payment-id>
```

```bash theme={null}
abacatepay payments simulate pix_abc123xyz
```

<CodeGroup>
  ```text text theme={null}
  ╭──────────────────────────╮
  │                          │
  │ 🥑 PIX Payment Simulated │
  │                          │
  │  ID:      pix_abc123xyz  │
  │  Status:  PAID           │
  │                          │
  ╰──────────────────────────╯
  ```

  ```json json theme={null}
  {
    "data": {
      "id": "pix_abc123xyz",
      "status": "PAID"
    }
  }
  ```
</CodeGroup>

<Info>
  Após a simulação, o status do pagamento será alterado para `PAID` e os webhooks configurados serão disparados normalmente.
</Info>

<Warning>
  Este comando só funciona em ambiente de sandbox. Em produção, os pagamentos devem ser realizados pelo fluxo real do PIX.
</Warning>

***


# Utilitários
Source: https://docs.abacatepay.com/pages/cli/utils

Comandos auxiliares para verificação de webhooks, atualização e documentação na AbacatePay CLI.

Comandos auxiliares para verificação de webhooks, atualização e documentação.

***

### `abacatepay verify`

Verifica assinaturas de webhooks localmente, útil para debug e validação offline.

```bash theme={null}
abacatepay verify --secret <secret> --payload <json> --signature <header>
```

| Flag          | Tipo   | Obrigatória | Descrição                                    |
| ------------- | ------ | ----------- | -------------------------------------------- |
| `--secret`    | string | Sim         | Webhook signing secret (inicia com `whsec_`) |
| `--payload`   | string | Sim         | Corpo JSON raw do payload                    |
| `--signature` | string | Sim         | Valor do header `X-Abacate-Signature`        |

<Info>
  O formato do header de assinatura segue o padrão: `t=TIMESTAMP,v1=SIGNATURE`
</Info>

```bash theme={null}
abacatepay verify \
  --secret "whsec_abc123xyz789" \
  --payload '{"id":"evt_123","event":"billing.paid"}' \
  --signature "t=1705849200,v1=a1b2c3d4e5f6..."
```

<CodeGroup>
  ```text Sucesso theme={null}
  ╭───────────────────────────╮
  │                           │
  │  🥑 Signature Verified    │
  │                           │
  │  Timestamp: 1705849200    │
  │  Secret:    whsec_...x789 │
  │  Status:    VALID         │
  │                           │
  ╰───────────────────────────╯
  ```

  ```text Erro theme={null}
  ✗ Signature Mismatch
    Expected: a1b2c3d4e5f6...
    Received: 9z8y7x6w5v4u...
  ```
</CodeGroup>

<Warning>
  Se o timestamp da assinatura tiver mais de 5 minutos, um aviso será exibido. Isso pode indicar um replay attack.
</Warning>

***

### `abacatepay update`

Atualiza a CLI para a versão mais recente.

```bash theme={null}
abacatepay update
```

<CodeGroup>
  ```text Atualização Disponível theme={null}
  Update available: v1.5.0
  Downloading and installing...
  Update complete ✨
  ```

  ```text Já Atualizado theme={null}
  You're already on the latest version (v1.4.2)
  ```
</CodeGroup>

<Tip>
  Execute `abacatepay update` periodicamente para garantir as últimas funcionalidades e correções de segurança.
</Tip>

***

### `abacatepay docs`

Abre a documentação oficial da CLI no navegador.

```bash theme={null}
abacatepay docs
```

***


# Webhooks & Eventos
Source: https://docs.abacatepay.com/pages/cli/webhooks

Comandos para escutar, simular e depurar webhooks e eventos na AbacatePay CLI.

Comandos para escutar, simular e depurar webhooks durante o desenvolvimento.

***

### `abacatepay listen`

Escuta webhooks em tempo real e os encaminha para sua aplicação local.

```bash theme={null}
abacatepay listen [flags]
```

| Flag           | Alias | Descrição                                   | Padrão                                      |
| -------------- | ----- | ------------------------------------------- | ------------------------------------------- |
| `--forward-to` | -     | URL para onde os eventos serão encaminhados | `http://localhost:3000/webhooks/abacatepay` |
| `--mock`       | -     | Simula webhooks sem conectar à API          | `false`                                     |

<Info>
  O comando `listen` mantém uma conexão WebSocket ativa com a AbacatePay para receber eventos em tempo real. Todos os eventos recebidos são salvos no log local.

  Se você não especificar `--forward-to`, a CLI perguntará via prompt qual URL usar.
</Info>

**Exemplos:**

```bash theme={null}
# Escutar e encaminhar para o endpoint padrão
abacatepay listen

# Encaminhar para URL personalizada
abacatepay listen --forward-to http://localhost:8080/webhook

# Modo simulação (sem conexão com a API)
abacatepay listen --mock
```

<Tip>
  Use `Ctrl+C` para interromper. Todos os eventos ficam salvos e podem ser consultados com `abacatepay logs list`.
</Tip>

***

### `abacatepay trigger`

Dispara eventos de teste para simular webhooks durante o desenvolvimento.

```bash theme={null}
abacatepay trigger <event>
```

**Eventos disponíveis:**

| Evento          | Descrição                              |
| --------------- | -------------------------------------- |
| `billing.paid`  | Simula o pagamento de uma cobrança Pix |
| `payout.done`   | Simula um saque concluído com sucesso  |
| `payout.failed` | Simula uma falha em saque              |

<Warning>
  O evento `billing.paid` cria uma cobrança Pix real na API (em modo teste) e simula seu pagamento. Os eventos `payout.*` geram apenas payloads mock locais.
</Warning>

```bash theme={null}
abacatepay trigger billing.paid
```

<CodeGroup>
  ```text text theme={null}
  ╭────────────────────────────────────────────────────────────────╮
  │                                                                │
  │  🥑 Billing.paid Triggered                                     │
  │                                                                │
  │  Charge ID: pix_abc123xyz                                      │
  │  Status:    Simulated                                          │
  │  Note:      Check your 'listen' terminal for the webhook event │
  │                                                                │
  ╰────────────────────────────────────────────────────────────────╯
  ```

  ```json json theme={null}
  {
    "event": "billing.paid",
    "chargeId": "pix_abc123xyz"
  }
  ```
</CodeGroup>

<Tip>
  Execute `abacatepay listen` em outro terminal antes de usar `trigger` para receber os webhooks.
</Tip>

***

### `abacatepay events sample`

Gera um payload JSON de exemplo para um tipo de evento específico.

```bash theme={null}
abacatepay events sample <event>
```

**Eventos:** `billing.paid`, `payout.done`, `payout.failed`

```bash theme={null}
# Gerar sample de billing.paid
abacatepay events sample billing.paid

# Salvar em arquivo
abacatepay events sample billing.paid > payload.json
```

<CodeGroup>
  ```json billing.paid theme={null}
  {
    "id": "evt_abc123",
    "event": "billing.paid",
    "devMode": true,
    "data": {
      "payment": {
        "amount": 1000,
        "fee": 0,
        "method": "PIX"
      },
      "billing": {
        "id": "bill_xyz789",
        "externalId": "uuid-v4-example",
        "url": "https://abacatepay.com/pay/...",
        "amount": 1000,
        "status": "PAID"
      }
    }
  }
  ```

  ```json payout.done theme={null}
  {
    "id": "evt_def456",
    "event": "payout.done",
    "devMode": true,
    "data": {
      "transaction": {
        "id": "txn_abc123",
        "status": "COMPLETE",
        "devMode": true,
        "receiptUrl": "https://abacatepay.com/receipt/...",
        "kind": "WITHDRAW",
        "amount": 5000,
        "platformFee": 0,
        "externalId": "uuid-v4-example",
        "createdAt": "2026-01-21T10:30:00Z",
        "updatedAt": "2026-01-21T10:30:00Z"
      }
    }
  }
  ```

  ```json payout.failed theme={null}
  {
    "id": "evt_ghi789",
    "event": "payout.failed",
    "devMode": true,
    "data": {
      "transaction": {
        "id": "txn_xyz456",
        "status": "CANCELLED",
        "kind": "WITHDRAW",
        "amount": 3000,
        "platformFee": 0,
      }
    }
  }
  ```
</CodeGroup>

<Info>
  Use este comando para entender a estrutura dos payloads e configurar corretamente o parsing na sua aplicação.
</Info>

***

### `abacatepay events resend`

Reenvia um evento passado para seu endpoint de webhook local.

```bash theme={null}
abacatepay events resend <event-id> [flags]
```

| Flag           | Alias | Descrição                             | Padrão                                                      |
| -------------- | ----- | ------------------------------------- | ----------------------------------------------------------- |
| `--forward-to` | -     | URL para onde o evento será reenviado | URL original ou `http://localhost:3000/webhooks/abacatepay` |

<Info>
  O evento é buscado no arquivo de log local. O ID pode ser obtido através de `abacatepay logs list`.
</Info>

```bash theme={null}
abacatepay events resend evt_abc123xyz
```

<CodeGroup>
  ```text text theme={null}
  Webhook signing secret: whsec_abacate_local_dev_secret
  Resending event evt_abc123xyz to http://localhost:3000/webhooks/abacatepay...

  → [200 OK] billing.paid

  ╭───────────────────────────────╮
  │                               │
  │  🥑 Event resent successfully │
  │                               │
  │  ID:       evt_abc123xyz      │
  │  Status:   200 OK             │
  │  Duration: 45ms               │
  │                               │
  ╰───────────────────────────────╯
  ```

  ```json json theme={null}
  {
    "id": "evt_abc123xyz",
    "status": 200,
    "statusText": "OK",
    "duration": "45ms"
  }
  ```
</CodeGroup>

<Tip>
  O header `X-Abacate-Signature` é gerado automaticamente com assinatura válida para ambiente de desenvolvimento.
</Tip>

***

### `abacatepay logs list`

Lista o histórico de eventos de webhook gravados localmente.

```bash theme={null}
abacatepay logs list [flags]
```

| Flag      | Alias | Descrição                   | Padrão |
| --------- | ----- | --------------------------- | ------ |
| `--limit` | `-n`  | Número de entradas a exibir | `50`   |
| `--type`  | `-t`  | Filtrar por tipo de log     | -      |

**Tipos de log disponíveis:**

| Tipo                     | Descrição                       |
| ------------------------ | ------------------------------- |
| `webhook_received`       | Webhook recebido da API         |
| `webhook_forwarded`      | Webhook encaminhado com sucesso |
| `webhook_forward_failed` | Falha ao encaminhar (erro HTTP) |
| `webhook_forward_error`  | Erro de conexão ao encaminhar   |

```bash theme={null}
# Listar últimos 50 logs
abacatepay logs list

# Listar últimos 10 logs
abacatepay logs list -n 10

# Filtrar apenas webhooks recebidos
abacatepay logs list -t webhook_received
```

<CodeGroup>
  ```text table theme={null}
  ┌─────────────────────────┬─────────────────────────┬───────────────┬────────────────────────────────────┐
  │ Timestamp               │ Type                    │ ID            │ URL                                │
  ├─────────────────────────┼─────────────────────────┼───────────────┼────────────────────────────────────┤
  │ 2026-01-21T10:30:00Z    │ webhook_forwarded [200] │ evt_abc123    │ http://localhost:3000/webhooks/abacatepay │
  │ 2026-01-21T10:29:55Z    │ webhook_received        │ evt_abc123    │ http://localhost:3000/webhooks/abacatepay │
  └─────────────────────────┴─────────────────────────┴───────────────┴────────────────────────────────────┘
  ```

  ```json json theme={null}
  {
    "logs": [
      {
        "timestamp": "2026-01-21T10:30:00Z",
        "msg": "webhook_forwarded",
        "id": "evt_abc123",
        "url": "http://localhost:3000/webhooks/abacatepay",
        "statusCode": 200,
        "size_bytes": 1024,
        "raw_message": "{\"id\":\"evt_abc123\",\"event\":\"billing.paid\",...}",
        "event": "billing.paid",
        "level": "INFO"
      }
    ],
    "count": 1
  }
  ```
</CodeGroup>

***

### `abacatepay logs tail`

Exibe eventos de webhook em tempo real via streaming.

```bash theme={null}
abacatepay logs tail
```

<Info>
  Este comando conecta ao WebSocket e exibe os eventos conforme chegam, sem encaminhá-los para nenhum endpoint.
</Info>

```text theme={null}
Streaming webhook events...

Press Ctrl+C to stop

[2026-01-21T10:30:00Z] billing.paid - evt_abc123xyz
  Amount: R$ 10,00
  Status: paid

^C
Listener stopped
```

<Tip>
  Use `logs tail` para monitorar eventos sem processá-los. Para receber e encaminhar webhooks, use `abacatepay listen`.
</Tip>

***


# Criar um Cliente
Source: https://docs.abacatepay.com/pages/client/create

POST /customers/create
Permite que você crie um cliente para a sua loja.

**Campo obrigatório**: Apenas o `email` é obrigatório para criar um cliente.

**Recomendado**: Embora os demais campos sejam opcionais, é altamente recomendado fornecer `name`, `cellphone`, `taxId` e `zipCode` quando disponíveis, pois essas informações melhoram a experiência do cliente no checkout e facilitam a identificação.


Cadastra um cliente para pré-preencher o checkout e reutilizar em várias cobranças.

<Card title="Obrigatório">
  Só `data.email` é obrigatório. Inclua `name`, `taxId` e `cellphone` sempre que tiver — melhora a experiência no checkout.
</Card>

**Exemplo:**

```json theme={null}
{
  "email": "joao@exemplo.com",
  "name": "João Silva",
  "taxId": "12345678900",
  "cellphone": "+5511999999999",
  "zipCode": "01310-100",
  "metadata": { "plano": "premium" }
}
```

<Tip title="Reuse o customerId">
  Guarde o `data.id` retornado e passe como `customerId` ao criar checkouts — o cliente não precisa preencher os dados novamente.
</Tip>

<Note>
  Cliente é único por CPF/CNPJ. Se já existir um cadastro com o mesmo `taxId`, a API devolve o registro existente em vez de criar um duplicado.
</Note>


# Deletar um Cliente
Source: https://docs.abacatepay.com/pages/client/delete

POST /customers/delete
Remove um cliente da sua loja.

Esta operação é irreversível. Use com cuidado.


Remove um cliente da sua loja pelo `id`.

<Card>
  Requer a permissão `CUSTOMER:DELETE`.
</Card>

<Warning>
  Deletar um cliente não cancela cobranças ou assinaturas vinculadas a ele.
</Warning>


# Buscar um Cliente
Source: https://docs.abacatepay.com/pages/client/get

GET /customers/get
Retorna os dados de um cliente específico baseado em filtros.

Você pode usar essa rota para buscar um cliente por ID ou outros critérios.


Retorna os dados de um cliente pelo seu `id`.

<Card>
  Requer a permissão `CUSTOMER:READ`.
</Card>

Use para recuperar o `id` de um cliente antes de criar uma cobrança ou para verificar os dados cadastrados.


# Listar Clientes
Source: https://docs.abacatepay.com/pages/client/list

GET /customers/list
Retorna todos os clientes que você cadastrou com suporte a paginação.

Você pode usar essa rota para visualizar todos os seus clientes e suas informações.

**Alternativa**: Você também pode visualizar e gerenciar seus clientes pelo [Dashboard da AbacatePay](https://app.abacatepay.com/clientes).


Retorna todos os clientes cadastrados na sua loja.

<Card>
  Requer a permissão `CUSTOMER:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Cliente](/pages/client/create), incluindo `id`, `email`, `name` e `taxId`.


# Referência
Source: https://docs.abacatepay.com/pages/client/reference

Clientes para pré-preencher checkout e reutilizar em várias cobranças

Use `/customers/create` para cadastrar um cliente antes de cobrar. O `customerId` retornado pode ser usado em várias cobranças e pré-preenche o checkout.

<Card title="Campos obrigatórios">
  Só `email` é obrigatório. Recomendado: `name`, `cellphone` e `taxId` quando tiver.
</Card>

**Exemplo:**

```json theme={null}
POST /customers/create
{
  "data": {
    "email": "customer@example.com",        // obrigatório
    "taxId": "12345678900",                 // opcional
    "name": "João Silva",                   // opcional
    "cellphone": "+5511999999999",          // opcional
    "zipCode": "01310-100"                  // opcional
  },
  "metadata": {                             // opcional - dados extras da sua aplicação
    "customField": "value"
  }
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "cust_abc123xyz",
    "devMode": false,
    "email": "customer@example.com",
    "taxId": "12345678900",
    "country": "BR",
    "name": "João Silva",
    "cellphone": "+5511999999999",
    "zipCode": "01310-100",
    "metadata": {
      "customField": "value"
    }
  },
  "success": true,
  "error": null
}
```

<Tip title="CPF/CNPJ único" icon="book">
  Cliente é único por CPF/CNPJ. Se já existir, a API devolve o existente em vez de criar outro. CPF/CNPJ inválido não é aceito.
</Tip>


# O que é o Checkout?
Source: https://docs.abacatepay.com/pages/concepts/checkout

Entenda como funciona a cobrança por link e tela de pagamento da AbacatePay

## A ideia simples

Um **checkout** é a tela onde seu cliente finaliza o pagamento. É aquela página que aparece quando você clica em "Comprar" em uma loja online — com o resumo do pedido e as opções de pagamento.

Na AbacatePay, você não precisa construir essa tela. A gente gera ela automaticamente. Você só precisa dizer **o que está sendo vendido** e **qual o valor**.

***

## Como funciona na prática

<Steps>
  <Step title="Você cria uma cobrança">
    Pode ser pelo dashboard ou pela API. Você informa o produto e o valor.
  </Step>

  <Step title="A AbacatePay gera um link">
    Um link único e seguro é criado. Ex: `https://app.abacatepay.com/pay/bill_abc123`
  </Step>

  <Step title="Você envia o link para o cliente">
    Por WhatsApp, e-mail, Instagram — qualquer canal.
  </Step>

  <Step title="O cliente paga">
    Ele escolhe PIX ou cartão e conclui o pagamento na tela da AbacatePay.
  </Step>

  <Step title="Você é notificado">
    Recebe uma notificação imediata de que o pagamento foi confirmado.
  </Step>
</Steps>

***

## Dois tipos de checkout

<CardGroup>
  <Card icon="arrow-up-right-from-square" title="Checkout Hospedado">
    A tela de pagamento fica **no site da AbacatePay**. Você redireciona o cliente para lá e pronto. É o jeito mais rápido — zero configuração de interface.

    **Ideal para:** quem quer começar rápido sem precisar de designer ou desenvolvedor.
  </Card>

  <Card icon="code" title="Checkout Transparente">
    A tela de pagamento fica **dentro do seu site**. A AbacatePay processa nos bastidores, mas o cliente nunca sai da sua página.

    **Ideal para:** quem quer uma experiência de compra mais profissional e integrada ao próprio site. Requer desenvolvimento.
  </Card>
</CardGroup>

<Tip>
  Se você está começando agora, use o **Checkout Hospedado**. É mais rápido e já funciona sem precisar de um desenvolvedor.
</Tip>

***

## Formas de pagamento aceitas

| Forma de pagamento     | Disponível?      |
| ---------------------- | ---------------- |
| PIX                    | ✅ Sim            |
| Cartão de crédito      | ✅ Sim            |
| Boleto                 | ✅ Sim            |
| Parcelamento (até 12x) | ✅ Sim, no cartão |

***

## Perguntas comuns

<AccordionGroup>
  <Accordion title="O link de pagamento tem prazo de validade?">
    Por padrão, o link não expira. Você pode configurar uma data de expiração ao criar a cobrança.
  </Accordion>

  <Accordion title="Meu cliente pode pagar mais de uma vez pelo mesmo link?">
    Depende. Um link de pagamento comum (`ONE_TIME`) aceita apenas um pagamento. Se você quiser um link reutilizável, use um **Link de Pagamento** com `MULTIPLE_PAYMENTS` — ideal para doações ou pedidos avulsos.
  </Accordion>

  <Accordion title="Consigo personalizar a tela de pagamento com minha marca?">
    Sim. Você pode configurar o nome, logo e cores da sua loja no dashboard, e eles aparecem automaticamente na tela de checkout.
  </Accordion>

  <Accordion title="O que acontece se o cliente não pagar?">
    A cobrança fica com status `PENDING`. Você pode reenviar o link para o cliente a qualquer momento.
  </Accordion>
</AccordionGroup>

***

<Card icon="rocket" title="Pronto para receber seu primeiro pagamento?" href="/pages/guides/primeiro-pagamento">
  Siga o guia passo a passo e receba um pagamento real em minutos.
</Card>


# O que é a AbacatePay?
Source: https://docs.abacatepay.com/pages/concepts/overview

Entenda o que a AbacatePay faz pelo seu negócio — sem precisar ser desenvolvedor

<Tip>
  Esta seção é para quem quer **entender o produto** antes de integrar. Se você já é desenvolvedor e quer ir direto ao código, vá para [Guias → Autenticação](/pages/authentication).
</Tip>

## Em uma frase

A AbacatePay é uma plataforma que permite ao seu negócio **cobrar clientes pela internet** — via PIX, cartão de crédito ou boleto — e **receber esse dinheiro na sua conta**.

***

## O problema que a AbacatePay resolve

Imagine que você tem uma loja online, um serviço de assinatura ou vende infoprodutos. Para cobrar seus clientes, você precisaria:

* Contratar um banco ou adquirente (processo longo e burocrático)
* Lidar com dezenas de regras técnicas de cada meio de pagamento
* Construir toda a tela de pagamento do zero
* Gerenciar estornos, inadimplência, notificações...

A AbacatePay cuida de tudo isso por você. Você foca no seu produto; a gente cuida do dinheiro.

***

## O que você pode fazer com a AbacatePay

<CardGroup>
  <Card icon="link" title="Cobrar com um link">
    Crie um link de pagamento em segundos e compartilhe com seu cliente — pelo WhatsApp, e-mail ou Instagram. Funciona como um carrinho de compras, sem precisar de site.
  </Card>

  <Card icon="qrcode" title="Cobrar via PIX">
    Gere um QR Code PIX na hora. O cliente escaneia e o dinheiro cai em segundos, qualquer dia, qualquer hora.
  </Card>

  <Card icon="credit-card" title="Cobrar no cartão">
    Aceite cartão de crédito com parcelamento em até 12x. Tudo em uma tela de pagamento pronta, sem precisar construir nada.
  </Card>

  <Card icon="rotate" title="Cobrar todo mês (assinaturas)">
    Configure uma cobrança recorrente e a AbacatePay cobra seu cliente automaticamente todo mês — ideal para cursos, mentorias ou serviços com mensalidade.
  </Card>

  <Card icon="money-bill-transfer" title="Sacar seu dinheiro">
    Quando quiser, transfira o saldo acumulado para sua conta bancária de forma simples e rápida.
  </Card>

  <Card icon="tag" title="Criar cupons de desconto">
    Crie promoções com desconto percentual ou fixo e distribua para seus clientes.
  </Card>
</CardGroup>

***

## Como funciona o fluxo de um pagamento

```
Seu cliente → Tela de pagamento → AbacatePay → Você recebe a confirmação → Saldo disponível
```

1. Você cria uma cobrança (via dashboard ou API)
2. A AbacatePay gera uma tela de pagamento segura
3. Seu cliente paga (PIX, cartão ou boleto)
4. Você recebe uma notificação automática
5. O valor entra no seu saldo na AbacatePay
6. Você saca para sua conta quando quiser

***

## Quem usa a AbacatePay?

* **Infoprodutores** que vendem cursos e mentorias
* **SaaS e startups** que cobram assinatura mensal
* **E-commerces** que precisam de checkout rápido
* **Freelancers** que querem um jeito simples de cobrar clientes
* **Lojas físicas** que querem aceitar pagamento online

***

## Próximos passos

<CardGroup>
  <Card icon="rocket" title="Receba seu primeiro pagamento" href="/pages/guides/primeiro-pagamento">
    Um guia passo a passo para você receber um pagamento real sem escrever código.
  </Card>

  <Card icon="book-open-cover" title="Entenda cada produto" href="/pages/concepts/checkout">
    Saiba mais sobre Checkout, PIX, Assinaturas e Saques em linguagem simples.
  </Card>
</CardGroup>


# O que é o PIX?
Source: https://docs.abacatepay.com/pages/concepts/pix

Como usar o PIX para receber pagamentos instantâneos pelo seu negócio

## PIX: o que todo mundo já sabe

O PIX é o sistema de pagamento instantâneo do Banco Central do Brasil. Funciona 24 horas por dia, 7 dias por semana, e o dinheiro cai na conta em segundos.

Você já usa PIX no dia a dia. Na AbacatePay, a gente traz isso para o seu negócio de forma profissional.

***

## Como a AbacatePay usa o PIX

A AbacatePay gera para você um **QR Code** ou um **código copia-e-cola** único para cada cobrança. Seu cliente escaneia ou cola no banco dele e o pagamento é confirmado em segundos.

<CardGroup>
  <Card icon="qrcode" title="QR Code">
    Uma imagem que o cliente escaneia com o aplicativo do banco. Ideal para cobranças em sites, landing pages ou imagens no WhatsApp.
  </Card>

  <Card icon="copy" title="Copia-e-cola">
    Um código de texto que o cliente cola no app do banco. Funciona em qualquer canal de texto — SMS, e-mail, chat.
  </Card>
</CardGroup>

***

## Quando usar PIX vs outras formas de pagamento?

|                        | PIX      | Cartão          | Boleto         |
| ---------------------- | -------- | --------------- | -------------- |
| **Confirmação**        | Segundos | Minutos a horas | 1-3 dias úteis |
| **Disponível**         | 24/7     | 24/7            | Dias úteis     |
| **Parcelamento**       | Não      | Sim (até 12x)   | Não            |
| **Taxa**               | Menor    | Maior           | Média          |
| **Cancelamento fácil** | Sim      | Sim             | Sim            |

**Regra prática:**

* Produto de baixo valor ou urgente → PIX
* Produto de alto valor → cartão com parcelamento
* Cliente sem cartão → boleto

***

## O que acontece depois que o cliente paga?

1. O pagamento é confirmado em segundos
2. O valor entra no seu **saldo na AbacatePay**
3. Você recebe uma **notificação automática** (se tiver webhook configurado)
4. Quando quiser, você **saca** o valor para sua conta bancária

***

## Perguntas comuns

<AccordionGroup>
  <Accordion title="O QR Code tem prazo de validade?">
    Sim. Por padrão, o QR Code PIX expira em 30 minutos após a criação. Você pode configurar um prazo diferente ao criar a cobrança.
  </Accordion>

  <Accordion title="Posso cobrar qualquer valor via PIX?">
    Sim, não há valor mínimo ou máximo definido pela AbacatePay. Limitações de valor do Banco Central podem se aplicar dependendo do banco do seu cliente.
  </Accordion>

  <Accordion title="Como sei se o pagamento foi confirmado?">
    Você pode verificar o status da cobrança no dashboard. Se configurou webhooks, receberá uma notificação automática assim que o pagamento for confirmado.
  </Accordion>

  <Accordion title="E se o cliente errar o valor ao transferir?">
    Se o cliente transferir um valor diferente do QR Code, o pagamento pode não ser confirmado automaticamente. Para evitar isso, sempre use o QR Code gerado pela AbacatePay — ele já tem o valor embutido.
  </Accordion>
</AccordionGroup>

***

<Card icon="rocket" title="Quer gerar um PIX agora?" href="/pages/guides/primeiro-pagamento">
  Siga o guia e gere seu primeiro QR Code em minutos.
</Card>


# Como receber seu dinheiro
Source: https://docs.abacatepay.com/pages/concepts/saques

Entenda como funciona o saldo e como transferir o dinheiro para sua conta bancária

## O fluxo do dinheiro

Quando um cliente paga pelo AbacatePay, o dinheiro não vai diretamente para o seu banco. Ele vai primeiro para o seu **saldo na AbacatePay**. Depois, você faz um **saque** para transferir esse saldo para a sua conta.

```
Cliente paga → Saldo na AbacatePay → Você saca → Sua conta bancária
```

***

## Por que funciona assim?

Esse modelo é padrão no mercado de pagamentos. Ele permite que a AbacatePay:

* Processe estornos sem problemas
* Garanta a segurança das transações
* Consolide múltiplos pagamentos antes de transferir

***

## Quando o dinheiro fica disponível?

| Forma de pagamento | Disponibilidade no saldo                          |
| ------------------ | ------------------------------------------------- |
| PIX                | Imediato após confirmação                         |
| Cartão de crédito  | Após o prazo de liquidação (consulte o dashboard) |
| Boleto             | Após a compensação bancária (1-3 dias úteis)      |

***

## Como fazer um saque

<Steps>
  <Step title="Acesse o dashboard">
    Entre em [app.abacatepay.com](https://app.abacatepay.com) com sua conta.
  </Step>

  <Step title="Vá em Saques">
    No menu lateral, clique em **Saques** ou **Financeiro**.
  </Step>

  <Step title="Informe os dados bancários">
    Digite o valor e os dados da conta de destino (banco, agência, conta e CPF/CNPJ do titular).
  </Step>

  <Step title="Confirme o saque">
    Revise os dados e confirme. O valor é transferido normalmente no mesmo dia útil.
  </Step>
</Steps>

***

## Perguntas comuns

<AccordionGroup>
  <Accordion title="Existe um valor mínimo para sacar?">
    Sim. O valor mínimo de saque é definido pela AbacatePay. Consulte o dashboard para ver o limite atual.
  </Accordion>

  <Accordion title="Posso sacar para a conta de outra pessoa?">
    Sim, desde que você forneça os dados bancários corretos do destinatário, incluindo o CPF ou CNPJ do titular da conta.
  </Accordion>

  <Accordion title="Quanto tempo demora para o dinheiro chegar?">
    Saques via PIX são instantâneos. Saques via TED levam até 1 dia útil para cair na conta de destino. Saques solicitados fora do horário comercial ou em fins de semana e feriados são processados no próximo dia útil.
  </Accordion>

  <Accordion title="O que é uma taxa de serviço?">
    A AbacatePay cobra uma taxa sobre cada transação processada. Essa taxa é descontada automaticamente do valor recebido antes de entrar no seu saldo. Consulte a [página de precificação](https://abacatepay.com) para os valores atuais.
  </Accordion>
</AccordionGroup>

***

<Card icon="circle-question" title="Tem mais dúvidas?" href="/pages/faq/index">
  Veja o FAQ com as perguntas mais comuns sobre saques e financeiro.
</Card>


# O que são Assinaturas?
Source: https://docs.abacatepay.com/pages/concepts/subscriptions

Entenda como cobrar seus clientes todo mês de forma automática

## A ideia

Uma assinatura é uma **cobrança automática e recorrente**. Em vez de você precisar cobrar seu cliente toda vez, a AbacatePay faz isso automaticamente no intervalo que você definiu — mensal, semanal ou anual.

Pense em como funciona o Netflix, Spotify ou qualquer academia: o cliente assina uma vez e é cobrado automaticamente todo mês. Você pode fazer exatamente isso para o seu negócio.

***

## Para que serve?

<CardGroup>
  <Card icon="graduation-cap" title="Cursos e mentorias">
    Cobranças mensais para alunos de um curso ou programa de mentoria continuada.
  </Card>

  <Card icon="briefcase" title="SaaS / software">
    Plano mensal ou anual para o seu serviço ou ferramenta online.
  </Card>

  <Card icon="dumbbell" title="Comunidades e grupos">
    Acesso a grupo exclusivo, comunidade ou clube de assinantes.
  </Card>

  <Card icon="box" title="Clube de assinaturas">
    Produto ou serviço entregue periodicamente com cobrança automática.
  </Card>
</CardGroup>

***

## Como funciona o ciclo

<Steps>
  <Step title="Você cria um produto com recorrência">
    No dashboard, você define o produto, o preço e o ciclo (mensal, anual, semanal).
  </Step>

  <Step title="Seu cliente assina">
    Ele paga a primeira cobrança. A assinatura está ativa.
  </Step>

  <Step title="Cobranças automáticas">
    No próximo ciclo (ex: daqui a 30 dias), a AbacatePay tenta cobrar o cliente automaticamente.
  </Step>

  <Step title="Você é notificado">
    A cada pagamento confirmado ou falha, você recebe uma notificação.
  </Step>

  <Step title="Cancelamento fácil">
    Você ou o cliente podem cancelar a assinatura a qualquer momento pelo dashboard ou pela API.
  </Step>
</Steps>

***

## O que acontece se o pagamento falhar?

A AbacatePay tenta cobrar de novo automaticamente. Você pode configurar:

* **Quantas tentativas** fazer (até 10)
* **Quantos dias esperar** entre cada tentativa (1 a 30 dias)

Se todas as tentativas falharem, a assinatura é marcada como `FAILED` e você é notificado.

***

## Ciclos disponíveis

| Ciclo     | Frequência  |
| --------- | ----------- |
| `WEEKLY`  | Toda semana |
| `MONTHLY` | Todo mês    |
| `YEARLY`  | Todo ano    |

***

## Perguntas comuns

<AccordionGroup>
  <Accordion title="Posso oferecer período de teste gratuito?">
    Sim. Defina o campo `trialDays` (de 1 a 90 dias) ao criar o produto. Durante o trial o cliente não é cobrado — a primeira cobrança pelo valor integral acontece automaticamente ao final do período. Veja mais em [Período de teste gratuito](/pages/subscriptions/reference#período-de-teste-gratuito-free-trial).
  </Accordion>

  <Accordion title="O cliente pode mudar de plano?">
    Sim. Você pode alterar o plano de uma assinatura ativa a qualquer momento — o novo valor passa a valer no próximo ciclo.
  </Accordion>

  <Accordion title="Posso aplicar cupom de desconto em assinaturas?">
    Sim. Você pode criar cupons e aplicá-los ao criar ou atualizar uma assinatura.
  </Accordion>

  <Accordion title="Como o cliente cancela a assinatura?">
    Você pode cancelar pelo dashboard ou pela API. Se quiser que o próprio cliente cancele de forma self-service, você precisa criar essa funcionalidade no seu site usando a API da AbacatePay.
  </Accordion>
</AccordionGroup>

***

<Card icon="rocket" title="Quer criar sua primeira assinatura?" href="/pages/guides/primeiro-pagamento">
  Veja o guia completo para começar a receber mensalidades.
</Card>


# Taxas e tarifas
Source: https://docs.abacatepay.com/pages/concepts/taxas

Entenda quanto custa usar a AbacatePay — sem mensalidade, sem surpresas

<Tip>
  A AbacatePay **não cobra mensalidade**. Você paga apenas quando recebe ou movimenta dinheiro — e as taxas já são descontadas automaticamente do valor antes de entrar no seu saldo.
</Tip>

***

## Receber pagamentos

| Forma de pagamento          | Taxa                       |
| --------------------------- | -------------------------- |
| PIX                         | R\$ 0,80 por transação     |
| Cartão de crédito à vista   | 3,50% + R\$ 0,60           |
| Cartão parcelado (2x a 6x)  | 4,00% + R\$ 0,60           |
| Cartão parcelado (7x a 12x) | 4,50% + R\$ 0,60           |
| Boleto bancário             | R\$ 2,50 por boleto gerado |

<Info>
  As taxas de cartão incidem sobre o **valor total da transação**. O valor fixo de R\$ 0,60 é cobrado independentemente do valor.
</Info>

***

## Sacar dinheiro

| Tipo de transferência              | Custo                      |
| ---------------------------------- | -------------------------- |
| PIX (primeiros 20 saques do mês)   | R\$ 0,80 por saque         |
| PIX (a partir do 21º saque no mês) | R\$ 2,50 por saque         |
| TED                                | R\$ 5,00 por transferência |

<Card title="Limite de saques mensais">
  O limite de saques com a taxa promocional de PIX é de 20 saques por mês. A partir do 21º saque no mês, a taxa de R\$ 2,50 passa a ser aplicada. O contador reinicia no início de cada mês calendário.
</Card>

<Card title="Limite diário de saque">
  O limite diário varia conforme a conta. Novas lojas começam com um limite menor que aumenta automaticamente após a verificação de conta. Consulte o dashboard para ver o limite atual da sua loja.
</Card>

***

## Antecipação de recebíveis

Recebíveis de cartão de crédito têm prazo de liquidação. Se você quiser antecipar e receber antes do prazo, é possível mediante taxa:

|                                     | Taxa         |
| ----------------------------------- | ------------ |
| Antecipação de recebíveis de cartão | 1,50% ao mês |

***

## Como as taxas são cobradas

Você **nunca paga separadamente**. O fluxo é sempre:

```
Cliente paga R$ 100,00 via PIX
→ AbacatePay desconta R$ 0,80
→ R$ 99,20 entra no seu saldo
```

O campo `platformFee` nas respostas da API mostra exatamente quanto foi descontado em cada transação, em centavos.

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Pago taxa sobre boletos não pagos?">
    Não. A taxa do boleto (R\$ 2,50) é cobrada apenas quando o boleto é **pago**. Se o cliente não pagar, nenhuma taxa é descontada.
  </Accordion>

  <Accordion title="Como funciona o parcelamento para mim como vendedor?">
    Você recebe cada parcela individualmente conforme a operadora de cartão a liquida. Se o cliente parcelou em 10x, você recebe 10 créditos separados ao longo dos meses — não o valor total de uma vez.
  </Accordion>

  <Accordion title="O contador de saques mensais reinicia todo mês?">
    Sim. O contador reinicia no início de cada mês calendário.
  </Accordion>

  <Accordion title="Existe taxa para criar uma conta ou usar o dashboard?">
    Não. Criar conta, acessar o dashboard, criar produtos, cupons e links de pagamento são gratuitos. Você só paga quando há movimentação financeira.
  </Accordion>

  <Accordion title="Minhas taxas podem ser diferentes dessas?">
    Sim. As taxas acima são as padrão. Dependendo do volume de transações da sua loja, as taxas podem ser negociadas. Entre em contato com o suporte para saber mais.
  </Accordion>
</AccordionGroup>

***

<Card title="Dúvidas sobre as suas taxas?" icon="headset">
  Consulte as taxas da sua conta diretamente no dashboard em **Perfil → Taxas**, ou entre em contato: [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Criar um cupom
Source: https://docs.abacatepay.com/pages/coupons/create

POST /coupons/create
Permite que você crie um novo cupom que pode ser usado por seus clientes para aplicar descontos.

**Alternativa**: Você também pode criar e gerenciar seus cupons pelo [Dashboard da AbacatePay](https://app.abacatepay.com/cupons).


Cria um cupom de desconto que seus clientes aplicam no checkout.

<Card title="Obrigatórios">
  `code` (único na sua loja), `discountKind` (`PERCENTAGE` ou `FIXED`) e `discount` (valor do desconto).
</Card>

**`PERCENTAGE`** desconta uma porcentagem do total. **`FIXED`** desconta um valor fixo em centavos.

**Exemplo — 10% de desconto ilimitado:**

```json theme={null}
{
  "code": "BEMVINDO10",
  "discountKind": "PERCENTAGE",
  "discount": 10,
  "maxRedeems": -1,
  "notes": "Cupom de boas-vindas"
}
```

**Exemplo — R\$ 20,00 fixo, válido 50 vezes:**

```json theme={null}
{
  "code": "PROMO20",
  "discountKind": "FIXED",
  "discount": 2000,
  "maxRedeems": 50
}
```

<Tip title="maxRedeems">
  `-1` significa usos ilimitados. Qualquer valor positivo limita o número total de resgates.
</Tip>


# Deletar um Cupom
Source: https://docs.abacatepay.com/pages/coupons/delete

POST /coupons/delete
Remove um cupom da sua loja.

Esta operação é irreversível. Use com cuidado.


Remove permanentemente um cupom da sua loja pelo `code`.

<Card>
  Requer a permissão `COUPON:DELETE`.
</Card>

<Warning>
  Esta operação é irreversível. Se quiser apenas impedir novos usos sem deletar, use [Alternar Status](/pages/coupons/toggle) para desativar o cupom.
</Warning>


# Buscar um Cupom
Source: https://docs.abacatepay.com/pages/coupons/get

GET /coupons/get
Retorna os dados de um cupom específico baseado em filtros.

Você pode usar essa rota para buscar um cupom por ID ou outros critérios.


Retorna os dados de um cupom pelo seu `code`.

<Card>
  Requer a permissão `COUPON:READ`.
</Card>

Use `redeemsCount` para acompanhar quantas vezes o cupom já foi utilizado e `status` para verificar se ainda está ativo.


# Listar cupons
Source: https://docs.abacatepay.com/pages/coupons/list

GET /coupons/list
Retorna todos os cupons que você criou com suporte a paginação.

Você pode usar essa rota para visualizar todos os seus cupons, incluindo seus status (ativos, inativos ou expirados), descontos aplicados e quantas vezes foram utilizados.

**Alternativa**: Você também pode visualizar e gerenciar seus cupons pelo [Dashboard da AbacatePay](https://app.abacatepay.com/cupons).


Retorna todos os cupons da sua loja, incluindo ativos e inativos.

<Card>
  Requer a permissão `COUPON:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Cupom](/pages/coupons/create), incluindo `status`, `redeemsCount` e `maxRedeems`.


# Referência
Source: https://docs.abacatepay.com/pages/coupons/reference

Crie cupons de desconto para seus clientes usarem uma ou várias vezes

Cupons oferecem desconto percentual ou valor fixo aos clientes, com limite de uso e contagem de resgates.

## Criar cupom

Use `/coupons/create`.

<Card title="Campos obrigatórios">
  Obrigatórios: `code` (único), `discount`, `discountKind` (`PERCENTAGE` ou `FIXED`). Opcionais: `maxRedeems`, `notes`, `metadata`.
</Card>

**Exemplo:**

```json theme={null}
POST /coupons/create
{
  "code": "MY_COUPON",                    // obrigatório - identificador único do cupom
  "discountKind": "PERCENTAGE",           // obrigatório - tipo de desconto (PERCENTAGE ou FIXED)
  "discount": 10,                         // obrigatório - valor do desconto
  "maxRedeems": -1,                       // -1 = ilimitado; qualquer número positivo limita os usos
  "notes": "Cupom de desconto especial",  
  "metadata": {                           
    "campaign": "black-friday"
  }
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "MY_COUPON",
    "discountKind": "PERCENTAGE",
    "discount": 10,
    "maxRedeems": -1,
    "redeemsCount": 0,
    "status": "ACTIVE",
    "devMode": true,
    "notes": "Cupom de desconto especial",
    "createdAt": "2025-01-23T14:06:16.880Z",
    "updatedAt": "2025-01-23T14:06:16.880Z"
  },
  "success": true,
  "error": null
}
```


# Alternar Status de um Cupom
Source: https://docs.abacatepay.com/pages/coupons/toggle

POST /coupons/toggle
Alterna o status de um cupom entre ativo e inativo.

Use essa rota para ativar ou desativar um cupom sem precisar deletá-lo.


Ativa ou desativa um cupom. Cupons inativos não podem ser aplicados em checkouts.

<Card>
  Requer a permissão `COUPON:UPDATE`.
</Card>

Chame este endpoint sempre que quiser pausar uma promoção temporariamente ou reativá-la sem precisar recriar o cupom.


# Dev mode, o que é?
Source: https://docs.abacatepay.com/pages/devmode

Entenda o Dev mode e aprenda a usar este ambiente para testar sua integração com segurança.

O **Dev mode** é o ambiente de testes da AbacatePay.\
Ele permite que você experimente toda a plataforma sem risco, simulando pagamentos, cobranças e webhooks antes de ir para produção.

## O que é o Dev mode?

Ao criar sua conta, você já começa no Dev mode.\
Nesse ambiente:

* Os pagamentos são **simulados**
* Nada é cobrado de verdade
* Você pode testar quantas vezes quiser
* Seus testes não afetam os dados de produção

É o lugar ideal para montar e validar toda sua integração.

<Card title="Por que usar o Dev mode?">
  * Teste sua integração com segurança
  * Simule diferentes tipos de pagamento
  * Configure webhooks sem risco
  * Valide o comportamento da sua aplicação
</Card>

## Como usar o Dev mode

Para começar:

1. <a href="/pages/authentication">Crie sua chave de API de desenvolvimento</a>
2. Use essa chave em todas as requisições de teste
3. Configure webhooks para receber notificações simuladas
4. Teste o fluxo completo: criar cliente, gerar cobrança, pagar, receber webhook, etc.

<Card title="Boas práticas ao testar">
  * Cubra todos os cenários (sucesso, erro e exceções)
  * Valide mensagens de erro e retornos da API
  * Confira se seus webhooks estão recebendo os eventos corretos
  * Revise o comportamento da sua aplicação em cada etapa
</Card>

## <Icon icon="credit-card" type="solid" />  Testando pagamentos com cartão

No Dev mode, você pode simular pagamentos no cartão de crédito. As regras de cartões de teste são:

### Cartão aceito

Use o seguinte cartão para simular um pagamento **aprovado**:

| Campo        | Valor                                                 |
| ------------ | ----------------------------------------------------- |
| **Número**   | `4242 4242 4242 4242`                                 |
| **Validade** | Qualquer data futura (ex.: 12/30)                     |
| **CVV**      | Qualquer número com 3 ou 4 dígitos (ex.: 123 ou 1234) |

### Cartões rejeitados

Os números abaixo são sempre **rejeitados** no Dev mode, para você testar o fluxo de falha:

* `4000000000000002`
* `4000000000009995`
* `4000000000000127`
* `4000000000000069`
* `4000000000000101`

## Checklist antes de ir para produção

Use esta lista para saber que sua integração está pronta. O progresso é salvo no seu navegador.

<div>
  <div>
    <span>Progresso</span>
    <span>0 / 9 concluídos</span>
  </div>

  <div>
    <div />
  </div>
</div>

<script />

Quando todos os itens estiverem marcados, você está pronto para [ir para produção](/pages/production).

## <Icon icon="arrow-right" type="solid" />  Próximos Passos

Quando sua integração estiver funcionando:

1. Desative o Dev mode
2. Finalize a verificação da conta
3. Aguarde a aprovação para produção
4. Comece a processar pagamentos reais

<Card title="Precisa de ajuda?">
  Estamos à disposição. Fale com a gente:  <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Perguntas Frequentes
Source: https://docs.abacatepay.com/pages/faq/index

Respostas para as dúvidas mais comuns sobre a AbacatePay — para lojistas e desenvolvedores.

### Para lojistas (sem código)

<AccordionGroup>
  <Accordion title="Preciso saber programar para usar a AbacatePay?">
    Não. Você pode criar cobranças, gerar links de pagamento e gerenciar tudo pelo dashboard sem escrever uma linha de código. A API e os SDKs são para quem quer automatizar o processo dentro de um sistema.

    Veja o guia [Receba seu primeiro pagamento](/pages/guides/primeiro-pagamento) para começar sem código.
  </Accordion>

  <Accordion title="Como recebo meu dinheiro?">
    O dinheiro dos pagamentos fica no seu saldo na AbacatePay. Você faz um saque a qualquer momento pelo dashboard para transferir para sua conta bancária. PIX cai em segundos, cartão tem um prazo de liquidação. Veja mais em [Como receber seu dinheiro](/pages/concepts/saques).
  </Accordion>

  <Accordion title="Posso cobrar pelo WhatsApp ou Instagram?">
    Sim. Você cria um link de pagamento no dashboard e compartilha esse link em qualquer canal — WhatsApp, Instagram, e-mail, SMS. O cliente clica, escolhe a forma de pagamento e pronto.
  </Accordion>

  <Accordion title="Quais formas de pagamento estão disponíveis?">
    PIX, cartão de crédito (com parcelamento em até 12x) e boleto bancário. Você pode habilitar ou desabilitar cada forma ao criar uma cobrança.
  </Accordion>

  <Accordion title="Como faço para cobrar todo mês (mensalidade)?">
    Crie um produto com recorrência no dashboard. Seu cliente paga uma vez e é cobrado automaticamente a cada ciclo (mensal, semanal ou anual). Veja [O que são Assinaturas](/pages/concepts/subscriptions).
  </Accordion>

  <Accordion title="Minha conta precisa ser verificada para receber pagamentos reais?">
    Sim. Você pode testar tudo no Dev Mode (ambiente de testes) sem verificação. Mas para processar pagamentos reais e sacar dinheiro, sua conta precisa estar verificada. O processo de verificação é feito no próprio dashboard.
  </Accordion>
</AccordionGroup>

***

### Autenticação e chaves

<AccordionGroup>
  <Accordion title="Como obtenho minha chave de API?">
    Acesse o [dashboard da AbacatePay](https://app.abacatepay.com), vá em **Integrar → API Keys** e clique em **Criar Chave**. Consulte o [guia de autenticação](/pages/authentication) para o passo a passo completo.
  </Accordion>

  <Accordion title="Posso usar a mesma chave em dev e produção?">
    Não. Chaves de Dev mode só funcionam no ambiente de desenvolvimento — elas nunca processam transações reais. Para produção, crie uma chave separada após verificar sua conta.
  </Accordion>

  <Accordion title="Recebi erro 401. O que fazer?">
    Verifique se:

    * O header `Authorization: Bearer SUA_CHAVE` está presente na requisição
    * A chave não foi revogada no dashboard
    * Você está usando a chave do ambiente correto (dev ou produção)
  </Accordion>

  <Accordion title="Recebi erro 403. O que fazer?">
    A chave existe e é válida, mas não tem permissão para o recurso solicitado. Acesse o dashboard, edite a chave e adicione a permissão necessária (ex: `CHECKOUT:CREATE`). Consulte a [tabela de permissões](/pages/authentication).
  </Accordion>
</AccordionGroup>

### Dev mode e testes

<AccordionGroup>
  <Accordion title="Qual a diferença entre Dev mode e Produção?">
    No Dev mode, todos os pagamentos são simulados — nenhum valor real é movimentado. O ambiente é determinado automaticamente pela chave usada: chaves de Dev geram transações fictícias, chaves de Produção processam transações reais.
  </Accordion>

  <Accordion title="Como simulo um pagamento aprovado no Dev mode?">
    Para PIX, use o endpoint `/transparents/simulate-payment` após criar a cobrança. Para cartão, use o número `4242 4242 4242 4242` com qualquer data futura e CVV de 3 dígitos. Consulte o [guia de Dev mode](/pages/devmode).
  </Accordion>

  <Accordion title="Meus webhooks do Dev mode recebem eventos reais?">
    Não. Webhooks criados em Dev mode recebem apenas eventos simulados. Para eventos reais, use uma chave de produção e crie o webhook no ambiente de produção.
  </Accordion>
</AccordionGroup>

### Webhooks

<AccordionGroup>
  <Accordion title="Meu webhook não está recebendo eventos. O que verificar?">
    1. Confirme que a URL está acessível publicamente via HTTPS
    2. Verifique se o endpoint responde `200 OK` — qualquer outro código faz a AbacatePay considerar a entrega como falha
    3. Confira se o webhook foi criado no ambiente correto (dev ou produção)
    4. Veja os logs do webhook no dashboard para checar tentativas anteriores
  </Accordion>

  <Accordion title="A AbacatePay tenta reenviar eventos se meu endpoint estiver fora do ar?">
    Sim. Em caso de falha (timeout ou resposta não-2xx), a AbacatePay realiza novas tentativas com backoff progressivo. Implemente idempotência usando o campo `id` do evento para evitar processamento duplicado.
  </Accordion>

  <Accordion title="Como validar que um webhook veio da AbacatePay?">
    Cada requisição inclui o header `X-Webhook-Signature` com uma assinatura HMAC-SHA256. Consulte a [página de segurança de webhooks](/pages/webhooks/security) para exemplos em Node.js, Python e Go.
  </Accordion>
</AccordionGroup>

### Pagamentos e cobranças

<AccordionGroup>
  <Accordion title="Qual a diferença entre Checkout e Checkout Transparente?">
    O **Checkout** redireciona o cliente para uma página de pagamento hospedada pela AbacatePay. O **Checkout Transparente** permite que você construa a interface de pagamento na sua própria aplicação, enquanto a AbacatePay processa a transação nos bastidores.
  </Accordion>

  <Accordion title="Como funciona o parcelamento?">
    O parcelamento está disponível no Checkout com cartão de crédito. Você define o número máximo de parcelas ao criar o checkout. Consulte a [documentação de parcelamento](/pages/payment/installments) para os detalhes de configuração.
  </Accordion>

  <Accordion title="Quanto tempo leva para um PIX ser confirmado?">
    No Dev mode, a confirmação é imediata após simular o pagamento. Em produção, PIX são confirmados em segundos após o pagamento pelo cliente — você receberá um webhook `transparent.completed` ou `checkout.completed` assim que ocorrer.
  </Accordion>
</AccordionGroup>

### SDKs e integração

<AccordionGroup>
  <Accordion title="Qual SDK devo usar?">
    Use o SDK da linguagem do seu backend. Para Node.js/TypeScript é `@abacatepay/sdk`. Consulte a [página de SDKs](/pages/sdks/sdks) para ver todas as opções disponíveis.
  </Accordion>

  <Accordion title="Posso usar a API diretamente sem SDK?">
    Sim. Todos os endpoints aceitam requisições HTTP padrão com `Content-Type: application/json`. Os SDKs são conveniência, não obrigação.
  </Accordion>

  <Accordion title="Encontrei um bug no SDK. O que faço?">
    Abra uma issue no repositório GitHub do SDK específico. Os links estão na [página de cada SDK](/pages/sdks/sdks). Nossa equipe monitora ativamente os repositórios.
  </Accordion>
</AccordionGroup>

***

<Card title="Não encontrou sua resposta?" icon="headset">
  Entre em contato com nossa equipe: <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Glossário
Source: https://docs.abacatepay.com/pages/glossario

Conceitos e termos técnicos da AbacatePay explicados de forma simples

<Card title="Bem-vindo ao Glossário">
  Encontrou um termo que não conhece? Este glossário explica os principais conceitos e termos técnicos usados na documentação da AbacatePay de forma simples e direta.
</Card>

## Autenticação e Segurança

### Bearer Token

Também chamado de **chave de API**, é o método de autenticação usado para autorizar suas requisições à API da AbacatePay. A chave é enviada no header HTTP `Authorization: Bearer {{API_KEY}}`. Sem uma chave válida, nenhuma requisição será aceita.

### Webhook Secret

Uma string única e secreta que garante que os webhooks recebidos realmente vieram da AbacatePay. É enviado na URL do webhook como parâmetro de query string e deve ser validado no seu servidor para evitar requisições maliciosas.

## Ambientes e Modos

### Dev Mode (Modo de Desenvolvimento)

Ambiente de testes onde todas as transações são **simuladas**. Nada é cobrado de verdade e você pode testar quantas vezes quiser sem riscos. Ideal para desenvolver e validar sua integração antes de ir para produção.

### Sandbox

Outro termo para ambiente de testes/desenvolvimento. Na AbacatePay, o ambiente é determinado pela chave de API utilizada (chave de Dev mode = sandbox, chave de Produção = ambiente real).

### Produção

Ambiente real onde as transações são processadas de verdade e valores reais são movimentados. Requer conta verificada e aprovação da AbacatePay.

## Pagamentos e Cobranças

### Checkout

Página segura fornecida pela AbacatePay onde seus clientes finalizam o pagamento. Existem dois tipos:

* **Checkout Integrado**: Você cria uma cobrança e a AbacatePay gera uma URL onde o cliente completa o pagamento em uma página gerenciada por nós.
* **Checkout Transparente**: Você recebe um QRCode PIX ou código copia-e-cola e gerencia toda a experiência de pagamento na sua própria aplicação.

### Gateway de Pagamento

Plataforma intermediária que processa pagamentos entre o cliente e o vendedor. A AbacatePay é um gateway de pagamento que facilita transações PIX e cartão de crédito.

### Fintech

Empresa que usa tecnologia para oferecer serviços financeiros. A AbacatePay é uma fintech focada em simplificar pagamentos.

### Payout

Transferência de dinheiro da sua conta AbacatePay para outra conta (seja sua ou de terceiros). Também chamado de saque ou transferência externa.

## Estrutura de Dados

### External ID

Identificador único criado por você para relacionar transações da AbacatePay com registros do seu sistema. Útil para buscar pagamentos usando seus próprios códigos de pedido.

**Exemplo:** Se você tem um pedido #12345 no seu sistema, pode usar `externalId: "pedido-12345"` ao criar a cobrança.

### Metadata

Campo opcional que permite armazenar informações adicionais personalizadas junto com os recursos da API (cobranças, clientes, etc.). Aceita qualquer objeto JSON e é útil para integrar com seus próprios sistemas.

**Exemplo:**

```json theme={null}
{
  "metadata": {
    "campaign": "black-friday",
    "source": "website",
    "customField": "qualquer valor"
  }
}
```

## Assinaturas e Recorrência

### Subscription (Assinatura)

Também chamada de **Item** na API, é um plano de cobrança recorrente onde o cliente é cobrado automaticamente em intervalos definidos (mensal, anual, etc.).

### Cycle (Ciclo)

Frequência de cobrança de uma assinatura:

* **WEEKLY**: Semanal
* **MONTHLY**: Mensal
* **YEARLY**: Anual

### Retry Policy (Política de Retentativa)

Configuração que define quantas vezes o sistema deve tentar cobrar uma assinatura quando o pagamento falha:

* **maxRetry**: Número máximo de tentativas (1-10)
* **retryEvery**: Intervalo em dias entre tentativas (1-30)

## Cupons e Descontos

### Discount Kind (Tipo de Desconto)

Forma como o desconto é aplicado:

* **PERCENTAGE**: Desconto percentual (ex: 10% de desconto)
* **FIXED**: Desconto em valor fixo (ex: R\$ 5,00 de desconto)

### Max Redeems

Número máximo de vezes que um cupom pode ser usado. Quando definido como `-1`, o cupom pode ser usado infinitamente.

## Status

### Status da Cobrança

* **PENDING**: Aguardando pagamento
* **PAID**: Pago e confirmado
* **CANCELLED**: Cancelada
* **EXPIRED**: Expirada

### Status da Assinatura

* **PENDING**: Criada e aguardando ativação
* **ACTIVE**: Ativa e processando cobranças recorrentes
* **CANCELLED**: Cancelada
* **EXPIRED**: Expirada
* **FAILED**: Falhou após todas as tentativas de cobrança

## PIX

### QRCode PIX

Código QR gerado pela AbacatePay que o cliente escaneia para realizar um pagamento PIX. Pode ser retornado como imagem Base64 (`brCodeBase64`) ou código copia-e-cola (`brCode`).

### BR Code (Código Copia-e-Cola PIX)

String alfanumérica do padrão PIX que pode ser copiada e colada diretamente no aplicativo do banco do cliente para realizar o pagamento. Retornado no campo `brCode`.

### Base64

Formato de codificação que converte dados binários (como imagens) em texto ASCII. O QRCode PIX é retornado como string Base64 no campo `brCodeBase64` para facilitar o uso em imagens HTML.

## Webhooks

### Webhook

Mecanismo onde a AbacatePay **envia notificações** para o seu servidor sempre que algo importante acontece (como um pagamento confirmado), sem você precisar ficar consultando a API constantemente.

### Evento

Ação que dispara um webhook (ex: `billing.paid`, `billing.cancelled`). Cada evento contém informações sobre o que aconteceu.

## URLs e Endpoints

### Return URL

URL para onde o cliente é redirecionado após clicar em "voltar" no checkout, antes de completar o pagamento.

### Completion URL

URL para onde o cliente é redirecionado **após completar** o pagamento com sucesso.

### Receipt URL

URL gerada automaticamente pela AbacatePay que contém o comprovante de pagamento. Disponível após a confirmação do pagamento.

## Processos

### Homologação

Processo de validação e aprovação necessário para ir de desenvolvimento para produção. Na AbacatePay, envolve verificação da conta e aprovação para processar transações reais.

## Estrutura de Resposta

Todas as respostas da API seguem o padrão:

```json theme={null}
{
  "data": { /* dados da operação */ },
  "error": null,
  "success": true
}
```

* Se `success` for `true`, a operação foi bem-sucedida e os dados estarão em `data`
* Se `success` for `false`, a operação falhou e você deve verificar a mensagem de erro no campo `error`

***

<Card title="Não encontrou o termo que procura?" icon="question-circle">
  Entre em contato com nosso suporte: <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Receba seu primeiro pagamento
Source: https://docs.abacatepay.com/pages/guides/primeiro-pagamento

Um guia passo a passo para você gerar um link de pagamento e receber sem escrever código

<Tip>
  Este guia **não exige nenhum conhecimento técnico**. Você vai usar apenas o dashboard da AbacatePay. Em menos de 10 minutos, você terá um link de pagamento funcionando.
</Tip>

***

## O que você vai precisar

* Uma conta na AbacatePay ([criar conta grátis](https://app.abacatepay.com))
* O produto ou serviço que você quer vender
* 10 minutos

***

## Passo 1 — Crie sua conta

Se você ainda não tem uma conta, acesse [app.abacatepay.com](https://app.abacatepay.com) e clique em **Criar conta**. O processo leva poucos minutos.

<Card title="Conta verificada vs não verificada">
  Você pode testar tudo no **Dev mode** (ambiente de testes) antes de verificar sua conta. Mas para receber dinheiro real, sua conta precisa ser verificada. Acesse o dashboard e siga as instruções de verificação.
</Card>

***

## Passo 2 — Crie um produto

Um produto é o que você está vendendo. Pode ser um curso, um serviço, uma consultoria — qualquer coisa.

1. No menu lateral, clique em **Produtos**
2. Clique em **Novo Produto**
3. Preencha:
   * **Nome**: Ex.: "Mentoria 1h", "Acesso ao Curso", "Pacote Premium"
   * **Preço**: O valor em reais que você quer cobrar
   * **Descrição** (opcional): Uma breve descrição para aparecer na tela de pagamento
4. Clique em **Salvar**

Pronto. Seu produto está criado.

***

## Passo 3 — Gere um link de pagamento

Agora você vai criar o link que vai enviar para seu cliente.

1. No menu lateral, clique em **Links de Pagamento** (ou **Cobranças**)
2. Clique em **Novo Link**
3. Selecione o produto que você criou
4. Configure as opções:
   * **Formas de pagamento**: PIX, Cartão ou Boleto (pode selecionar mais de um)
   * **URL de retorno** (opcional): Para onde o cliente vai depois de pagar
5. Clique em **Gerar Link**

O link ficará no formato: `https://app.abacatepay.com/pay/bill_...`

***

## Passo 4 — Envie para o seu cliente

Copie o link e envie pelo canal de sua preferência:

* **WhatsApp**: Cole o link direto na conversa
* **E-mail**: Adicione ao corpo do e-mail com um botão "Clique aqui para pagar"
* **Instagram**: Coloque no bio ou envie por direct
* **Site**: Coloque um botão que abre o link

Seu cliente vai clicar no link, escolher a forma de pagamento e concluir.

***

## Passo 5 — Acompanhe o pagamento

Você pode acompanhar os pagamentos em tempo real:

1. No dashboard, vá em **Cobranças**
2. Veja o status de cada link: `Pendente`, `Pago`, `Expirado`

Quando o cliente pagar, o status muda para **Pago** automaticamente.

<Card title="Quer ser notificado automaticamente?">
  Configure webhooks para receber uma notificação no seu sistema quando um pagamento for confirmado. É opcional, mas útil se você quiser automatizar ações como "liberar acesso ao produto" ou "enviar e-mail de boas-vindas". Veja [como configurar webhooks](/pages/webhooks).
</Card>

***

## Passo 6 — Saque seu dinheiro

Quando quiser transferir o saldo para sua conta:

1. Vá em **Saques** no menu lateral
2. Informe o valor e os dados bancários
3. Confirme

O dinheiro chega no mesmo dia útil.

***

## Próximos passos

Agora que você recebeu seu primeiro pagamento, pode explorar recursos mais avançados:

<CardGroup>
  <Card icon="rotate" title="Cobranças recorrentes" href="/pages/concepts/subscriptions">
    Configure assinaturas para cobrar clientes todo mês automaticamente.
  </Card>

  <Card icon="tag" title="Cupons de desconto" href="/pages/coupons/reference">
    Crie promoções e aplique descontos nas suas cobranças.
  </Card>

  <Card icon="users" title="Cadastrar clientes" href="/pages/client/reference">
    Mantenha um cadastro de clientes para facilitar cobranças futuras.
  </Card>

  <Card icon="terminal" title="Integrar via API" href="/pages/authentication">
    Automatize tudo via código com a API da AbacatePay.
  </Card>
</CardGroup>


# Criar um link de pagamento
Source: https://docs.abacatepay.com/pages/payment-links/create

POST /payment-links/create
Cria um link de pagamento (checkout com frequency MULTIPLE_PAYMENTS). Vários clientes podem pagar o mesmo link; não suporta customerId.


Cria um link de pagamento que pode ser pago por múltiplos clientes — ideal para vendas em massa, rifas ou formulários de inscrição sem criar um checkout por cliente.

<Card title="Obrigatório">
  Envie `"frequency": "MULTIPLE_PAYMENTS"` junto com `items`. O restante dos parâmetros é idêntico ao [Checkout](/pages/payment/create).
</Card>

**Exemplo:**

```json theme={null}
{
  "frequency": "MULTIPLE_PAYMENTS",
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "externalId": "link-campanha-123",
  "completionUrl": "https://seusite.com/obrigado",
  "methods": ["PIX", "CARD"]
}
```

**Exemplo com multa e juros (apenas BOLETO):**

```json theme={null}
{
  "frequency": "MULTIPLE_PAYMENTS",
  "methods": ["BOLETO"],
  "dueDate": "2026-08-15",
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "interest": { "value": 100 },
  "fine": { "value": 200, "type": "PERCENTAGE" }
}
```

<Tip title="Use a url retornada">
  Compartilhe `data.url` — cada cliente que acessar o link pode pagar de forma independente.
</Tip>

<Tip title="Vencimento do boleto">
  Use `dueDate` (`YYYY-MM-DD`) para definir a data de vencimento. Se omitido, o padrão é 3 dias úteis. Só se aplica a `methods: ["BOLETO"]` — veja a [referência completa](/pages/payment/reference#data-de-vencimento-do-boleto).
</Tip>

<Tip title="Multa e juros no boleto">
  Use `interest` e `fine` para configurar juros por atraso e multa caso o pagamento ocorra depois do vencimento. Os campos só se aplicam a `methods: ["BOLETO"]` e seguem o mesmo formato do checkout — veja a [referência completa](/pages/payment/reference#multa-e-juros-no-boleto).
</Tip>


# Listar links de pagamento
Source: https://docs.abacatepay.com/pages/payment-links/list

GET /payment-links/list
Lista apenas links de pagamento (checkouts com frequency MULTIPLE_PAYMENTS).


Retorna todos os links de pagamento (`frequency: MULTIPLE_PAYMENTS`) da sua loja.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar link de pagamento](/pages/payment-links/create).


# Buscar um link de pagamento
Source: https://docs.abacatepay.com/pages/payment-links/one

GET /payment-links/get
Retorna os dados de um link de pagamento específico (checkout com frequency MULTIPLE_PAYMENTS) usando o ID.


Retorna os dados de um link de pagamento pelo seu `id`.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

O campo `frequency` virá como `MULTIPLE_PAYMENTS`. Use `paidAmount` para acompanhar o total arrecadado via esse link ao longo do tempo.


# Referência
Source: https://docs.abacatepay.com/pages/payment-links/reference

Links de pagamento — checkout com múltiplas parcelas

Um **Link de pagamento** é um [Checkout](/pages/payment/reference) que pode ser pago mais de uma vez.

Isso facilita quando existe a necessidade de vários clientes pagarem o mesmo valor mas sem que você crie novos checkouts.

## Criar link de pagamento

**Exemplo:**

```json theme={null}
POST /checkouts/create
{
  "frequency": "MULTIPLE_PAYMENTS",
  "items": [
    {
      "id": "prod_pro",
      "quantity": 1
    }
  ],
  "externalId": "pedido-123",
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["PIX", "CARD"],
  "metadata": {
    "customField": "value"
  }
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "externalId": "pedido-123",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "paidAmount": null,
    "items": [
      {
        "id": "prod_456",
        "quantity": 2
      }
    ],
    "status": "PENDING",
    "frequency": "MULTIPLE_PAYMENTS",
    "coupons": [],
    "devMode": false,
    "customerId": null,
    "returnUrl": null,
    "completionUrl": null,
    "receiptUrl": null,
    "metadata": {},
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

<Tip title="Redirecione o cliente" icon="book">
  Use a `url` retornada para levar o cliente ao checkout e concluir o pagamento.
</Tip>

## Buscar e listar

Links de pagamento são cobranças como qualquer outra: use **GET /checkouts/get** (por ID) e **GET /checkouts/list** para buscar e listar.


# Reembolsar pagamento de link
Source: https://docs.abacatepay.com/pages/payment-links/refund

POST /payment-links/refund
Reembolsa um pagamento realizado em um link de pagamento. O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados.


Reembolsa integralmente um pagamento realizado em um link de pagamento. O valor reembolsado é igual ao valor original da transação — não há reembolso parcial.

<Card title="Obrigatório">
  Apenas `id` é obrigatório — o ID público do pagamento (não do link). Use o ID da cobrança/transação gerada quando o cliente pagou.
</Card>

O campo `id` aceita:

| Prefixo                                | Recurso                                                         |
| -------------------------------------- | --------------------------------------------------------------- |
| `bill_...`                             | ID público do pagamento (billing gerado quando o cliente pagou) |
| `char_...`, `pix_char_...`, `card_...` | ID público do payment intent (charge)                           |

<Note>
  Reembolsos atuam sobre uma **transação específica**, não sobre o link como um todo. Se o mesmo link recebeu múltiplos pagamentos, cada um precisa ser reembolsado individualmente.
</Note>

**Exemplo mínimo:**

```json theme={null}
{
  "id": "bill_link789xyz"
}
```

**Exemplo com motivo:**

```json theme={null}
{
  "id": "bill_link789xyz",
  "reason": "Cobrança duplicada."
}
```

**Resposta:**

```json theme={null}
{
  "data": { "refundPublicId": "tran_refund789xyz" },
  "success": true,
  "error": null
}
```

<Tip title="Idempotência">
  Chamar o endpoint para o mesmo `id` retorna sempre o mesmo `refundPublicId` — não cria reembolsos duplicados.
</Tip>

***

## Regras de negócio

* **Reembolso total apenas** — o valor é sempre igual ao valor original da transação.
* **Métodos suportados** — `PIX`, `PIX_QRCODE` e `CARD`. Boleto, TED e movimentações internas não são reembolsáveis via API.
* **Estado exigido:**
  * `PIX` / `PIX_QRCODE` — transação precisa estar `COMPLETE`.
  * `CARD` — transação precisa estar `APPROVED` ou `COMPLETE`.
* **Disputas** — transações em disputa (`UNDER_DISPUTE` ou `metadata.underDispute=true`) não podem ser reembolsadas por este endpoint.
* **Saldo** — o valor é debitado do saldo `available` da loja (ou `pending`, em casos específicos de `CARD`). Sem saldo, retorna `INSUFFICIENT_FUNDS`.
* **Modo dev (sandbox)** — em `devMode` o reembolso é confirmado instantaneamente, sem chamar o provider real.
* **Status final após o reembolso:**
  * A transação original vira `REFUNDED`.
  * O billing daquele pagamento vira `REFUNDED`.
  * O payment intent vira `REFUNDED`.
  * É criada uma nova transação `WITHDRAW` representando o reembolso (retornada em `refundPublicId`).

<Note>
  Ao concluir, é disparado o webhook [`checkout.refunded`](/pages/webhooks/events/checkout). Configure seu endpoint em [Webhooks](/pages/webhooks/create) para receber a notificação.
</Note>

***

## Códigos de erro

| Código                       | Significado                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `LOCK_NOT_ACQUIRED`          | Outra operação está em andamento para esta loja — tente novamente em instantes.                                  |
| `TRANSACTION_NOT_FOUND`      | O `id` informado não existe ou não pertence à loja.                                                              |
| `TRANSACTION_NOT_REFUNDABLE` | A transação não está em um estado reembolsável (precisa estar `COMPLETE`, ou `APPROVED`/`COMPLETE` para `CARD`). |
| `TRANSACTION_UNDER_DISPUTE`  | Transação em disputa — não pode ser reembolsada.                                                                 |
| `INVALID_METHOD`             | Apenas `PIX`, `PIX_QRCODE` e `CARD` podem ser reembolsados.                                                      |
| `INSUFFICIENT_FUNDS`         | Saldo da loja menor que o valor da transação.                                                                    |
| `STORE_NOT_FOUND`            | Loja não encontrada.                                                                                             |
| `REFUND_REQUEST_FAILED`      | Falha ao criar a transação no ledger ou ao acionar o provider.                                                   |
| `REFUND_CONFIRMATION_FAILED` | Falha ao confirmar o reembolso após a criação.                                                                   |

**Exemplo de erro:**

```json theme={null}
{
  "data": null,
  "success": false,
  "error": "INSUFFICIENT_FUNDS"
}
```

***

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.abacatepay.com/v2/payment-links/refund \
  -H "Authorization: Bearer $ABACATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "bill_link789xyz",
    "reason": "Cobrança duplicada."
  }'
```


# Criar um Checkout
Source: https://docs.abacatepay.com/pages/payment/create

POST /checkouts/create
Cria um Checkout para o cliente realizar o pagamento.

Gera uma página de pagamento hospedada. Você envia os produtos; a API devolve a `url` para redirecionar o cliente.

<Card title="Obrigatório">
  Só `items` é obrigatório — lista com `id` do produto e `quantity`.
</Card>

**Exemplo mínimo:**

```json theme={null}
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ]
}
```

**Exemplo completo:**

```json theme={null}
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "customerId": "cust_abc123xyz",
  "externalId": "pedido-123",
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["PIX", "CARD"],
  "card": {
    "maxInstallments": 12
  },
  "metadata": { "origem": "app-mobile" }
}
```

**Exemplo com upsell:**

```json theme={null}
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "upSellProductId": "prod_bump456xyz"
}
```

**Exemplo com vencimento customizado (apenas BOLETO):**

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

**Exemplo com multa e juros (apenas BOLETO):**

```json theme={null}
{
  "methods": ["BOLETO"],
  "dueDate": "2026-08-15",
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "interest": { "value": 100 },
  "fine": { "value": 200, "type": "PERCENTAGE" }
}
```

<Tip title="Upsell">
  Use `upSellProductId` para oferecer um produto adicional ao cliente após a conclusão do pagamento. O produto deve ser **avulso** (sem `cycle`) e estar com status `ACTIVE`. Veja a [referência completa de upsell](/pages/payment/reference#upsell).
</Tip>

<Tip title="Vencimento do boleto">
  Use `dueDate` (`YYYY-MM-DD`) para definir a data de vencimento. Se omitido, o padrão é 3 dias úteis. Só se aplica a `methods: ["BOLETO"]`. Veja a [referência completa](/pages/payment/reference#data-de-vencimento-do-boleto).
</Tip>

<Tip title="Multa e juros no boleto">
  Use `interest` e `fine` para configurar juros por atraso e multa caso o cliente pague depois do vencimento. Os campos só se aplicam a `methods: ["BOLETO"]` e são ignorados nos demais métodos. Veja a [referência completa](/pages/payment/reference#multa-e-juros-no-boleto).
</Tip>

<Tip title="Parcelamento no cartão">
  Use `card.maxInstallments` (1–12) para permitir que o cliente parcele no cartão. O valor mínimo por parcela é R\$ 10,00. Veja a [doc completa de parcelamento](/pages/payment/installments).
</Tip>

<Tip title="Use a url retornada">
  Redirecione o cliente para `data.url` — é lá que ele finaliza o pagamento.
</Tip>

<Note>
  Para cobranças recorrentes use [Assinaturas](/pages/subscriptions/create). Para um link que múltiplos clientes podem pagar use [Links de pagamento](/pages/payment-links/create).
</Note>


# Receber parcelado (Cartão)
Source: https://docs.abacatepay.com/pages/payment/installments

Permita que seus clientes paguem em até 12x no cartão de crédito.

Ao criar um checkout, você pode definir o número máximo de parcelas que o cliente pode escolher no cartão de crédito. O cliente seleciona as parcelas na tela de pagamento e o valor total é dividido automaticamente.

<Card title="Não disponível em assinaturas">
  Parcelamento funciona em checkouts `ONE_TIME` e links de pagamento (`MULTIPLE_PAYMENTS`). Apenas assinaturas (`SUBSCRIPTION`) não suportam parcelamento.
</Card>

## Como funciona

Envie o objeto `card` com o campo `maxInstallments` ao criar o checkout. O valor deve ser um inteiro entre **1 e 12**.

```json theme={null}
POST /checkouts/create
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "methods": ["CARD"],
  "card": {
    "maxInstallments": 12
  }
}
```

O checkout gerado exibe um seletor para o cliente escolher de 1x até o máximo definido.

## Regras e restrições

| Regra                  | Detalhe                                                                        |
| ---------------------- | ------------------------------------------------------------------------------ |
| **Mínimo por parcela** | R$ 10,00 — para oferecer 3x o total deve ser ≥ R$ 30,00                        |
| **Máximo de parcelas** | 12x                                                                            |
| **Método obrigatório** | `CARD` deve estar em `methods`                                                 |
| **Frequência**         | `ONE_TIME` e `MULTIPLE_PAYMENTS`; não funciona em assinaturas (`SUBSCRIPTION`) |

<Warning>
  Se o valor total for insuficiente para o número de parcelas configurado, a API retorna erro: `"Total below minimum for Nx (R$10 per installment)"`.
</Warning>

## Exemplo completo

```json theme={null}
POST /checkouts/create
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "customerId": "cust_abc123xyz",
  "externalId": "pedido-456",
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["PIX", "CARD"],
  "card": {
    "maxInstallments": 6
  }
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "frequency": "ONE_TIME",
    "methods": ["PIX", "CARD"],
    "card": {
      "maxInstallments": 6
    },
    "installmentsCount": null,
    "createdAt": "2025-04-17T12:00:00.000Z",
    "updatedAt": "2025-04-17T12:00:00.000Z"
  },
  "success": true,
  "error": null
}
```

<Tip title="Redirecione o cliente">
  Use a `url` retornada para levar o cliente ao checkout. O seletor de parcelas aparece automaticamente na tela de pagamento quando `maxInstallments` for maior que 1.
</Tip>

## Confirmar as parcelas após o pagamento

Após o pagamento, o campo `installmentsCount` no objeto do checkout passa a refletir o número de parcelas escolhido pelo cliente. Para pagamentos à vista ou via outros métodos (PIX, Boleto) o valor é sempre `null`.

Use **GET /checkouts/get** para consultar o checkout após receber o [webhook `checkout.completed`](/pages/webhooks/events/checkout):

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "status": "PAID",
    "methods": ["CARD"],
    "installmentsCount": 6,
    ...
  },
  "success": true,
  "error": null
}
```

## Só aceitar cartão parcelado

Se o seu produto só faz sentido com parcelamento (ex: curso, produto de ticket alto), remova o PIX de `methods` e defina `maxInstallments`:

```json theme={null}
{
  "items": [{ "id": "prod_abc123xyz", "quantity": 1 }],
  "methods": ["CARD"],
  "card": {
    "maxInstallments": 12
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Criar checkout" href="/pages/payment/create">
    Veja todos os campos disponíveis ao criar um checkout.
  </Card>

  <Card title="Webhooks" href="/pages/webhooks">
    Receba notificações quando cada parcela for paga.
  </Card>
</CardGroup>


# Listar Checkouts
Source: https://docs.abacatepay.com/pages/payment/list

GET /checkouts/list
Retorna todos os Checkouts que você criou.

Você pode usar essa rota para listar todos seus Checkouts e visualizar seus status, valores e informações relacionadas.


Retorna todos os checkouts da sua loja em ordem cronológica decrescente.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Use os parâmetros de paginação `limit`, `after` e `before` para navegar pelos resultados, e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item da lista segue o mesmo formato da resposta do [Criar Checkout](/pages/payment/create).

<Tip title="Filtrando por status">
  Combine com `status` para buscar só cobranças pendentes, pagas ou canceladas.
</Tip>


# Buscar um Checkout
Source: https://docs.abacatepay.com/pages/payment/one

GET /checkouts/get
Retorna os dados de um Checkout específico usando o ID.

Você pode usar essa rota para buscar um Checkout por ID e visualizar seus detalhes, status e informações relacionadas.


Retorna os dados completos de um checkout pelo seu `id`.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Use este endpoint para verificar o `status` de uma cobrança após o cliente retornar ao seu site, ou ao receber um [webhook](/pages/webhooks) de pagamento.

**Valores de `status`:**

| Valor       | Significado            |
| ----------- | ---------------------- |
| `PENDING`   | Aguardando pagamento   |
| `PAID`      | Pago com sucesso       |
| `EXPIRED`   | Expirado sem pagamento |
| `CANCELLED` | Cancelado              |
| `REFUNDED`  | Reembolsado            |


# Referência
Source: https://docs.abacatepay.com/pages/payment/reference

Crie um checkout

O **Checkout** é a página segura onde o cliente finaliza o pagamento. Você envia os itens; a API devolve uma URL para redirecionar.

<img alt="Fluxo de cobrança - Checkout AbacatePay" />

## Criar checkout

Use `/checkouts/create`. O total é calculado a partir dos itens.

<Card title="Campos obrigatórios">
  Só `items` é obrigatório (lista com `id` do produto e `quantity`).
</Card>

O parâmetro **`frequency`** define o tipo de cobrança:

| Valor                  | Descrição                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| **ONE\_TIME**          | Pagamento único (padrão). Não é necessário enviar ao criar um checkout.                                       |
| **MULTIPLE\_PAYMENTS** | Link de pagamento onde é possível pagar mais de uma vez. Veja [Links de pagamento](/payment-links/reference). |
| **SUBSCRIPTION**       | Assinatura recorrente. Veja [Assinaturas](/subscriptions/reference).                                          |

**Exemplo (pagamento único — frequency não precisa ser enviado):**

```json theme={null}
POST /checkouts/create
{
  "items": [                                    // obrigatório
    {
      "id": "prod_pro",                         // ID do produto na sua loja
      "quantity": 1                             // quantidade
    }
  ],
  "customerId": "cust_abc123xyz",              // opcional - ID do cliente já cadastrado
  "externalId": "pedido-123",                  // opcional - ID no seu sistema
  "returnUrl": "https://seusite.com/voltar",   // opcional - URL de retorno
  "completionUrl": "https://seusite.com/sucesso", // opcional - URL após pagamento
  "methods": ["PIX", "CARD"],                  // opcional - métodos de pagamento (padrão: PIX e CARD)
  "metadata": {                                 // opcional - dados adicionais
    "customField": "value"
  }
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "externalId": "pedido-123",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "paidAmount": null,
    "items": [
      {
        "id": "prod_456",
        "quantity": 2
      }
    ],
    "status": "PENDING",
    "frequency": "ONE_TIME",
    "coupons": [],
    "devMode": false,
    "customerId": null,
    "returnUrl": null,
    "completionUrl": null,
    "receiptUrl": null,
    "metadata": {},
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

<Tip title="Redirecione o cliente" icon="book">
  Use a `url` retornada para levar o cliente ao checkout e concluir o pagamento.
</Tip>

## Upsell

Você pode oferecer um produto adicional ao cliente após a conclusão do pagamento usando o campo `upSellProductId`. O produto é apresentado como uma oferta na página de confirmação — ideal para aumentar o ticket médio sem criar um novo checkout.

<Card title="Regras do produto de upsell">
  O produto referenciado em `upSellProductId` precisa estar com `status: ACTIVE` e **não pode ter `cycle`** (deve ser avulso, sem assinatura).
</Card>

**Exemplo:**

```json theme={null}
POST /checkouts/create
{
  "items": [
    { "id": "prod_principal", "quantity": 1 }
  ],
  "upSellProductId": "prod_bump456xyz"
}
```

**Resposta (com upsell):**

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "upSellProductId": "prod_bump456xyz",
    "status": "PENDING",
    "frequency": "ONE_TIME",
    ...
  },
  "success": true,
  "error": null
}
```

O `upSellProductId` é retornado na resposta e ficará `null` caso nenhum produto de upsell tenha sido vinculado ao checkout.

## Data de vencimento do boleto

Para cobranças com `methods: ["BOLETO"]`, você pode definir a data de vencimento com o campo opcional `dueDate` (`YYYY-MM-DD`). Se omitido, o vencimento padrão é de **3 dias úteis**.

| Campo     | Tipo     | Descrição                                                                  |
| --------- | -------- | -------------------------------------------------------------------------- |
| `dueDate` | `string` | Data de vencimento no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Opcional. |

**Regras:**

* Só é válido se `methods` incluir `BOLETO` (ignorado nos demais métodos)
* Não pode ser data no passado
* Máximo de 365 dias no futuro

`dueDate` é a data de vencimento enviada ao provedor. Sem juros/multa, após o vencimento o boleto expira (`EXPIRED`) via webhook `PAYMENT_OVERDUE`. Com juros/multa, o boleto pode permanecer aberto para pagamento em atraso.

**Exemplo:**

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

A resposta do checkout expõe `dueDate` (`string` ou `null`):

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "dueDate": "2026-08-15",
    ...
  },
  "success": true,
  "error": null
}
```

## Multa e juros no boleto

Para cobranças com `methods: ["BOLETO"]`, você pode configurar **juros por atraso** (`interest`) e **multa por atraso** (`fine`) que serão aplicados se o cliente pagar após a data de vencimento. Ambos os campos são opcionais e independentes — pode-se enviar só `interest`, só `fine`, ambos ou nenhum.

<Card title="Aplicação dos campos">
  Os campos só têm efeito quando o método de pagamento é `BOLETO`. Para `PIX` ou `CARD` são ignorados silenciosamente.
</Card>

### `interest` — juros por atraso / late interest

| Campo   | Tipo          | Descrição                                                                                                                                 |
| ------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `integer ≥ 0` | Percentual de juros **ao mês**, em centésimos de percentual. `100` = 1% ao mês, `250` = 2,5% ao mês. Quando `0` ou omitido, não há juros. |

Os juros seguem o padrão **percentual ao mês, calculados pro rata die** após o vencimento.

> **EN:** `interest.value` is an integer in hundredths of a percent representing the **monthly** late interest rate (`100` = 1%/month, `250` = 2.5%/month). It accrues pro rata die after the due date. Omit or use `0` to disable.

### `fine` — multa por atraso / late fine

| Campo   | Tipo                        | Descrição                                                                                                                                                                   |
| ------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `integer ≥ 0`               | Quando `type = "PERCENTAGE"`: centésimos de percentual (`200` = 2%). Quando `type = "FIXED"`: valor em **centavos** (`1000` = R\$ 10,00). Quando `0` ou omitido, sem multa. |
| `type`  | `"PERCENTAGE"` \| `"FIXED"` | `PERCENTAGE` aplica percentual sobre o valor do boleto. `FIXED` aplica um valor fixo em centavos.                                                                           |

A multa é uma **cobrança única** aplicada uma vez após o vencimento.

> **EN:** `fine` is a one-time charge added after the due date. With `type: "PERCENTAGE"`, `value` is in hundredths of a percent (`200` = 2%). With `type: "FIXED"`, `value` is in **cents** (`1000` = R\$ 10.00).

<Note>
  **Unidades resumidas / unit cheat sheet:** `interest.value` e `fine.value` (quando `type = "PERCENTAGE"`) são sempre em centésimos de percentual — `100` = 1%. `fine.value` (quando `type = "FIXED"`) e `amount` seguem o restante da API e são em centavos — `1000` = R\$ 10,00.
</Note>

**Exemplo — juros de 1% ao mês + multa de 2%:**

```json theme={null}
POST /checkouts/create
{
  "methods": ["BOLETO"],
  "dueDate": "2026-08-15",
  "items": [
    { "id": "prod_abc123", "quantity": 1 }
  ],
  "interest": { "value": 100 },
  "fine": { "value": 200, "type": "PERCENTAGE" }
}
```

**Exemplo — só multa fixa de R\$ 10,00:**

```json theme={null}
POST /checkouts/create
{
  "methods": ["BOLETO"],
  "dueDate": "2026-08-15",
  "items": [
    { "id": "prod_abc123", "quantity": 1 }
  ],
  "fine": { "value": 1000, "type": "FIXED" }
}
```

**Resposta:**

Os mesmos objetos `interest` e `fine` constam na resposta de `GET /checkouts/get` e `GET /checkouts/list`, ou ficam `null` quando nenhum dos campos foi configurado. O campo `dueDate` também é retornado (`string` ou `null`).

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "dueDate": "2026-08-15",
    "interest": { "value": 100 },
    "fine": { "value": 200, "type": "PERCENTAGE" },
    ...
  },
  "success": true,
  "error": null
}
```


# Reembolsar um Checkout
Source: https://docs.abacatepay.com/pages/payment/refund

POST /checkouts/refund
Reembolsa integralmente um Checkout pago (PIX ou Cartão). O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados.


Reembolsa integralmente um Checkout pago. O valor reembolsado é igual ao valor original da transação — não há reembolso parcial.

<Card title="Obrigatório">
  Apenas `id` é obrigatório — o ID público do recurso a reembolsar.
</Card>

O campo `id` aceita:

| Prefixo                                | Recurso                                                               |
| -------------------------------------- | --------------------------------------------------------------------- |
| `bill_...`                             | ID público do Checkout (billing) — resolve para o payment intent pago |
| `char_...`, `pix_char_...`, `card_...` | ID público do payment intent (charge)                                 |

**Exemplo mínimo:**

```json theme={null}
{
  "id": "bill_abc123xyz"
}
```

**Exemplo com motivo:**

```json theme={null}
{
  "id": "bill_abc123xyz",
  "reason": "Pedido cancelado pelo cliente."
}
```

**Resposta:**

```json theme={null}
{
  "data": { "refundPublicId": "tran_refund789xyz" },
  "success": true,
  "error": null
}
```

<Tip title="Idempotência">
  Chamar o endpoint para o mesmo `id` retorna sempre o mesmo `refundPublicId` — não cria reembolsos duplicados.
</Tip>

***

## Regras de negócio

* **Reembolso total apenas** — o valor é sempre igual ao valor original da transação.
* **Métodos suportados** — `PIX`, `PIX_QRCODE` e `CARD`. Boleto, TED e movimentações internas não são reembolsáveis via API.
* **Estado exigido:**
  * `PIX` / `PIX_QRCODE` — transação precisa estar `COMPLETE`.
  * `CARD` — transação precisa estar `APPROVED` ou `COMPLETE`.
* **Disputas** — transações em disputa (`UNDER_DISPUTE` ou `metadata.underDispute=true`) não podem ser reembolsadas por este endpoint.
* **Saldo** — o valor é debitado do saldo `available` da loja (ou `pending`, em casos específicos de `CARD`). Sem saldo, retorna `INSUFFICIENT_FUNDS`.
* **Modo dev (sandbox)** — em `devMode` o reembolso é confirmado instantaneamente, sem chamar o provider real.
* **Status final após o reembolso:**
  * A transação original vira `REFUNDED`.
  * O billing vira `REFUNDED`.
  * O payment intent vira `REFUNDED`.
  * É criada uma nova transação `WITHDRAW` representando o reembolso (retornada em `refundPublicId`).

<Note>
  Ao concluir, é disparado o webhook [`checkout.refunded`](/pages/webhooks/events/checkout). Configure seu endpoint em [Webhooks](/pages/webhooks/create) para receber a notificação.
</Note>

***

## Códigos de erro

| Código                       | Significado                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `LOCK_NOT_ACQUIRED`          | Outra operação está em andamento para esta loja — tente novamente em instantes.                                  |
| `TRANSACTION_NOT_FOUND`      | O `id` informado não existe ou não pertence à loja.                                                              |
| `TRANSACTION_NOT_REFUNDABLE` | A transação não está em um estado reembolsável (precisa estar `COMPLETE`, ou `APPROVED`/`COMPLETE` para `CARD`). |
| `TRANSACTION_UNDER_DISPUTE`  | Transação em disputa — não pode ser reembolsada.                                                                 |
| `INVALID_METHOD`             | Apenas `PIX`, `PIX_QRCODE` e `CARD` podem ser reembolsados.                                                      |
| `INSUFFICIENT_FUNDS`         | Saldo da loja menor que o valor da transação.                                                                    |
| `STORE_NOT_FOUND`            | Loja não encontrada.                                                                                             |
| `REFUND_REQUEST_FAILED`      | Falha ao criar a transação no ledger ou ao acionar o provider.                                                   |
| `REFUND_CONFIRMATION_FAILED` | Falha ao confirmar o reembolso após a criação.                                                                   |

**Exemplo de erro:**

```json theme={null}
{
  "data": null,
  "success": false,
  "error": "TRANSACTION_UNDER_DISPUTE"
}
```

***

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.abacatepay.com/v2/checkouts/refund \
  -H "Authorization: Bearer $ABACATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "bill_abc123xyz",
    "reason": "Pedido cancelado pelo cliente."
  }'
```


# Criar um Saque
Source: https://docs.abacatepay.com/pages/payouts/create

POST /payouts/create
Permite que você crie um novo payout para transferir valores da sua conta AbacatePay.

Você pode usar esta rota para:
- **Realizar saques** da sua conta para sua própria chave PIX
- **Enviar dinheiro** para outras contas
- **Realizar pagamentos** diretamente pela API
- **Efetuar transferências** para fornecedores, parceiros ou terceiros

**Importante**: A chave PIX de destino não precisa ter a mesma titularidade do CNPJ da sua conta. Você pode realizar payouts para qualquer chave PIX válida.


Saca saldo da sua conta para uma chave PIX de sua titularidade.

<Card>
  Requer a permissão `WITHDRAW:CREATE`.
</Card>

<Note>
  **Saques vs PIX:** use **Saques** para sua própria chave PIX. Para enviar a terceiros use [Enviar PIX](/pages/pix/create).
</Note>

<Warning>
  O destino é aninhado em `pix`, com as chaves `key` e `type`. Enviar
  `pixKey`/`pixKeyType` no topo falha com `Property 'pix' is missing`, e
  aninhar com esses nomes falha com `Property 'pix.type' is missing`.
</Warning>

**Formato aceito pela API:**

```json theme={null}
{
  "amount": 10000,
  "description": "Saque semanal",
  "externalId": "saque-123",
  "pix": {
    "key": "sua-chave@email.com",
    "type": "EMAIL"
  }
}
```

**Limites:**

* Valor mínimo: R\$ 3,50
* Taxa: R\$ 0,80 por saque
* Limite de frequência: 1 saque por minuto (HTTP 429 se excedido)


# Buscar saque
Source: https://docs.abacatepay.com/pages/payouts/get

GET /payouts/get
Permite que você recupere os detalhes de um payout específico usando o externalId.

Retorna os dados de um saque pelo seu `id`.

<Card>
  Requer a permissão `WITHDRAW:READ`.
</Card>

Use para verificar o `status` de um saque após criá-lo. Quando `status` for `COMPLETE`, o campo `receiptUrl` estará disponível com o comprovante.

**Valores de `status`:**

| Valor       | Significado                         |
| ----------- | ----------------------------------- |
| `PENDING`   | Aguardando processamento            |
| `COMPLETE`  | Concluído — `receiptUrl` disponível |
| `CANCELLED` | Cancelado                           |
| `REFUNDED`  | Reembolsado                         |


# Listar Saques
Source: https://docs.abacatepay.com/pages/payouts/list

GET /payouts/list
Permite que você recupere uma lista de todos os payouts criados com suporte a paginação.


Retorna todos os saques realizados pela sua conta.

<Card>
  Requer a permissão `WITHDRAW:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Saque](/pages/payouts/create), incluindo `status`, `amount`, `platformFee` e `receiptUrl`.


# Referência
Source: https://docs.abacatepay.com/pages/payouts/reference

Saques do seu saldo para sua própria chave PIX

Com **payouts** você saca o saldo da conta de forma automatizada para uma chave PIX de sua titularidade.

## Estrutura

Exemplo de resposta de um saque:

```json theme={null}
{
  "data": {
    "id": "txn_abc123xyz",
    "status": "PENDING",
    "devMode": false,
    "receiptUrl": null,
    "amount": 10000,
    "platformFee": 100,
    "externalId": "saque-123",
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

## Atributos

| Atributo      | Tipo           | Descrição                                                   |
| ------------- | -------------- | ----------------------------------------------------------- |
| `id`          | string         | ID único da transação na AbacatePay                         |
| `status`      | string         | Status do saque (veja valores abaixo)                       |
| `devMode`     | boolean        | `true` se criado em sandbox                                 |
| `receiptUrl`  | string \| null | URL do comprovante; disponível quando `status` é `COMPLETE` |
| `amount`      | number         | Valor em centavos (ex.: 10000 = R\$ 100,00)                 |
| `platformFee` | number         | Taxa da plataforma em centavos                              |
| `externalId`  | string         | ID no seu sistema                                           |
| `createdAt`   | string         | Data/hora de criação (ISO 8601)                             |
| `updatedAt`   | string         | Data/hora da última atualização                             |

**Valores de `status`:**

| Valor       | Significado                      |
| ----------- | -------------------------------- |
| `PENDING`   | Criado, aguardando processamento |
| `EXPIRED`   | Expirado                         |
| `CANCELLED` | Cancelado                        |
| `COMPLETE`  | Concluído com sucesso            |
| `REFUNDED`  | Reembolsado                      |

## Limites e taxas

* **Mínimo:** R\$ 3,50 (350 centavos)
* **Taxa:** R\$ 0,80 por saque dentro dos limites; ver [termos de uso](https://abacatepay.com/termos)
* **Processamento:** instantâneo; 24/7 respeitando limites diários e noturnos da conta
* **Limite:** 1 saque por minuto; excesso retorna HTTP 429. Para aumentar, fale com o suporte

## Segurança

* Requisições autenticadas via Bearer Token
* Abusos podem levar à suspensão da conta conforme os [termos de uso](https://abacatepay.com/termos)


# Enviar PIX
Source: https://docs.abacatepay.com/pages/pix/create

POST /pix/send
Permite que você envie dinheiro via PIX para qualquer chave PIX que não seja do titular da conta.

Você pode usar esta rota para:
- **Enviar pagamentos** para fornecedores, parceiros ou terceiros
- **Realizar transferências** para contas de outras pessoas ou empresas
- **Efetuar pagamentos** diretamente pela API

**Importante**: Esta funcionalidade é diferente dos payouts, pois permite enviar dinheiro para chaves PIX que não pertencem ao titular da conta. Use payouts quando quiser enviar para sua própria chave PIX.


Envia dinheiro para qualquer chave PIX de terceiros — fornecedores, parceiros ou colaboradores.

<Card>
  Requer a permissão `WITHDRAW:CREATE`.
</Card>

<Note>
  **PIX vs Saques:** use **PIX** para enviar a chaves de terceiros. Para sacar para a sua própria chave use [Saques](/pages/payouts/create).
</Note>

<Warning>
  O destino é aninhado em `pix`, com as chaves `key` e `type`. Enviar
  `pixKey`/`pixKeyType` no topo falha com `Property 'pix' is missing`, e
  aninhar com esses nomes falha com `Property 'pix.type' is missing`.
</Warning>

**Formato aceito pela API:**

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

**Tipos de chave PIX aceitos:**

| `pix.type` | Exemplo               |
| ---------- | --------------------- |
| `CPF`      | `12345678901`         |
| `CNPJ`     | `12345678000190`      |
| `PHONE`    | `11987654321`         |
| `EMAIL`    | `contato@exemplo.com` |
| `RANDOM`   | UUID aleatório        |
| `BR_CODE`  | Código completo do QR |

<Tip title="Limites">
  Valor mínimo: R\$ 1,00. O processamento é instantâneo e disponível 24/7.
</Tip>


# Buscar PIX
Source: https://docs.abacatepay.com/pages/pix/get

GET /pix/get
Permite que você recupere os detalhes de uma transação PIX específica usando o ID ou externalId.

Você pode buscar usando:
- `id`: Identificador único da transação PIX na AbacatePay
- `externalId`: Identificador único do PIX em seu sistema

**Importante**: Você deve fornecer pelo menos um dos parâmetros (`id` ou `externalId`).


Retorna os dados de uma transação PIX pelo seu `id`.

<Card>
  Requer a permissão `WITHDRAW:READ`.
</Card>

Use para acompanhar o `status` de um envio após criar a transação.

**Valores de `status`:**

| Valor       | Significado                                   |
| ----------- | --------------------------------------------- |
| `PENDING`   | Aguardando processamento                      |
| `COMPLETE`  | Enviado com sucesso — `receiptUrl` disponível |
| `CANCELLED` | Cancelado                                     |
| `REFUNDED`  | Reembolsado                                   |


# Listar PIX
Source: https://docs.abacatepay.com/pages/pix/list

GET /pix/list
Consulta um envio de PIX pelo `id`. Apesar do nome, esta rota não pagina nem aceita filtros: `id` é obrigatório e o contrato é o mesmo de `/pix/get`.


Retorna todas as transações PIX enviadas pela sua conta.

<Card>
  Requer a permissão `WITHDRAW:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Enviar PIX](/pages/pix/create), incluindo `status`, `amount`, `platformFee` e `receiptUrl`.


# Referência
Source: https://docs.abacatepay.com/pages/pix/reference

Envie dinheiro via PIX para qualquer chave PIX

Com o **PIX** você envia dinheiro para qualquer chave PIX que não seja da conta titular — terceiros, fornecedores ou parceiros.

<Note>
  **PIX vs Saques:** use **PIX** para enviar a chaves de terceiros; use **Saques** para enviar para sua própria chave.
</Note>

## Estrutura

Exemplo de resposta de uma transação PIX:

```json theme={null}
{
  "data": {
    "id": "txn_abc123xyz",
    "status": "PENDING",
    "devMode": false,
    "receiptUrl": "https://app.abacatepay.com/receipt/txn_abc123xyz",
    "amount": 10000,
    "platformFee": 100,
    "externalId": "pix-123",
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

## Atributos

| Atributo      | Tipo           | Descrição                                                   |
| ------------- | -------------- | ----------------------------------------------------------- |
| `id`          | string         | ID único da transação na AbacatePay                         |
| `status`      | string         | Status da transação (veja valores abaixo)                   |
| `devMode`     | boolean        | `true` se criado em sandbox                                 |
| `receiptUrl`  | string         | URL do comprovante; disponível quando `status` é `COMPLETE` |
| `amount`      | number         | Valor em centavos (ex.: 10000 = R\$ 100,00)                 |
| `platformFee` | number         | Taxa da plataforma em centavos                              |
| `externalId`  | string \| null | ID no seu sistema; pode ser `null`                          |
| `createdAt`   | string         | Data/hora de criação (ISO 8601)                             |
| `updatedAt`   | string         | Data/hora da última atualização                             |

**Valores de `status`:**

| Valor       | Significado                      |
| ----------- | -------------------------------- |
| `PENDING`   | Criado, aguardando processamento |
| `EXPIRED`   | Expirado                         |
| `CANCELLED` | Cancelado                        |
| `COMPLETE`  | Concluído com sucesso            |
| `REFUNDED`  | Reembolsado                      |

## Tipos de chave PIX

Ao criar um PIX, informe o tipo da chave de destino:

| Tipo      | Descrição              | Exemplo               |
| --------- | ---------------------- | --------------------- |
| `CPF`     | CPF (11 dígitos)       | `12345678901`         |
| `CNPJ`    | CNPJ (14 dígitos)      | `12345678000190`      |
| `PHONE`   | Celular (DDD + número) | `11987654321`         |
| `EMAIL`   | E-mail                 | `contato@exemplo.com` |
| `RANDOM`  | Chave aleatória (UUID) | `a1b2c3d4-e5f6-...`   |
| `BR_CODE` | Código BR (QR Code)    | Código completo do QR |

## Limites e taxas

* **Mínimo:** R\$ 1,00
* **Taxa:** ver [termos de uso](https://abacatepay.com/termos)
* **Processamento:** instantâneo; disponível 24/7
* **Limite:** consulte o dashboard; excesso pode retornar HTTP 429

## Segurança

* Requisições autenticadas via Bearer Token
* Abusos podem levar à suspensão da conta conforme os [termos de uso](https://abacatepay.com/termos)


# Indo para produção
Source: https://docs.abacatepay.com/pages/production

Como sair do dev mode e começar a faturar

Ir para produção envolve dois passos independentes: **verificar sua conta** (processo burocrático, feito uma vez só) e **trocar a chave de API** no seu sistema (mudança de código). Ambos precisam estar prontos antes de processar pagamentos reais.

<Info>
  Antes de iniciar, confirme que você passou pelo [checklist do Dev mode](/pages/devmode#checklist-antes-de-ir-para-producao). Ir para produção com integração incompleta pode causar falhas silenciosas.
</Info>

## O que muda na prática

|                      | Dev mode          | Produção           |
| -------------------- | ----------------- | ------------------ |
| Chave de API         | Começa com `dev_` | Começa com `prod_` |
| Pagamentos           | Simulados         | Reais              |
| Webhooks             | Eventos fictícios | Eventos reais      |
| Saque                | Não disponível    | Disponível         |
| Aprovação necessária | Não               | Sim                |

A troca de ambiente é só isso: substituir a chave de API. Não há URL diferente.

Al migrar do ambiente de desenvolvimento para produção, você precisará completar o processo de verificação da sua conta. Este processo é necessário para garantir a segurança e conformidade das operações.

<Card title="Validação do Projeto">
  Além da verificação de documentos, nossa equipe também valida se o seu projeto está dentro das especificações e em conformidade com nossos termos de uso e regras de operação.

  Antes de iniciar o processo, verifique se a sua operação está na nossa [lista de operações suportadas](/operacoes-suportadas) para garantir que poderemos dar suporte ao seu negócio.
</Card>

## Processo de Verificação

Para ativar sua conta em produção, siga estes passos:

<Steps>
  <Step title="Acesse o Modo de Produção">
    <Card>
      <img alt="Interface da plataforma AbacatePay mostrando o botão de Dev mode" />

      <Card title="Desative o Dev mode">
        Clique no botão "Dev mode" no canto superior direito da plataforma para iniciar o processo de migração
      </Card>
    </Card>
  </Step>

  <Step title="Complete o Cadastro">
    <Card>
      <img alt="Formulário de documentação da AbacatePay" />

      <Card title="Forneça as Informações Necessárias">
        Preencha os dados da sua empresa, informações dos sócios e anexe os documentos solicitados:

        * Documentos da empresa
        * Documentos dos sócios
        * Comprovante de endereço
        * Outros documentos específicos do seu segmento
      </Card>
    </Card>
  </Step>
</Steps>

<Card title="Processo de Aprovação">
  Após o envio dos documentos:

  * Nossa equipe analisará sua documentação
  * Validaremos se o projeto está em conformidade com nossos termos e regras
  * Você receberá uma resposta em até 24 horas
  * O e-mail de aprovação conterá instruções para os próximos passos
</Card>

## Após a aprovação

Quando sua conta for aprovada, você receberá um e-mail com as instruções. O que fazer:

1. Gere uma chave de **Produção** no dashboard (Integração → API Keys → Criar Chave)
2. Substitua a chave de Dev mode no seu sistema pela chave de Produção
3. Crie novamente os webhooks no ambiente de Produção (webhooks de Dev não recebem eventos reais)
4. Faça uma transação de teste com valor real para confirmar que tudo está funcionando

<Warning>
  Não reutilize webhooks do Dev mode em produção. Eles precisam ser criados separadamente com a chave de Produção.
</Warning>

<Card title="Precisa de ajuda?" icon="headset">
  Nossa equipe está disponível para auxiliar. Entre em contato: <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Criar um produto
Source: https://docs.abacatepay.com/pages/products/create

POST /products/create
Permite que você crie um novo produto que pode ser usado em cobranças.
Produtos podem ser avulsos (pagamento único) ou de assinatura; use o campo opcional `cycle` para definir a recorrência (`WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`). Quando `cycle` é omitido ou `null`, o produto é avulso.

**Alternativa**: Você também pode criar e gerenciar seus produtos pelo [Dashboard da AbacatePay](https://app.abacatepay.com/produtos).


Cria um produto no seu catálogo para usar em checkouts, assinaturas e links de pagamento.

<Card title="Obrigatórios">
  `externalId` (único no seu sistema), `name`, `price` (em centavos) e `currency` (sempre `"BRL"`).
</Card>

**Produto digital com arquivo para download** (passe `fileUrl` com a URL pública de um PDF):

```json theme={null}
{
  "externalId": "ebook-001",
  "name": "E-book: Guia Completo",
  "price": 4990,
  "currency": "BRL",
  "fileUrl": "https://exemplo.com/guia-completo.pdf"
}
```

<Note title="fileUrl">
  `fileUrl` deve apontar para um PDF público acessível. Tamanho máximo: 20 MB. O arquivo é armazenado pela AbacatePay e o comprador recebe acesso após o pagamento. O campo `hasFile: true` na resposta confirma o vínculo.
</Note>

**Produto avulso** (pagamento único — omita `cycle`):

```json theme={null}
{
  "externalId": "prod-123",
  "name": "Camiseta Premium",
  "price": 8990,
  "currency": "BRL",
  "description": "Camiseta 100% algodão"
}
```

**Produto de assinatura** (defina `cycle`):

```json theme={null}
{
  "externalId": "plano-mensal",
  "name": "Plano Mensal",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY"
}
```

**Produto de assinatura com período de teste gratuito** (defina `trialDays`):

```json theme={null}
{
  "externalId": "plano-mensal-trial",
  "name": "Plano Mensal com 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7
}
```

**Valores de `cycle`:** `WEEKLY` · `MONTHLY` · `QUARTERLY` · `SEMIANNUALLY` · `ANNUALLY`

<Note title="trialDays">
  `trialDays` exige `cycle`. Valor inteiro entre 1 e 90. O cliente não é cobrado durante o período de teste — a primeira cobrança ocorre ao final do trial.
</Note>

<Tip title="ID retornado">
  Guarde o `data.id` retornado — é ele que você passa como `items[].id` ao criar checkouts e assinaturas.
</Tip>


# Deletar um Produto
Source: https://docs.abacatepay.com/pages/products/delete

POST /products/delete
Remove um produto da sua loja (avulso ou de assinatura).

Esta operação é irreversível. Use com cuidado.


Remove um produto do catálogo pelo seu `id`.

<Card>
  Requer a permissão `PRODUCT:DELETE`.
</Card>

<Warning>
  Produtos vinculados a checkouts ou assinaturas ativos não devem ser deletados — isso pode causar inconsistências nas cobranças em andamento.
</Warning>


# Buscar um produto
Source: https://docs.abacatepay.com/pages/products/get

GET /products/get
Retorna os dados de um produto específico baseado em filtros, incluindo o campo `cycle` (assinatura ou avulso).

Você pode usar essa rota para buscar um produto por ID ou externalId.


Retorna os dados de um produto pelo seu `id`.

<Card>
  Requer a permissão `PRODUCT:READ`.
</Card>

Use para verificar `status`, `price`, `cycle`, `trialDays` e demais atributos antes de criar um checkout com o produto.


# Listar produtos
Source: https://docs.abacatepay.com/pages/products/list

GET /products/list
Retorna todos os produtos que você criou com suporte a paginação.

Você pode usar essa rota para visualizar todos os seus produtos, incluindo status, preços, ciclo de assinatura (quando aplicável) e demais informações.

**Alternativa**: Você também pode visualizar e gerenciar seus produtos pelo [Dashboard da AbacatePay](https://app.abacatepay.com/produtos).


Retorna todos os produtos do seu catálogo.

<Card>
  Requer a permissão `PRODUCT:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Produto](/pages/products/create), incluindo `id`, `name`, `price`, `cycle`, `trialDays` e `status`.


# Referência
Source: https://docs.abacatepay.com/pages/products/reference

Gerencie produtos para suas cobranças

Produtos são itens do seu catálogo usados nas cobranças: nome, preço, descrição e opcionalmente ciclo de assinatura. **Avulso** = pagamento único (`cycle` omitido ou `null`). **Assinatura** = `cycle`: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY` ou `ANNUALLY`.

Produtos também podem ter um **arquivo para download** vinculado: um PDF que o comprador recebe acesso após o pagamento (e-books, ingressos, licenças, etc.).

## Criar produto

Use `/products/create`. Moeda é sempre `BRL`.

<Card title="Campos obrigatórios">
  Obrigatórios: `externalId` (único no seu sistema), `name`, `price`, `currency`. Opcionais: `description`, `imageUrl`, `fileUrl`, `cycle` (null/omitido = avulso), `trialDays` (requer `cycle`).
</Card>

**Exemplo (produto avulso):**

```json theme={null}
POST /products/create
{
  "externalId": "prod-123",              // obrigatório - identificador único do produto no seu sistema
  "name": "Produto Exemplo",             // obrigatório - nome do produto
  "price": 10000,                        // obrigatório - preço em centavos
  "currency": "BRL",                     // obrigatório - moeda (sempre BRL)
  "description": "Descrição do produto", // opcional - descrição
  "imageUrl": null                       // opcional - URL da imagem (string | null)
}
```

**Exemplo (produto de assinatura):**

```json theme={null}
POST /products/create
{
  "externalId": "prod-assinatura-1",
  "name": "Plano Mensal",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY"                     // opcional - WEEKLY | MONTHLY | QUARTERLY | SEMIANNUALLY | ANNUALLY; omitir ou null = avulso
}
```

**Exemplo (produto de assinatura com período de teste gratuito):**

```json theme={null}
POST /products/create
{
  "externalId": "prod-assinatura-trial",
  "name": "Plano Mensal com 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7                         // opcional - inteiro 1–90; requer cycle
}
```

**Resposta (modelo Product):**

```json theme={null}
{
  "data": {
    "externalId": "prod-assinatura-trial",
    "name": "Plano Mensal com 7 dias grátis",
    "description": null,
    "imageUrl": null,
    "hasFile": false,
    "price": 4990,
    "devMode": false,
    "currency": "BRL",
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z",
    "status": "ACTIVE",
    "id": "prod_abc123xyz",
    "cycle": "MONTHLY",
    "trialDays": 7
  },
  "success": true,
  "error": null
}
```

O `data` retornado segue o modelo Product: `id`, `externalId`, `name`, `description`, `imageUrl`, `hasFile`, `price`, `currency`, `status`, `cycle`, `trialDays`, `createdAt`, `updatedAt`, etc.

## Arquivo para download

Vincule um PDF ao produto passando `fileUrl` na criação. A AbacatePay baixa e armazena o arquivo internamente — o link original não é exposto.

* `fileUrl` aceita qualquer URL pública de PDF. Tamanho máximo: **20 MB**.
* Após o pagamento, o comprador recebe acesso ao download automaticamente.
* O campo `hasFile` na resposta indica se o produto possui arquivo vinculado (`true` / `false`).

**Exemplo (produto com arquivo):**

```json theme={null}
POST /products/create
{
  "externalId": "ebook-001",
  "name": "E-book: Guia Completo",
  "price": 4990,
  "currency": "BRL",
  "fileUrl": "https://exemplo.com/guia-completo.pdf"
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "prod_abc123xyz",
    "externalId": "ebook-001",
    "name": "E-book: Guia Completo",
    "hasFile": true,
    "price": 4990,
    "currency": "BRL",
    "status": "ACTIVE",
    ...
  },
  "success": true,
  "error": null
}
```

<Note>
  O URL do arquivo nunca é exposto pela API. Use `hasFile` para verificar se o produto tem um arquivo vinculado.
</Note>


# Introdução
Source: https://docs.abacatepay.com/pages/reference/introduction

Base URL, autenticação, formato de resposta, códigos de status e limites da API.

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.

<CardGroup>
  <Card title="Autenticação" icon="key" href="/pages/authentication">
    Como gerar e usar suas chaves de API.
  </Card>

  <Card title="Dev mode" icon="code" href="/pages/devmode">
    Testar sem risco antes de ir para produção.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pages/webhooks">
    Receber notificações de eventos em tempo real.
  </Card>
</CardGroup>

***

## Base URL

Todas as requisições da v2 usam o seguinte endereço:

```
https://api.abacatepay.com/v2
```

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

```bash theme={null}
Authorization: Bearer SUA_CHAVE_API
```

Requisições sem chave ou com chave inválida retornam `401 Unauthorized`. Consulte a [página de autenticação](/pages/authentication) para criar e gerenciar suas chaves.

***

## Formato de resposta

Todos os endpoints retornam JSON com a mesma estrutura:

```json theme={null}
{
  "data": { ... },
  "success": true,
  "error": null
}
```

Em caso de erro:

```json theme={null}
{
  "data": null,
  "success": false,
  "error": "Mensagem descritiva do erro"
}
```

<Info>
  Sempre verifique `success` antes de acessar `data`. Nunca assuma que a requisição funcionou apenas pelo status HTTP.
</Info>

***

## Códigos de status HTTP

| Código | Significado                                                     |
| ------ | --------------------------------------------------------------- |
| `200`  | Sucesso                                                         |
| `400`  | Requisição inválida — verifique os campos enviados              |
| `401`  | Não autenticado — chave ausente, inválida ou revogada           |
| `403`  | Sem permissão — a chave não tem acesso ao recurso solicitado    |
| `404`  | Recurso não encontrado                                          |
| `422`  | Erro de validação — dados corretos mas semanticamente inválidos |
| `429`  | Rate limit atingido                                             |
| `5xx`  | Erro interno — tente novamente com backoff exponencial          |

***

## 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](/pages/authentication) 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

| Param    | Tipo      | Descrição                                               |
| -------- | --------- | ------------------------------------------------------- |
| `limit`  | `integer` | Itens por página (1–100, default `100`)                 |
| `after`  | `string`  | Cursor — `publicId` do último item da página anterior   |
| `before` | `string`  | Cursor — `publicId` do primeiro item da página seguinte |

<Warning>
  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`.
</Warning>

Envelope retornado hoje:

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "error": null
}
```

Para avançar, passe `after` com o `id` do último item recebido:

```bash theme={null}
GET /v2/customers/list?limit=20&after=cust_abc123
```

### Filtro por data

| Param       | Tipo     | Descrição                             |
| ----------- | -------- | ------------------------------------- |
| `startDate` | `string` | Data inicial inclusive (`YYYY-MM-DD`) |
| `endDate`   | `string` | Data final inclusive (`YYYY-MM-DD`)   |

Os dois parâmetros são opcionais e podem ser usados isoladamente ou combinados com `limit`, `after` e `before`.

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

<Info>
  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).
</Info>

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

<AccordionGroup>
  <Accordion title="400 — os campos estão corretos mas a requisição é rejeitada">
    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.
  </Accordion>

  <Accordion title="401 — chave válida mas ainda recebo Unauthorized">
    Confirme que o header está exatamente como `Authorization: Bearer SUA_CHAVE` — com espaço entre `Bearer` e a chave, sem aspas extras.
  </Accordion>

  <Accordion title="403 — tenho a chave mas não tenho acesso ao endpoint">
    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.
  </Accordion>

  <Accordion title="422 — dados válidos mas semanticamente errados">
    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.
  </Accordion>

  <Accordion title="5xx — erro do servidor">
    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.
  </Accordion>
</AccordionGroup>

## Dicas gerais

<CardGroup>
  <Card title="Use Dev mode para testes" icon="code" href="/pages/devmode">
    Chaves de desenvolvimento simulam pagamentos sem cobranças reais.
  </Card>

  <Card title="Armazene a chave em variável de ambiente" icon="shield">
    Nunca comite sua chave de API no código. Use `process.env`, `.env` ou um gerenciador de segredos.
  </Card>

  <Card title="Idempotência em webhooks" icon="repeat" href="/pages/webhooks">
    Sempre registre o ID do evento recebido e descarte duplicatas.
  </Card>

  <Card title="Backoff em erros 5xx" icon="rotate">
    Implemente retentativas com espera crescente para falhas temporárias.
  </Card>
</CardGroup>


# Go
Source: https://docs.abacatepay.com/pages/sdks/go

Integre a AbacatePay em aplicações Go em minutos.

<Card title="AbacatePay Go SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-go-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Go 1.21+
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

```bash theme={null}
go get github.com/AbacatePay/abacatepay-go-sdk
```

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```go theme={null}
import (
    "os"
    "time"
    "github.com/AbacatePay/abacatepay-go-sdk/abacatepay"
)

client, err := abacatepay.New(&abacatepay.ClientConfig{
    ApiKey:  os.Getenv("ABACATEPAY_API_KEY"),
    Timeout: 10 * time.Second,
})
if err != nil {
    panic(err)
}
```

## Primeira cobrança (PIX)

```go theme={null}
import (
    "context"
    "log"
    "time"

    "github.com/AbacatePay/abacatepay-go-sdk/v1/pix"
)

ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()

response, err := client.Pix.Create(ctx, &pix.CreateQrCodePIXBody{
    Amount: 1000, // em centavos
})
if err != nil {
    log.Fatal(err)
}

log.Printf("PIX criado: %s\n", response.Data.ID)
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "pix_char_123456",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "brCode": "00020101021226950014br.gov.bcb.pix...",
    "createdAt": "2025-03-24T21:50:20.772Z",
    "expiresAt": "2025-03-25T21:50:20.772Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Java
Source: https://docs.abacatepay.com/pages/sdks/java

Integre a AbacatePay em aplicações Java em minutos.

<Card title="AbacatePay Java SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-java-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Java 8+ e Maven
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

Adicione a dependência Feign ao seu `pom.xml`:

```xml theme={null}
<dependency>
    <groupId>io.github.openfeign</groupId>
    <artifactId>feign-core</artifactId>
    <version>11.7</version>
</dependency>
```

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```java theme={null}
import com.abacatepay.AbacatePay;

AbacatePay abacate = new AbacatePay(System.getenv("ABACATEPAY_API_KEY"));
```

## Primeira cobrança

```java theme={null}
import com.abacatepay.model.billing.CreateBillingData;
import com.abacatepay.model.billing.CreateBillingResponse;
import java.util.Arrays;

CreateBillingData billingData = new CreateBillingData();
billingData.setFrequency("ONE_TIME");
billingData.setMethods(Arrays.asList("PIX"));
billingData.setReturnUrl("https://meusite.com/app");
billingData.setCompletionUrl("https://meusite.com/pagamento/sucesso");

CreateBillingResponse billing = abacate.createBilling(billingData);
System.out.println(billing.getUrl()); // URL de pagamento para o cliente
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Kotlin
Source: https://docs.abacatepay.com/pages/sdks/kotlin

Integre a AbacatePay em aplicações Android e Kotlin em minutos.

<Card title="AbacatePay Kotlin SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-kotlin-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Kotlin 2+ e Java 11+
* Android 5+ (se for app Android)
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

Adicione ao `build.gradle.kts`:

```kotlin theme={null}
repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.abacatepay:abacatepay-kotlin-sdk:0.0.5")
}
```

## Configuração

Armazene sua chave de API em uma variável de ambiente ou arquivo seguro e nunca no código:

```kotlin theme={null}
import com.abacatepay.AbacatePayClient

val client = AbacatePayClient(apiKey = BuildConfig.ABACATEPAY_API_KEY)
```

## Primeira cobrança

```kotlin theme={null}
import kotlinx.coroutines.runBlocking
import com.abacatepay.models.*

runBlocking {
    val billing = client.createBilling(
        frequency     = BillingFrequency.ONE_TIME,
        methods       = listOf(BillingMethod.PIX),
        returnUrl     = "https://meusite.com/app",
        completionUrl = "https://meusite.com/pagamento/sucesso",
        products = listOf(
            BillingProduct(
                externalId = "PRO-PLAN",
                name       = "Pro plan",
                quantity   = 1,
                price      = 1000, // em centavos
            )
        ),
    )

    println(billing.url) // URL de pagamento para o cliente
}
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Node.js
Source: https://docs.abacatepay.com/pages/sdks/nodejs

Integre a AbacatePay em aplicações Node.js e TypeScript em minutos.

<Card title="AbacatePay Node.js SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-nodejs-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Node.js 18+
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

<CodeGroup>
  ```bash npm theme={null}
  npm install @abacatepay/sdk
  ```

  ```bash yarn theme={null}
  yarn add @abacatepay/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @abacatepay/sdk
  ```

  ```bash bun theme={null}
  bun add @abacatepay/sdk
  ```
</CodeGroup>

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```ts theme={null}
// .env
ABACATEPAY_API_KEY=sua_chave_aqui
```

```ts theme={null}
import { AbacatePay } from "@abacatepay/sdk";

const abacate = AbacatePay({ secret: process.env.ABACATEPAY_API_KEY! });
```

## Primeira cobrança

```ts theme={null}
const checkout = await abacate.checkouts.create({
  items: [{ id: "prod_abc123", quantity: 1 }],
  customerId: "cust_987",
});

console.log(checkout.data.url); // URL de pagamento para o cliente
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_123456789",
    "url": "https://app.abacatepay.com/pay/bill_123456789",
    "amount": 15000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# PHP
Source: https://docs.abacatepay.com/pages/sdks/php

Integre a AbacatePay em aplicações PHP em minutos.

<Card title="AbacatePay PHP SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-php-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* PHP 7.2.5+ e Composer
* SSL habilitado em produção
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

```bash theme={null}
composer require abacatepay/php-sdk
```

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```php theme={null}
use AbacatePay\Clients\Client;

Client::setToken($_ENV['ABACATEPAY_API_KEY']);
```

## Primeira cobrança

```php theme={null}
use AbacatePay\Clients\BillingClient;
use AbacatePay\Resources\Billing;
use AbacatePay\Resources\Billing\Product;
use AbacatePay\Resources\Billing\Metadata as BillingMetadata;
use AbacatePay\Enums\Billing\Methods;
use AbacatePay\Enums\Billing\Frequencies;

$billingClient = new BillingClient();

$billing = $billingClient->create(new Billing([
    'frequency' => Frequencies::ONE_TIME,
    'methods'   => [Methods::PIX],
    'products'  => [
        new Product([
            'external_id' => 'PRO-PLAN',
            'name'        => 'Pro plan',
            'quantity'    => 1,
            'price'       => 1000, // em centavos
        ])
    ],
    'metadata' => new BillingMetadata([
        'return_url'     => 'https://meusite.com/app',
        'completion_url' => 'https://meusite.com/pagamento/sucesso',
    ]),
]));

echo $billing->url; // URL de pagamento para o cliente
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Python
Source: https://docs.abacatepay.com/pages/sdks/python

Integre a AbacatePay em aplicações Python em minutos.

<Card title="AbacatePay Python SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-python-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Python 3.10+
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

<CodeGroup>
  ```bash pip theme={null}
  pip install abacatepay
  ```

  ```bash poetry theme={null}
  poetry add abacatepay
  ```

  ```bash uv theme={null}
  uv add abacatepay
  ```
</CodeGroup>

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```bash theme={null}
# .env
ABACATEPAY_API_KEY=sua_chave_aqui
```

```python theme={null}
import os
import abacatepay

client = abacatepay.AbacatePay(os.environ["ABACATEPAY_API_KEY"])
```

## Primeira cobrança

```python theme={null}
from abacatepay.products import Product

checkout = client.billing.create(
    products=[
        Product(
            external_id="PRO-PLAN",
            name="Pro plan",
            quantity=1,
            price=1000,  # em centavos
        )
    ],
    return_url="https://meusite.com/app",
    completion_url="https://meusite.com/pagamento/sucesso",
)

print(checkout.data.url)  # URL de pagamento para o cliente
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Ruby
Source: https://docs.abacatepay.com/pages/sdks/ruby

Integre a AbacatePay em aplicações Ruby em minutos.

<Card title="AbacatePay Ruby SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-ruby-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Ruby 3.2+
* Gem `abacatepay-ruby` 1.2.2 ou superior
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

<CodeGroup>
  ```bash Gemfile theme={null}
  # Adicione ao seu Gemfile:
  gem 'abacatepay-ruby'
  # Depois execute:
  bundle install
  ```

  ```bash bundler theme={null}
  bundle add abacatepay-ruby
  ```

  ```bash gem theme={null}
  gem install abacatepay-ruby
  ```
</CodeGroup>

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```ruby theme={null}
# config/initializers/abacatepay.rb
AbacatePay.configure do |config|
  config.api_token = ENV['ABACATEPAY_API_KEY']
  config.timeout   = 30 # opcional, em segundos
end
```

<Card title="Dev mode x Produção">
  O ambiente é definido **pela chave utilizada**, não por configuração do SDK — chaves criadas em Dev mode geram transações simuladas. Saiba mais <a href="/pages/devmode">aqui</a>.
</Card>

## Primeira cobrança

```ruby theme={null}
checkout = AbacatePay.checkouts.create(
  AbacatePay::Resources::Checkouts.new(
    methods: ['PIX'],
    products: [
      AbacatePay::Resources::Billings::Product.new(
        external_id: 'prod_abc123xyz',
        name:        'Pro plan',
        quantity:    1,
        price:       1000 # em centavos
      )
    ],
    metadata: AbacatePay::Resources::Billings::Metadata.new(
      return_url:     'https://meusite.com/app',
      completion_url: 'https://meusite.com/pagamento/sucesso'
    )
  )
)

puts checkout.url # URL de pagamento para o cliente
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2026-08-04T18:38:28.573Z"
  }
}
```

## Recursos disponíveis

Todos os recursos são acessíveis pela fachada `AbacatePay.<recurso>`:

| Recurso             | Métodos                                               |
| ------------------- | ----------------------------------------------------- |
| `customers`         | `list` `get` `create` `delete`                        |
| `products`          | `list` `get` `create` `delete`                        |
| `coupons`           | `list` `get` `create` `delete` `toggle`               |
| `checkouts`         | `list` `get` `create` `refund`                        |
| `payment_links`     | `list` `get` `create` `refund`                        |
| `subscriptions`     | `list` `create` `cancel` `change_plan` `record_usage` |
| `transparents`      | `list` `create` `check` `simulate_payment` `refund`   |
| `pix`               | `list` `get` `send_pix`                               |
| `payouts`           | `list` `get` `create`                                 |
| `store`             | `get` `merchant_info` `mrr` `revenue`                 |
| `webhook_endpoints` | `list` `get` `create` `delete`                        |

```ruby theme={null}
AbacatePay.customers.list(limit: 25)
AbacatePay.products.get('prod_abc123xyz')
AbacatePay.checkouts.refund('bill_abc123xyz')
AbacatePay.subscriptions.cancel('subs_abc123xyz')
```

## Tratamento de erros

O SDK de Ruby **levanta exceções** — ele não retorna `{ data, error, success }`. Toda falha herda de `AbacatePay::Error`:

```ruby theme={null}
begin
  checkout = AbacatePay.checkouts.create(data)
rescue AbacatePay::ConfigurationError => e
  # token ausente ou vazio
rescue AbacatePay::ApiError => e
  # erro da API, falha de rede ou timeout
end
```

| Exceção                                | Quando acontece                                         |
| -------------------------------------- | ------------------------------------------------------- |
| `AbacatePay::ConfigurationError`       | Token ausente ou vazio                                  |
| `AbacatePay::ApiError`                 | Erro da API, falha de rede ou timeout                   |
| `AbacatePay::Webhooks::SignatureError` | Assinatura de webhook ausente, vazia ou inválida        |
| `AbacatePay::Webhooks::PayloadError`   | Corpo do webhook malformado ou que não é um objeto JSON |

## Webhooks

A AbacatePay usa **dois mecanismos** e a [documentação de segurança](/pages/webhooks/security) orienta usar os dois:

| Mecanismo                 | O que garante            |
| ------------------------- | ------------------------ |
| `webhookSecret` na query  | autentica a **origem**   |
| Assinatura HMAC no header | integridade do **corpo** |

A chave HMAC é pública e global, publicada na documentação, então a assinatura sozinha não prova origem.

```ruby theme={null}
payload   = request.body.read
signature = request.headers['X-Webhook-Signature']

begin
  # 1. Autentica a origem com o secret definido ao criar o webhook.
  AbacatePay::Webhooks.verify_secret!(
    received: params[:webhookSecret],
    expected: ENV['ABACATEPAY_WEBHOOK_SECRET']
  )

  # 2. Verifica a integridade do corpo antes de fazer o parse.
  event = AbacatePay::Webhooks.construct_event(
    payload: payload, signature: signature
  )
rescue AbacatePay::Webhooks::SignatureError
  return head :unauthorized
rescue AbacatePay::Webhooks::PayloadError
  return head :bad_request
end

case event.type
when 'checkout.completed'          then handle_payment(event.data)
when 'subscription.payment_failed' then handle_dunning(event.data)
end
```

<Tip title="Idempotência é obrigatória">
  A AbacatePay reentrega qualquer webhook que não responda 2xx. Guarde o `id` do evento com índice único no banco e responda 200 também para duplicatas, senão a reentrega não para.
</Tip>

<Warning>
  Em Rails, leia `request.query_parameters` em vez de `params` antes de validar. Tocar em `params` faz o framework parsear o corpo, e um corpo malformado estoura antes do seu código rodar.
</Warning>

## Boleto

Boleto tem vencimento, juros e multa próprios. Valores em centavos.

```ruby theme={null}
AbacatePay.checkouts.create(
  AbacatePay::Resources::Checkouts.new(
    methods: ['BOLETO'],
    due_date: '2026-09-15',
    interest: { value: 100 },
    fine: { value: 200, type: 'PERCENTAGE' },
    products: [
      AbacatePay::Resources::Billings::Product.new(external_id: 'prod_abc123xyz', quantity: 1)
    ]
  )
)
```

No checkout transparente, o boleto exige nome e CPF/CNPJ do pagador. O SDK valida isso localmente, antes de gastar uma chamada:

```ruby theme={null}
boleto = AbacatePay.transparents.create(charge, method: 'BOLETO')
boleto.bar_code   # linha digitável
boleto.url        # PDF para impressão
boleto.br_code    # PIX alternativo da mesma cobrança
```

## Paginação

Listas retornam no máximo 100 itens. Para percorrer tudo sem lidar com cursor:

```ruby theme={null}
AbacatePay.customers.auto_paging_each { |customer| puts customer.name }
```

## Resiliência

O SDK já traz retry com backoff exponencial e jitter em 429 e 5xx. Escritas nunca são repetidas, porque refazer uma criação de cobrança após timeout poderia cobrar o cliente duas vezes.

```ruby theme={null}
AbacatePay.configure do |config|
  config.api_token   = ENV['ABACATEPAY_API_KEY']
  config.timeout     = 30  # segundos
  config.max_retries = 2   # 0 desliga
  config.logger      = Rails.logger  # opcional, o token é redigido
end
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Rust
Source: https://docs.abacatepay.com/pages/sdks/rust

Integre a AbacatePay em aplicações Rust em minutos.

<Card title="AbacatePay Rust SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-rust-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Rust (edição 2021+) com Tokio
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

```bash theme={null}
cargo add abacatepay-rust-sdk
cargo add tokio --features full
```

Ou adicione ao `Cargo.toml`:

```toml theme={null}
[dependencies]
abacatepay-rust-sdk = "0.1.0"
tokio = { version = "1", features = ["full"] }
```

## Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

```rust theme={null}
use abacatepay_rust_sdk::AbacatePay;

let api_key = std::env::var("ABACATEPAY_API_KEY").expect("ABACATEPAY_API_KEY not set");
let client = AbacatePay::new(api_key);
```

## Primeira cobrança

```rust theme={null}
use abacatepay_rust_sdk::{
    AbacatePay, BillingKind, BillingMethods, CreateBillingData, CreateBillingProduct,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AbacatePay::new(std::env::var("ABACATEPAY_API_KEY")?);

    let billing = client.create_billing(CreateBillingData {
        frequency:      BillingKind::OneTime,
        methods:        vec![BillingMethods::Pix],
        return_url:     "https://meusite.com/app".to_string(),
        completion_url: "https://meusite.com/pagamento/sucesso".to_string(),
        products: vec![CreateBillingProduct {
            external_id: "PRO-PLAN".to_string(),
            name:        "Pro plan".to_string(),
            quantity:    1,
            price:       1000.0, // em centavos
            description: None,
        }],
        customer_id: None,
    }).await?;

    println!("{}", billing.url); // URL de pagamento para o cliente
    Ok(())
}
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# SDKs
Source: https://docs.abacatepay.com/pages/sdks/sdks

Bibliotecas oficiais para integração com a API da AbacatePay

## O que são os SDKs da AbacatePay?

Os SDKs (Software Development Kits) da AbacatePay são bibliotecas que simplificam a comunicação com nossa API. Eles oferecem uma interface amigável e específica para cada linguagem, permitindo que você integre rapidamente nossos serviços de pagamento ao seu aplicativo.

<Card title="Benefícios de usar nossos SDKs">
  * **Integração simplificada**: Funções prontas para todos os endpoints da API
  * **Tipagem forte**: Interfaces completas em linguagens com suporte a tipos
  * **Tratamento de erros**: Gerenciamento automático dos casos de erro mais comuns
  * **Menor curva de aprendizado**: Não é necessário conhecer todos os detalhes da API
  * **Atualizações frequentes**: Mantemos os SDKs atualizados com as mais recentes funcionalidades
</Card>

## SDKs Disponíveis

Oferecemos SDKs oficiais para diversas linguagens de programação. Escolha o que melhor se adapta à sua stack tecnológica:

<Tabs>
  <Tab title="Backend">
    <CardGroup>
      <Card title="Node.js" icon="node-js" href="./nodejs">
        SDK oficial para Node.js, compatível com TypeScript e ES modules.
      </Card>

      <Card title="Python" icon="python" href="./python">
        SDK oficial para Python 3.10+, com suporte a async/await e type hints.
      </Card>

      <Card title="Java" icon="java" href="./java">
        SDK oficial para Java 8+, compatível com Spring Boot e Jakarta EE.
      </Card>

      <Card title="PHP" icon="php" href="./php">
        SDK oficial para PHP 7.4+, com suporte a Composer e PSR standards.
      </Card>

      <Card title="Ruby" icon="gem" href="./ruby">
        SDK oficial para Ruby 2.6+, disponível como gem e com suporte a Rails.
      </Card>

      <Card title="Go" icon="golang" href="./go">
        SDK oficial para Go 1.13+, com suporte a módulos e generics.
      </Card>

      <Card title="Rust" icon="rust" href="./rust">
        SDK oficial para Rust, com foco em segurança e performance.
      </Card>

      <Card title="Elixir" icon="elixir" href="https://github.com/AbacatePay/abacatepay-elixir-sdk">
        SDK oficial para Elixir, ideal para aplicações escaláveis e distribuídas.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Mobile">
    <CardGroup>
      <Card title="Kotlin" icon="android" href="./kotlin">
        SDK oficial para Kotlin, ideal para aplicativos Android modernos.
      </Card>

      <Card title="Swift" icon="apple" href="./swift">
        SDK oficial para Swift, ideal para aplicativos iOS e macOS.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Perguntas Frequentes

<Accordion title="Como instalar o SDK da minha linguagem?">
  Cada SDK tem instruções de instalação específicas no seu repositório no GitHub. Geralmente, você pode usar o gerenciador de pacotes da sua linguagem, como npm, pip, composer, bundle, etc.
</Accordion>

<Accordion title="Os SDKs funcionam tanto em modo de desenvolvimento quanto em produção?">
  Sim! Todos os nossos SDKs suportam ambos os ambientes. Em alguns casos, é preciso configurar o parâmetro `environment` ao inicializar o cliente para `sandbox` ou `production`, ou basta usar a chave de api do ambiente desejado.
</Accordion>

<Accordion title="O que fazer se encontrar um bug em um SDK?">
  Você pode abrir uma issue no repositório do GitHub do SDK específico. Nossa equipe está sempre atenta para corrigir bugs e melhorar nossos SDKs.
</Accordion>

<Accordion title="Falta um SDK para a linguagem que eu uso. O que fazer?">
  Entre em contato conosco em <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com) informando qual linguagem você precisa. Também aceitamos contribuições da comunidade!
</Accordion>

## Recursos Adicionais

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="./webhooks">
    Aprenda a configurar webhooks para receber notificações de eventos.
  </Card>

  <Card title="Ambiente de Desenvolvimento" icon="code" href="./devmode">
    Saiba como usar o ambiente de desenvolvimento para testar suas integrações.
  </Card>
</CardGroup>

<Card title="Precisa de ajuda com integração?" icon="headset">
  Nossa equipe está disponível para ajudar. Entre em contato: <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Swift
Source: https://docs.abacatepay.com/pages/sdks/swift

Integre a AbacatePay em aplicações iOS e macOS em minutos.

<Card title="AbacatePay Swift SDK" icon="github" href="https://github.com/AbacatePay/abacatepay-swift-sdk">
  Repositório oficial — issues, changelog e contribuições.
</Card>

## Pré-requisitos

* Swift 5.5+ / Xcode 13+
* iOS 14+ ou macOS 11+
* Uma chave de API ([criar no dashboard](https://app.abacatepay.com))

## Instalação

<CodeGroup>
  ```swift Package.swift theme={null}
  dependencies: [
      .package(url: "https://github.com/AbacatePay/abacatepay-swift-sdk", from: "1.0.0")
  ]
  ```

  ```
  Xcode → File → Add Package Dependencies
  URL: https://github.com/AbacatePay/abacatepay-swift-sdk
  ```
</CodeGroup>

## Configuração

Armazene sua chave de API em variáveis de configuração ou no Keychain e nunca no código:

```swift theme={null}
import AbacatePay

let abacatePay = AbacatePay(apiKey: ProcessInfo.processInfo.environment["ABACATEPAY_API_KEY"]!)
```

## Primeira cobrança

```swift theme={null}
let billingData = CreateBillingData(
    frequency:    .oneTime,
    methods:      [.pix],
    returnUrl:    "https://meusite.com/app",
    completionUrl: "https://meusite.com/pagamento/sucesso",
    products: [
        .init(externalId: "PRO-PLAN", name: "Pro plan", quantity: 1, price: 1000)
    ]
)

do {
    let billing = try await abacatePay.billing.create(data: billingData)
    print(billing.url) // URL de pagamento para o cliente
} catch {
    print("Erro:", error)
}
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2024-11-04T18:38:28.573Z"
  }
}
```

## Próximos passos

<CardGroup>
  <Card title="Configurar webhooks" icon="bell" href="/pages/webhooks">
    Receba notificações em tempo real sobre pagamentos confirmados.
  </Card>

  <Card title="Checkout Transparente" icon="credit-card" href="/pages/transparents/create">
    Aceite PIX e cartão diretamente na sua interface.
  </Card>

  <Card title="Criar clientes" icon="users" href="/pages/client/create">
    Gerencie clientes vinculados às cobranças.
  </Card>

  <Card title="Referência completa" icon="book-open" href="/pages/reference/introduction">
    Todos os endpoints, status codes e formato de resposta.
  </Card>
</CardGroup>


# Bem-vindo à Documentação da AbacatePay
Source: https://docs.abacatepay.com/pages/start/welcome



<div>
  # Bem-vindo à AbacatePay

  <p>
    Receba pagamentos online com PIX, cartão e boleto.<br />
    Seja você um lojista ou desenvolvedor, encontre aqui o que precisa.
  </p>
</div>

<div>
  ## Por onde você quer começar?

  <p>
    Escolha o caminho que faz mais sentido para você agora.
  </p>

  <div>
    <a href="/pages/concepts/overview">
      <div>
        <div>🛍️</div>

        <div>
          Sou lojista / empreendedor
        </div>

        <div>
          Quero entender o produto, criar cobranças e receber pagamentos — sem precisar saber programar.
        </div>

        <div>
          Começar por aqui →
        </div>
      </div>
    </a>

    <a href="/pages/authentication">
      <div>
        <div>💻</div>

        <div>
          Sou desenvolvedor
        </div>

        <div>
          Quero integrar a API, configurar webhooks e usar os SDKs para automatizar cobranças no meu sistema.
        </div>

        <div>
          Ver documentação técnica →
        </div>
      </div>
    </a>
  </div>
</div>

<div>
  ## O que é a AbacatePay?

  <p>
    A AbacatePay é um gateway de pagamento que surgiu da nossa própria necessidade de simplificar cobranças. Percebemos que os meios de pagamento existentes eram excessivamente complexos — documentações confusas, processos longos de homologação e múltiplas formas de fazer a mesma coisa. Nossa solução foi uma API que transforma essa complexidade em algo simples e intuitivo:
  </p>

  ```ts theme={null}
  abacatepay.checkouts.create({
    items: [{ id: 'pro', quantity: 1 }],
  });
  ```

  <div>
    ### Princípios da API

    <div>
      <Card title="Baseada em intenção" icon="bullseye-arrow">
        Cada endpoint representa exatamente o que você lê. `POST /checkouts/create` cria um checkout. Sem ambiguidade.
      </Card>

      <Card title="Consistente" icon="check-double">
        Toda resposta segue o padrão `{data, error, success}`. Se `success` for `true`, os dados estão em `data`.
      </Card>
    </div>
  </div>
</div>

<div>
  ## O que você pode fazer

  <div>
    <Card icon="qrcode" title="Receber via Pix" href="/pages/pix/create">
      Gere um QR Code PIX para cobrar seus clientes de forma instantânea.
    </Card>

    <Card icon="credit-card" title="Criar uma assinatura" href="/pages/subscriptions/create">
      Crie um checkout de assinatura e comece a receber pagamentos recorrentes.
    </Card>

    <Card icon="money-bill" title="Checkout (Pix + Cartão)" href="/pages/payment/create">
      Use nosso checkout para receber via Pix e Cartão de Crédito.
    </Card>

    <Card icon="credit-card" title="Receber parcelado" href="/pages/payment/installments">
      Permita que seus clientes paguem em até 12x no cartão de crédito.
    </Card>

    <Card icon="money-bill-transfer" title="Realizar saques" href="/pages/payouts/create">
      Veja como realizar saques de forma segura pela API.
    </Card>

    <Card icon="tag" title="Criar cupons" href="/pages/coupons/create">
      Aprenda a criar cupons e aplicá-los em suas transações.
    </Card>

    <Card icon="shopping-basket" title="Criar produtos" href="/pages/products/create">
      Aprenda a criar e organizar produtos dentro do seu sistema via API.
    </Card>

    <Card icon="users" title="Criar clientes" href="/pages/client/create">
      Aprenda como criar clientes via API da AbacatePay.
    </Card>
  </div>

  ## Primeiros passos

  <div>
    <Card icon="key" title="Chaves de API" href="/pages/authentication">
      Consulte como gerar e gerenciar suas credenciais com segurança.
    </Card>

    <Card icon="terminal" title="Ambiente de testes" href="/pages/devmode">
      Entenda como funciona o ambiente de desenvolvimento e como você pode testar sua integração.
    </Card>

    <Card icon="bell" title="Configurar webhooks" href="/pages/webhooks">
      Aprenda a receber notificações de eventos em tempo real.
    </Card>

    <Card icon="coins" title="Produção" href="/pages/production">
      Como realizar vendas reais na AbacatePay.
    </Card>
  </div>

  <div>
    <button>
      Carregar mais
    </button>
  </div>

  <div>
    <div>
      <Card icon="boxes-stacked" title="SDKs" href="/pages/sdks/sdks">
        Veja os SDKs disponíveis para a AbacatePay.
      </Card>

      <Card icon="codepen" title="Ferramentas" href="/pages/ecosystem/ecosystem">
        Explore o nosso ecossistema de ferramentas.
      </Card>

      <Card icon="scroll" title="ChangeLog" href="/pages/changelog/index">
        Veja as últimas alterações na API da AbacatePay.
      </Card>

      <Card icon="terminal" title="CLI" href="/pages/cli/overview">
        Veja o que temos de melhor com a nossa CLI oficial.
      </Card>

      <Card icon="command" title="AI" href="/pages/ai/overview">
        Integre com as nossas ferramentas de IA facilmente, sem magia.
      </Card>
    </div>
  </div>
</div>

<div>
  ## Saiba mais sobre a AbacatePay

  <div>
    <Card icon="graduation-cap" title="AbacatePay Academy ↗" href="https://chat.abacatepay.com/academy">
      Acesse o AbacatePay Academy para aprender a usar a API da AbacatePay.
    </Card>

    <Card icon="circle-question" title="FAQ e Glossário" href="/pages/faq/index">
      Dúvidas frequentes e termos técnicos explicados.
    </Card>

    <Card icon="headset" title="Suporte ↗" href="https://www.abacatepay.com/">
      Entre em contato com o suporte da AbacatePay para ajuda com sua integração.
    </Card>
  </div>
</div>


# Obter detalhes da loja
Source: https://docs.abacatepay.com/pages/store/get

GET /stores/get
Permite que você recupere os detalhes da sua conta/loja, incluindo informações de saldo.

<Card>
  Requer a permissão `STORE:READ`.
</Card>

<Note>
  Este endpoint permite que você recupere todas as informações da sua loja, incluindo saldos disponíveis, pendentes e bloqueados.
</Note>

## Exemplo de uso

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.abacatepay.com/v2/stores/get" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.abacatepay.com/v2/stores/get', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.abacatepay.com/v2/stores/get', headers=headers)
  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $headers = [
      'Authorization: Bearer YOUR_API_KEY',
      'Content-Type: application/json'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.abacatepay.com/v2/stores/get');
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $data = json_decode($response, true);
  curl_close($ch);

  print_r($data);
  ?>
  ```
</CodeGroup>

## Resposta de sucesso

```json theme={null}
{
  "data": {
    "id": "store_abc123xyz",
    "name": "Minha Loja",
    "balance": {
      "available": 50000,
      "pending": 10000,
      "blocked": 0
    }
  },
  "success": true,
  "error": null
}
```

## Resposta de erro

```json theme={null}
{
  "success": false,
  "error": "Erro ao recuperar dados da loja.",
  "data": null
}
```

## Casos de uso

<AccordionGroup>
  <Accordion title="Verificar saldo disponível">
    Use este endpoint para verificar quanto dinheiro você tem disponível para saque antes de criar uma nova transação de saque.
  </Accordion>

  <Accordion title="Dashboard da loja">
    Ideal para exibir informações da loja em dashboards administrativos, mostrando saldos e identificação da conta.
  </Accordion>

  <Accordion title="Reconciliação de contas">
    Útil para processos de reconciliação, permitindo verificar o estado atual dos saldos da sua conta.
  </Accordion>
</AccordionGroup>

<Warning title="Autenticação obrigatória" icon="lock">
  Este endpoint requer autenticação via Bearer token. Certifique-se de incluir sua chave de API no cabeçalho Authorization.
</Warning>


# Referência
Source: https://docs.abacatepay.com/pages/store/reference

Dados da sua loja e saldos da conta

A **Loja** é sua conta na AbacatePay: dados do negócio e saldos.

## Estrutura

Exemplo de resposta da loja:

```json theme={null}
{
  "id": "store_123456",
  "name": "Minha Loja Online",
  "balance": {
    "available": 15000,
    "pending": 5000,
    "blocked": 2000
  }
}
```

## Atributos

| Atributo  | Tipo   | Descrição                                                      |
| --------- | ------ | -------------------------------------------------------------- |
| `id`      | string | ID único da loja na AbacatePay                                 |
| `name`    | string | Nome da loja ou empresa                                        |
| `balance` | object | Saldos da conta (todos em centavos; divida por 100 para reais) |

**Campos de `balance`:**

| Campo       | Tipo   | Descrição                                                            |
| ----------- | ------ | -------------------------------------------------------------------- |
| `available` | number | Saldo disponível para saque (centavos)                               |
| `pending`   | number | Saldo pendente de confirmação (centavos)                             |
| `blocked`   | number | Saldo em disputa ou análise; não disponível para saque até resolução |


# Cancelar uma assinatura
Source: https://docs.abacatepay.com/pages/subscriptions/cancel

POST /subscriptions/cancel
Cancela imediatamente uma assinatura ativa.

A assinatura passa para o status `CANCELLED` e nenhuma cobrança futura será gerada. Esta operação é irreversível.


Cancela uma assinatura ativa imediatamente. Parcelas futuras pendentes são canceladas junto.

<Card>
  Requer a permissão `SUBSCRIPTION:DELETE`.
</Card>

## Corpo da requisição

| Campo | Tipo   | Obrigatório | Descrição                     |
| ----- | ------ | ----------- | ----------------------------- |
| `id`  | string | Sim         | ID da assinatura (`subs_...`) |

**Exemplo:**

```json theme={null}
{
  "id": "subs_abc123xyz"
}
```

## Resposta

Retorna o objeto da assinatura com `status` atualizado para `CANCELLED`.

```json theme={null}
{
  "data": {
    "id": "subs_abc123xyz",
    "customerId": "cust_abc123xyz",
    "amount": 2990,
    "status": "CANCELLED",
    "method": "CARD",
    "coupons": [],
    "devMode": false,
    "trialDays": null,
    "trialEndsAt": null,
    "createdAt": "2024-12-06T20:00:00.000Z",
    "updatedAt": "2024-12-06T20:00:05.000Z"
  },
  "success": true,
  "error": null
}
```

<Warning title="Cancelamento imediato">
  O cancelamento é aplicado na hora (`cancelPolicy: NOW`). Não há período de carência — o cliente perde o acesso imediatamente.
</Warning>


# Alterar plano da assinatura
Source: https://docs.abacatepay.com/pages/subscriptions/change-plan

POST /subscriptions/change-plan
Altera o produto principal de uma assinatura ativa.

A mudança é agendada como `PENDING` e aplicada automaticamente no início do próximo ciclo de cobrança. Só pode existir uma alteração pendente por assinatura — uma nova chamada substitui a anterior ainda não aplicada.

O produto informado em `productId` deve ter um ciclo de cobrança definido. Produtos avulsos (sem ciclo) retornam erro.


Altera o produto principal de uma assinatura ativa. O novo valor começa a ser cobrado no próximo ciclo de cobrança — o ciclo atual não é afetado.

<Card>
  Requer a permissão `SUBSCRIPTION:CREATE`.
</Card>

## Corpo da requisição

| Campo       | Tipo    | Obrigatório | Descrição                                                 |
| ----------- | ------- | ----------- | --------------------------------------------------------- |
| `id`        | string  | Sim         | ID da assinatura (`subs_...`)                             |
| `productId` | string  | Sim         | ID do novo produto (`prod_...`) — deve ter ciclo definido |
| `quantity`  | integer | Sim         | Quantidade do produto (mínimo `1`)                        |

<Note>
  O produto informado em `productId` precisa ter um `cycle` configurado (`WEEKLY`, `MONTHLY`, `SEMIANNUALLY` ou `ANNUALLY`). Produtos avulsos (sem ciclo) retornam erro.
</Note>

**Exemplo — upgrade de plano:**

```json theme={null}
{
  "id": "subs_abc123xyz",
  "productId": "prod_plano_pro",
  "quantity": 1
}
```

## Resposta

Retorna um objeto de atualização pendente (`status: "PENDING"`). A mudança é aplicada automaticamente no início do próximo ciclo.

```json theme={null}
{
  "data": {
    "id": "subu_abc123xyz",
    "subscriptionId": "subs_abc123xyz",
    "status": "PENDING",
    "productId": "prod_plano_pro",
    "quantity": 1,
    "newAmount": 4990,
    "requestedAt": "2024-12-06T20:05:00.000Z"
  },
  "success": true,
  "error": null
}
```

| Campo            | Tipo    | Descrição                                              |
| ---------------- | ------- | ------------------------------------------------------ |
| `id`             | string  | ID da atualização pendente (`subu_...`)                |
| `subscriptionId` | string  | ID da assinatura                                       |
| `status`         | string  | `PENDING` até o próximo ciclo; `APPLIED` após aplicado |
| `productId`      | string  | ID do novo produto                                     |
| `quantity`       | integer | Quantidade do produto                                  |
| `newAmount`      | integer | Novo valor em centavos (`preço × quantidade`)          |
| `requestedAt`    | string  | Data/hora da solicitação                               |

<Tip title="Webhook subscription.plan_changed">
  Um evento `subscription.plan_changed` é disparado imediatamente após a solicitação, com os detalhes do novo plano e o ID da atualização pendente.
</Tip>

<Warning title="Uma alteração por vez">
  Só pode existir uma atualização `PENDING` por assinatura. Chamar o endpoint novamente sobrescreve a alteração anterior ainda não aplicada.
</Warning>


# Criar Checkout de assinatura
Source: https://docs.abacatepay.com/pages/subscriptions/create

POST /subscriptions/create
Cria um Checkout de assinatura — uma página de pagamento igual ao Checkout comum, mas para cobrança recorrente.

Aceita os mesmos parâmetros do Checkout (`returnUrl`, `completionUrl`, `customerId`, `externalId`, `metadata`, `coupons`, `methods`). O Checkout de assinatura aceita **apenas um produto**; o ciclo (frequência) já deve estar definido no produto ao criá-lo na loja — não é enviado no checkout.


Cria um checkout de assinatura. O cliente paga uma vez e entra no ciclo de cobranças recorrentes do produto.

<Card title="Pré-requisito">
  O produto referenciado em `items` deve ter um `cycle` definido (`WEEKLY`, `MONTHLY`, `SEMIANNUALLY` ou `ANNUALLY`). Produtos avulsos retornam erro.
</Card>

**Exemplo:**

```json theme={null}
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "customerId": "cust_abc123xyz",
  "externalId": "subs-123",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["CARD"],
  "retryPolicy": {
    "maxRetry": 3,
    "retryEvery": 2
  }
}
```

<Tip title="Use a url retornada">
  Redirecione o cliente para `data.url` para concluir o primeiro pagamento e ativar a assinatura.
</Tip>

<Note>
  Assinaturas aceitam apenas **um produto por checkout**. O método padrão é `CARD`.
</Note>

<Note title="Período de teste gratuito">
  Se o produto referenciado tiver `trialDays` configurado, o checkout cobra **R\$ 0,00** — apenas tokeniza o cartão. A primeira cobrança pelo valor integral ocorre automaticamente ao final do trial. Consulte a [referência de assinaturas](/pages/subscriptions/reference#período-de-teste-gratuito-free-trial) para mais detalhes.
</Note>


# Listar Checkouts de assinatura
Source: https://docs.abacatepay.com/pages/subscriptions/list

GET /subscriptions/list
Retorna todos os Checkouts de assinatura que você criou, com suporte a paginação baseada em cursor.
Cada item possui o mesmo formato de um Checkout: `id`, `url`, `amount`, `items`, `status`, etc.


Retorna todos os checkouts de assinatura da sua loja.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Checkout de assinatura](/pages/subscriptions/create), incluindo `status`, `url`, `amount` e `items`.

**Valores de `status`:**

| Valor       | Significado                     |
| ----------- | ------------------------------- |
| `PENDING`   | Aguardando o primeiro pagamento |
| `PAID`      | Assinatura ativa                |
| `EXPIRED`   | Expirado sem pagamento          |
| `CANCELLED` | Cancelado                       |
| `REFUNDED`  | Reembolsado                     |


# Registrar uso
Source: https://docs.abacatepay.com/pages/subscriptions/record-usage

POST /subscriptions/record-usage
Registra unidades de uso de um produto avulso (pay-as-you-go) em uma assinatura ativa.

O registro é vinculado à próxima parcela pendente da assinatura e incluído na cobrança do ciclo atual. Use `action: "add"` para acrescentar unidades e `action: "subtract"` para estornar unidades já registradas.

O produto informado em `productId` **não** deve ter ciclo de cobrança. Produtos de assinatura (com ciclo) retornam erro.


Registra unidades de uso de um produto avulso (pay-as-you-go) em uma assinatura ativa. O valor correspondente é incluído na próxima cobrança do ciclo.

<Card>
  Requer a permissão `SUBSCRIPTION:CREATE`.
</Card>

## Como funciona

Diferente do produto principal da assinatura (que tem ciclo fixo), produtos de uso são cobrados de acordo com o consumo real registrado via este endpoint. Cada registro é vinculado à próxima parcela pendente da assinatura.

Use `action: "add"` para adicionar unidades e `action: "subtract"` para estornar unidades já registradas no mesmo ciclo.

## Corpo da requisição

| Campo       | Tipo    | Obrigatório | Descrição                                                    |
| ----------- | ------- | ----------- | ------------------------------------------------------------ |
| `id`        | string  | Sim         | ID da assinatura (`subs_...`)                                |
| `productId` | string  | Sim         | ID do produto de uso (`prod_...`) — **não** deve ter ciclo   |
| `units`     | integer | Sim         | Quantidade de unidades (mínimo `1`)                          |
| `action`    | string  | Sim         | `"add"` para adicionar ou `"subtract"` para remover unidades |

<Note>
  O produto em `productId` deve ser um produto **sem ciclo** (`cycle: null`). Produtos de assinatura (com ciclo) retornam erro.
</Note>

**Exemplo — adicionar 50 unidades de API calls:**

```json theme={null}
{
  "id": "subs_abc123xyz",
  "productId": "prod_api_calls",
  "units": 50,
  "action": "add"
}
```

**Exemplo — estornar 10 unidades:**

```json theme={null}
{
  "id": "subs_abc123xyz",
  "productId": "prod_api_calls",
  "units": 10,
  "action": "subtract"
}
```

## Resposta

Retorna o registro de uso criado, já vinculado à próxima parcela do ciclo (`installmentNumber`).

```json theme={null}
{
  "data": {
    "id": "usgr_abc123xyz",
    "subscriptionId": "subs_abc123xyz",
    "productId": "prod_api_calls",
    "units": 50,
    "unitPrice": 100,
    "action": "add",
    "installmentNumber": 2,
    "recordedAt": "2024-12-06T20:10:00.000Z"
  },
  "success": true,
  "error": null
}
```

| Campo               | Tipo    | Descrição                                         |
| ------------------- | ------- | ------------------------------------------------- |
| `id`                | string  | ID do registro de uso (`usgr_...`)                |
| `subscriptionId`    | string  | ID da assinatura                                  |
| `productId`         | string  | ID do produto                                     |
| `units`             | integer | Quantidade de unidades registradas                |
| `unitPrice`         | integer | Preço unitário em centavos no momento do registro |
| `action`            | string  | `"add"` ou `"subtract"`                           |
| `installmentNumber` | integer | Número da parcela onde este uso será cobrado      |
| `recordedAt`        | string  | Data/hora do registro                             |

<Tip title="Cobrança automática">
  O valor total cobrado na próxima parcela inclui todos os registros de uso com `action: "add"` menos os com `action: "subtract"` do mesmo ciclo: `Σ(add × unitPrice) − Σ(subtract × unitPrice)`.
</Tip>


# Referência
Source: https://docs.abacatepay.com/pages/subscriptions/reference

Crie checkouts de assinatura e gerencie as existentes.

## Modelo mental

Uma assinatura na AbacatePay tem três fases distintas:

```
Checkout (cliente paga) → Assinatura ACTIVE → Cobranças automáticas a cada ciclo
```

O `POST /subscriptions/create` **não cria uma assinatura diretamente** — ele cria um checkout de assinatura. A assinatura em si (com `id: subs_...`) só existe após o cliente concluir o pagamento. Esse detalhe muda como você lida com os webhooks: ouça `subscription.completed` para confirmar que a assinatura está ativa, não apenas que o checkout foi criado.

<CardGroup>
  <Card title="Criar checkout" href="/pages/subscriptions/create" icon="plus">
    Inicia o fluxo de assinatura.
  </Card>

  <Card title="Cancelar" href="/pages/subscriptions/cancel" icon="xmark">
    Cancela imediatamente, sem cobranças futuras.
  </Card>

  <Card title="Alterar plano" href="/pages/subscriptions/change-plan" icon="arrows-rotate">
    Muda o produto; novo valor no próximo ciclo.
  </Card>
</CardGroup>

***

Toda assinatura antes de ser iniciada, o seu cliente deve passar pelo [Checkout](/pages/payment/reference).

A diferença é que um checkout de assinatura aceita **só um produto**, e esse produto precisa ter **ciclo (frequency)** definido na loja.

Quando o pagamento é realizado, a assinatura se torna ativa.

## Parâmetros

O `POST /subscriptions/create` usa os mesmos parâmetros do Checkout:

| Parâmetro       | Obrigatório | Descrição                                                                                                    |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `items`         | Sim         | Lista com **exatamente um** item (`id` e `quantity`); o produto deve ter sido criado com ciclo de assinatura |
| `customerId`    | Não         | ID do cliente já cadastrado                                                                                  |
| `externalId`    | Não         | ID da assinatura no seu sistema                                                                              |
| `returnUrl`     | Não         | URL de retorno ao clicar em "Voltar"                                                                         |
| `completionUrl` | Não         | URL após pagamento concluído                                                                                 |
| `metadata`      | Não         | Metadados livres                                                                                             |
| `coupons`       | Não         | Lista de cupons                                                                                              |
| `methods`       | Não         | Lista de métodos (`PIX`, `CARD`). Padrão: `["CARD"]` para assinaturas                                        |
| `retryPolicy`   | Não         | Política de retentativa em caso de falha de cobrança (veja abaixo)                                           |

### retryPolicy

Controla o comportamento automático de retentativas quando uma cobrança do ciclo falha (ex.: cartão sem saldo). Se não informado, os padrões são aplicados.

| Campo        | Tipo    | Padrão | Min | Max  | Descrição                                                                              |
| ------------ | ------- | ------ | --- | ---- | -------------------------------------------------------------------------------------- |
| `maxRetry`   | integer | `3`    | `1` | `10` | Número máximo de tentativas de cobrança antes do cancelamento automático da assinatura |
| `retryEvery` | integer | `1`    | `1` | `30` | Dias entre cada tentativa                                                              |

Após esgotar todas as tentativas sem sucesso, a assinatura é automaticamente cancelada com `cancelledDueTo: "max_payment_retries_exceeded"` e o evento `subscription.cancelled` é disparado.

Exemplo (cada item só precisa de `id` e `quantity`; o ciclo vem do produto):

```json theme={null}
{
  "items": [
    {
      "id": "prod-1234",
      "quantity": 1
    }
  ],
  "customerId": "cust_abc123xyz",
  "externalId": "subs-123",
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["CARD"],
  "retryPolicy": {
    "maxRetry": 5,
    "retryEvery": 3
  }
}
```

## Resposta

Create e list retornam o mesmo formato do Checkout (`id`, `url`, `amount`, `items`, `status`, etc.).

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "bill_abc123xyz",
    "externalId": "subs-123",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "paidAmount": null,
    "items": [
      {
        "id": "prod_456",
        "quantity": 1
      }
    ],
    "status": "PENDING",
    "coupons": [],
    "devMode": false,
    "customerId": "cust_abc123xyz",
    "returnUrl": "https://seusite.com/voltar",
    "completionUrl": "https://seusite.com/sucesso",
    "receiptUrl": null,
    "metadata": {},
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

<Tip title="Redirecione o cliente" icon="book">
  Use a `url` retornada para levar o cliente ao checkout e concluir o pagamento.
</Tip>

### Objeto de assinatura ativa

Após ativação, os endpoints de assinatura (`GET /subscriptions/get`, `GET /subscriptions/list`) retornam o objeto completo incluindo `retryPolicy`:

```json theme={null}
{
  "data": {
    "id": "subs_abc123xyz",
    "customerId": "cust_abc123xyz",
    "amount": 10000,
    "status": "ACTIVE",
    "method": "CARD",
    "coupons": [],
    "devMode": false,
    "trialDays": null,
    "trialEndsAt": null,
    "retryPolicy": {
      "maxRetry": 5,
      "retryEvery": 3
    },
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

| Campo                    | Tipo    | Descrição                                           |
| ------------------------ | ------- | --------------------------------------------------- |
| `retryPolicy.maxRetry`   | integer | Tentativas máximas antes do cancelamento automático |
| `retryPolicy.retryEvery` | integer | Dias entre cada tentativa                           |

## Ciclo de cobrança

Definido no produto ao criar na loja. Valores: **WEEKLY**, **MONTHLY**, **SEMIANNUALLY**, **ANNUALLY**.

## Status

Mesmos do Checkout: **PENDING**, **EXPIRED**, **CANCELLED**, **PAID**, **REFUNDED**.

## Período de teste gratuito (Free Trial)

Configure um período de teste no produto com o campo `trialDays` ao [criar o produto](/pages/products/create). Durante o trial, o cliente não é cobrado — a primeira cobrança ocorre somente ao final do período.

### Como funciona

1. **Criação do produto**: defina `trialDays` (inteiro de 1 a 90) junto com `cycle`.
2. **Checkout**: o cliente insere o cartão normalmente, mas o valor cobrado é **R\$ 0,00**. O cartão é apenas tokenizado para uso futuro.
3. **Assinatura ativa imediatamente**: a assinatura é criada com `status: ACTIVE` e os campos `trialDays` e `trialEndsAt` preenchidos.
4. **Fim do trial**: na data `trialEndsAt`, a primeira cobrança pelo valor integral é processada automaticamente.
5. **Renovações**: seguem o ciclo normal do produto a partir do fim do trial.

### Exemplo de produto com trial

```json theme={null}
POST /products/create
{
  "externalId": "plano-pro-trial",
  "name": "Plano Pro — 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7
}
```

### Objeto da assinatura com trial

Após a ativação, a assinatura expõe `trialDays` e `trialEndsAt`:

```json theme={null}
{
  "data": {
    "id": "subs_abc123xyz",
    "customerId": "cust_abc123xyz",
    "amount": 4990,
    "status": "ACTIVE",
    "method": "CARD",
    "coupons": [],
    "devMode": false,
    "trialDays": 7,
    "trialEndsAt": "2024-11-11T23:59:59.999Z",
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}
```

| Campo         | Tipo            | Descrição                                                               |
| ------------- | --------------- | ----------------------------------------------------------------------- |
| `trialDays`   | integer \| null | Duração do período de teste em dias; `null` se não houver trial         |
| `trialEndsAt` | string \| null  | Data/hora (ISO 8601) em que o trial termina; `null` se não houver trial |

### Webhook de início de trial

Quando uma assinatura com trial é criada, o evento `subscription.trial_started` é disparado:

```json theme={null}
{
  "event": "subscription.trial_started",
  "apiVersion": 2,
  "data": {
    "subscription": {
      "id": "subs_abc123xyz",
      "amount": 4990,
      "status": "ACTIVE",
      "method": "CARD",
      "trialDays": 7,
      "trialEndsAt": "2024-11-11T23:59:59.999Z",
      "createdAt": "2024-11-04T18:38:28.573Z"
    }
  }
}
```

### Cancelamento durante o trial

Cancelar uma assinatura em período de trial tem o mesmo comportamento que cancelar uma assinatura normal: o cancelamento é imediato e nenhuma cobrança futura é processada. Veja [Cancelar assinatura](/pages/subscriptions/cancel).

## Gerenciando assinaturas ativas

Após uma assinatura ser criada e ativada, você pode gerenciá-la com os seguintes endpoints:

| Endpoint                                           | Descrição                                                                            |
| -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [Cancelar](/pages/subscriptions/cancel)            | Cancela a assinatura imediatamente e interrompe cobranças futuras                    |
| [Alterar plano](/pages/subscriptions/change-plan)  | Troca o produto principal; novo valor começa no próximo ciclo                        |
| [Registrar uso](/pages/subscriptions/record-usage) | Adiciona ou remove unidades de produtos pay-as-you-go para cobrança no próximo ciclo |

### Produtos de uso (pay-as-you-go)

Além do produto principal (com ciclo), uma assinatura pode acumular cobranças variáveis via [Registrar uso](/pages/subscriptions/record-usage). O produto referenciado precisa ser um produto **sem ciclo** — ele representa um item cobrado por unidade consumida (ex: chamadas de API, SMS, créditos).

## Segurança

* Requisições autenticadas via Bearer Token
* Abusos podem levar à suspensão da conta conforme os [termos de uso](https://abacatepay.com/termos)


# Criar cobrança Boleto
Source: https://docs.abacatepay.com/pages/transparents/boleto

POST /transparents/create
Cria um checkout transparente. Use `"method": "PIX"` para gerar um QR Code ou `"method": "BOLETO"` para emitir um boleto com PIX alternativo incluído.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Cria um checkout transparente via **Boleto**. A API devolve a linha digitável (`barCode`), uma URL para visualização e impressão do boleto (`url`), e o PIX alternativo (`brCode`/`brCodeBase64`) para a mesma cobrança — tudo em uma única chamada.

<Note>
  Para cobrar via PIX, veja [Criar cobrança PIX](/pages/transparents/create).
</Note>

***

## Campos obrigatórios

| Campo                 | Tipo     | Descrição                                    |
| --------------------- | -------- | -------------------------------------------- |
| `method`              | `string` | Deve ser `"BOLETO"`                          |
| `data.amount`         | `number` | Valor em centavos (ex: `25000` = R\$ 250,00) |
| `data.customer.name`  | `string` | Nome completo do pagador                     |
| `data.customer.taxId` | `string` | CPF ou CNPJ do pagador                       |

### `data.dueDate` — vencimento (opcional)

Data de vencimento do boleto no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Se omitido, o vencimento padrão é de **3 dias úteis**.

| Campo     | Tipo     | Descrição                                    |
| --------- | -------- | -------------------------------------------- |
| `dueDate` | `string` | Data de vencimento (`YYYY-MM-DD`). Opcional. |

**Regras:**

* Não pode ser data no passado
* Máximo de 365 dias no futuro

`dueDate` é a data enviada ao provedor. A resposta continua expondo `expiresAt` (ISO datetime no fim do dia do `dueDate`). Sem juros/multa, após o vencimento o boleto expira (`EXPIRED`) via webhook `PAYMENT_OVERDUE`. Com juros/multa, pode permanecer aberto para pagamento em atraso.

### `data.utm` — campanha / UTM (opcional)

No **`BoletoTransparentData`** (corpo `data` com `method: "BOLETO"`), você pode incluir o mesmo bloco opcional `utm`: objeto opcional com campos opcionais `source`, `medium`, `campaign`, `term` e `content` (`string`). Valores enviados podem ser vistos no **dashboard** e **não mudam** o fluxo da cobrança.

***

## Exemplos mínimos (BOLETO)

Sem `dueDate` (vencimento padrão de 3 dias úteis):

```json theme={null}
{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00"
    }
  }
}
```

Com `dueDate`:

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

Com `utm`:

```json theme={null}
{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00"
    },
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "boleto_teste"
    }
  }
}
```

***

## Requisição

```json theme={null}
{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "dueDate": "2026-08-15",
    "description": "Fatura de serviço mensal",
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00",
      "email": "mariana.costa@empresa.com.br",
      "cellphone": "(21) 99876-5432"
    },
    "metadata": {
      "faturaId": "fatura-456",
      "plano": "pro"
    }
  }
}
```

***

## Multa e juros por atraso

Você pode configurar **juros** (`data.interest`) e **multa** (`data.fine`) que serão aplicados se o cliente pagar após a data de vencimento. Ambos os campos são opcionais e independentes — pode-se enviar só `interest`, só `fine`, ambos ou nenhum. Eles só têm efeito quando `method: "BOLETO"` e são ignorados nos demais métodos.

### `data.interest` — juros por atraso / late interest

| Campo   | Tipo          | Descrição                                                                                                                                 |
| ------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `integer ≥ 0` | Percentual de juros **ao mês**, em centésimos de percentual. `100` = 1% ao mês, `250` = 2,5% ao mês. Quando `0` ou omitido, não há juros. |

Os juros seguem o padrão **percentual ao mês, calculados pro rata die** após o vencimento.

> **EN:** `data.interest.value` is an integer in hundredths of a percent representing the **monthly** late interest rate (`100` = 1%/month). It accrues pro rata die after the due date. Omit or use `0` to disable.

### `data.fine` — multa por atraso / late fine

| Campo   | Tipo                        | Descrição                                                                                                                                                                   |
| ------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | `integer ≥ 0`               | Quando `type = "PERCENTAGE"`: centésimos de percentual (`200` = 2%). Quando `type = "FIXED"`: valor em **centavos** (`1000` = R\$ 10,00). Quando `0` ou omitido, sem multa. |
| `type`  | `"PERCENTAGE"` \| `"FIXED"` | `PERCENTAGE` aplica percentual sobre o valor do boleto. `FIXED` aplica um valor fixo em centavos.                                                                           |

A multa é uma **cobrança única** aplicada uma vez após o vencimento.

> **EN:** `data.fine` is a one-time charge added after the due date. With `type: "PERCENTAGE"`, `value` is in hundredths of a percent. With `type: "FIXED"`, `value` is in cents.

**Exemplo — juros de 1% ao mês + multa fixa de R\$ 10,00:**

```json theme={null}
{
  "method": "BOLETO",
  "data": {
    "amount": 5000,
    "dueDate": "2026-08-15",
    "customer": {
      "name": "João Silva",
      "taxId": "123.456.789-00"
    },
    "interest": { "value": 100 },
    "fine": { "value": 1000, "type": "FIXED" }
  }
}
```

**Exemplo — multa percentual de 2%:**

```json theme={null}
{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00"
    },
    "fine": { "value": 200, "type": "PERCENTAGE" }
  }
}
```

<Note>
  **Unidades / units:** `interest.value` e `fine.value` (com `type = "PERCENTAGE"`) estão em centésimos de percentual — `100` = 1%. `fine.value` (com `type = "FIXED"`) e `amount` estão em centavos — `1000` = R\$ 10,00.
</Note>

***

## Resposta

Os mesmos objetos `interest` e `fine` constam na resposta de `POST /transparents/create`, `GET /transparents/get` e `GET /transparents/list` (dentro do payload do boleto), ou ficam `null` quando nenhum dos campos foi configurado. O campo `expiresAt` é o datetime ISO no fim do dia do `dueDate` (ou do vencimento padrão de 3 dias úteis).

```json theme={null}
{
  "data": {
    "id": "bole_k8pqr2mnvx",
    "amount": 25000,
    "status": "PENDING",
    "devMode": false,
    "barCode": "23793.38128 60007.827263 37000.963779 4 10010000025000",
    "url": "https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto",
    "brCode": "00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Mariana Costa6009SAO PAULO62070503***6304F1C2",
    "brCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "platformFee": 250,
    "interest": { "value": 100 },
    "fine": { "value": 1000, "type": "FIXED" },
    "receiptUrl": null,
    "expiresAt": "2026-08-16T02:59:59.999Z",
    "createdAt": "2026-07-27T14:22:10.381Z",
    "updatedAt": "2026-07-27T14:22:10.381Z",
    "metadata": {
      "faturaId": "fatura-456",
      "plano": "pro"
    }
  },
  "success": true,
  "error": null
}
```

<Tip>
  Abra `url` para exibir o boleto para impressão. Use `barCode` para o cliente digitar a linha digitável no app do banco. Use `brCode`/`brCodeBase64` para oferecer PIX como alternativa sem nenhum esforço adicional.
</Tip>


# Checar Status
Source: https://docs.abacatepay.com/pages/transparents/check

GET /transparents/check
Checar status do pagamento do QRCode Pix.

Verifica o status atual de um checkout transparente pelo seu `id`.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Use este endpoint para confirmar se o cliente já realizou o pagamento do QR Code. O campo `status` indica o estado atual:

| Valor       | Significado                    |
| ----------- | ------------------------------ |
| `PENDING`   | Aguardando pagamento           |
| `PAID`      | PIX recebido com sucesso       |
| `EXPIRED`   | QR Code expirado sem pagamento |
| `CANCELLED` | Cancelado                      |

<Tip title="Polling ou webhook?">
  Prefira [webhooks](/pages/webhooks) a fazer polling — você recebe a confirmação em tempo real sem precisar consultar repetidamente.
</Tip>


# Criar cobrança PIX
Source: https://docs.abacatepay.com/pages/transparents/create

POST /transparents/create
Cria um checkout transparente. Use `"method": "PIX"` para gerar um QR Code ou `"method": "BOLETO"` para emitir um boleto com PIX alternativo incluído.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Cria um checkout transparente via **PIX**. A API devolve o QR Code em imagem (`brCodeBase64`) e o código copia e cola (`brCode`) — o cliente nunca sai do seu site.

<Note>
  Para cobrar via Boleto, veja [Criar cobrança Boleto](/pages/transparents/boleto).
</Note>

***

## Campos obrigatórios

| Campo         | Tipo     | Descrição                                    |
| ------------- | -------- | -------------------------------------------- |
| `method`      | `string` | Deve ser `"PIX"`                             |
| `data.amount` | `number` | Valor em centavos (ex: `10000` = R\$ 100,00) |

Todos os outros campos são opcionais mas recomendados para melhor rastreabilidade.

### `data.utm` — campanha / UTM (opcional)

No corpo `data` com **`method`: `"PIX"`**, o objeto `utm` usa o mesmo esquema do **PIX QR Code v1 (`PixQrCodeV1`)**: objeto opcional; cada campo interno também é opcional (`string`).

| Campo          | Tipo     | Descrição |
| -------------- | -------- | --------- |
| `utm.source`   | `string` | Opcional  |
| `utm.medium`   | `string` | Opcional  |
| `utm.campaign` | `string` | Opcional  |
| `utm.term`     | `string` | Opcional  |
| `utm.content`  | `string` | Opcional  |

Quando enviados, podem ser **consultados no dashboard**. Não alteram valores, vencimento nem status da cobrança.

***

## Exemplos mínimos (PIX)

Sem `utm`:

```json theme={null}
{
  "method": "PIX",
  "data": {
    "amount": 10000
  }
}
```

Com `utm`:

```json theme={null}
{
  "method": "PIX",
  "data": {
    "amount": 10000,
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "lancamento_q1",
      "term": "pix",
      "content": "cta_hero"
    }
  }
}
```

***

## Requisição

```json theme={null}
{
  "method": "PIX",
  "data": {
    "amount": 10000,
    "description": "Cobrança PIX no checkout transparente",
    "expiresIn": 3600,
    "customer": {
      "name": "Daniel Lima",
      "email": "daniel_lima@abacatepay.com",
      "taxId": "123.456.789-01",
      "cellphone": "(11) 4002-8922"
    },
    "metadata": {
      "pedidoId": "pedido-123"
    }
  }
}
```

***

## Resposta

```json theme={null}
{
  "data": {
    "id": "pix_char_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "devMode": false,
    "brCode": "00020160014BR.GOV.BCB.PIX070503***6304ABCD",
    "brCodeBase64": "data:image/png;base64,iVBORw0KG...",
    "platformFee": 100,
    "receiptUrl": null,
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z",
    "expiresAt": "2024-11-04T19:38:28.573Z",
    "metadata": {
      "pedidoId": "pedido-123"
    }
  },
  "success": true,
  "error": null
}
```

<Tip>
  Use `brCodeBase64` para renderizar a imagem do QR Code diretamente na sua página. Use `brCode` (copia e cola) para enviar por WhatsApp, Telegram ou e-mail.
</Tip>


# Listar Checkouts Transparentes
Source: https://docs.abacatepay.com/pages/transparents/list

GET /transparents/list
Retorna todos os Checkouts Transparentes (QRCodes PIX) que você criou.

Você pode usar essa rota para listar todos os seus checkouts transparentes e visualizar seus status, valores e informações relacionadas.


Retorna todos os checkouts transparentes (PIX QR Code) da sua loja.

<Card>
  Requer a permissão `CHECKOUT:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar QRCode PIX](/pages/transparents/create), incluindo `status`, `brCode`, `amount` e `expiresAt`.


# Referência
Source: https://docs.abacatepay.com/pages/transparents/reference

PIX QR Code e Boleto no seu checkout sem redirecionar o cliente

O **checkout transparente** permite receber pagamentos diretamente no seu site ou app — sem redirecionar o cliente para outra página. Suporta **PIX** e **Boleto**.

## Métodos disponíveis

| `method` | Descrição                                            |
| -------- | ---------------------------------------------------- |
| `PIX`    | Gera um QR Code e código copia e cola instantâneos   |
| `BOLETO` | Gera um boleto bancário com PIX alternativo incluído |

Todos os métodos usam o mesmo endpoint: `POST /v2/transparents/create`.

## Parâmetros UTM (`data.utm`)

Objeto opcional em `data` para **`PIX`** e **`BOLETO`**:

| Campo          | Tipo     | Descrição          |
| -------------- | -------- | ------------------ |
| `utm`          | objeto   | Opcional em `data` |
| `utm.source`   | `string` | Opcional           |
| `utm.medium`   | `string` | Opcional           |
| `utm.campaign` | `string` | Opcional           |
| `utm.term`     | `string` | Opcional           |
| `utm.content`  | `string` | Opcional           |

Quando há valores enviados, podem ser **vistos no dashboard**. Metadados de campanha — **não** mudam valores, datas ou regras de cobrança.

Exemplos completos para copiar e colar: [Criar cobrança PIX](/pages/transparents/create) e [Criar cobrança Boleto](/pages/transparents/boleto).

***

## Receber via PIX

Use `POST /v2/transparents/create`. A API devolve o QR Code em imagem (`brCodeBase64`) e o código copia e cola (`brCode`).

<Card title="Campos obrigatórios">
  Só `data.amount` é obrigatório (valor em centavos). Envie `method: "PIX"`.
</Card>

**Exemplo de requisição:**

```json theme={null}
POST /v2/transparents/create
{
  "method": "PIX",
  "data": {
    "amount": 10000,
    "description": "Cobrança PIX no checkout transparente",
    "expiresIn": 3600,
    "customer": {
      "name": "Daniel Lima",
      "email": "daniel_lima@abacatepay.com",
      "taxId": "123.456.789-01",
      "cellphone": "(11) 4002-8922"
    },
    "metadata": {
      "pedidoId": "pedido-123"
    }
  }
}
```

**Exemplo de resposta:**

```json theme={null}
{
  "data": {
    "id": "pix_char_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "devMode": false,
    "brCode": "00020160014BR.GOV.BCB.PIX070503***6304ABCD",
    "brCodeBase64": "data:image/png;base64,iVBORw0KG...",
    "platformFee": 100,
    "receiptUrl": null,
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z",
    "expiresAt": "2024-11-04T19:38:28.573Z",
    "metadata": {
      "pedidoId": "pedido-123"
    }
  },
  "success": true,
  "error": null
}
```

<Tip title="Usando a resposta">
  Use `brCodeBase64` para exibir a imagem do QR Code ou `brCode` (copia e cola) para enviar por WhatsApp/Telegram ou
  integrar no seu checkout.
</Tip>

***

## Receber via Boleto

Use `POST /v2/transparents/create` com `method: "BOLETO"`. A API devolve a linha digitável (`barCode`), uma URL para visualização e impressão do boleto (`url`), e um código PIX alternativo para a mesma cobrança.

<Card title="Campos obrigatórios">
  `data.amount` e `data.customer` (com `name` e `taxId`) são obrigatórios para boleto.
</Card>

Use `data.dueDate` (`YYYY-MM-DD`) para definir a data de vencimento. Se omitido, o padrão é **3 dias úteis**. Não pode ser data no passado; máximo de 365 dias no futuro. A resposta expõe `expiresAt` (ISO datetime no fim do dia do `dueDate`).

**Exemplo de requisição:**

```json theme={null}
POST /v2/transparents/create
{
  "method": "BOLETO",
  "data": {
    "amount": 5000,
    "dueDate": "2026-08-15",
    "description": "Fatura de serviço mensal",
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00",
      "email": "mariana.costa@empresa.com.br",
      "cellphone": "(21) 99876-5432"
    },
    "metadata": {
      "faturaId": "fatura-456",
      "plano": "pro"
    }
  }
}
```

**Exemplo de resposta:**

```json theme={null}
{
  "data": {
    "id": "bole_k8pqr2mnvx",
    "amount": 5000,
    "status": "PENDING",
    "devMode": false,
    "barCode": "23793.38128 60007.827263 37000.963779 4 10010000005000",
    "url": "https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto",
    "pix": {
      "brCode": "00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Mariana Costa6009SAO PAULO62070503***6304F1C2",
      "brCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "platformFee": 250,
    "receiptUrl": null,
    "expiresAt": "2026-08-16T02:59:59.999Z",
    "createdAt": "2026-07-27T14:22:10.381Z",
    "updatedAt": "2026-07-27T14:22:10.381Z",
    "metadata": {
      "faturaId": "fatura-456",
      "plano": "pro"
    }
  },
  "success": true,
  "error": null
}
```

<Tip title="Usando a resposta">
  Abra `url` para exibir o boleto para impressão. Use `barCode` para o cliente digitar a linha digitável no app do
  banco. O objeto `pix` permite oferecer PIX como alternativa sem nenhum esforço adicional.
</Tip>

***

## Ideias de uso

* **PIX no checkout próprio:** exiba o QR Code na sua página e mantenha o cliente no seu site.
* **Boleto por e-mail:** envie `url` ou `barCode` por e-mail ou WhatsApp.
* **Boleto + PIX:** ofereça os dois métodos na mesma tela — o cliente escolhe como pagar.


# Reembolsar Checkout Transparente
Source: https://docs.abacatepay.com/pages/transparents/refund

POST /transparents/refund
Reembolsa integralmente um pagamento transparente (PIX ou Cartão). O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados.


Reembolsa integralmente um pagamento transparente (PIX QR Code ou Cartão). O valor reembolsado é igual ao valor original da transação — não há reembolso parcial.

<Card title="Obrigatório">
  Apenas `id` é obrigatório — o ID público do recurso a reembolsar.
</Card>

O campo `id` aceita:

| Prefixo        | Recurso                                 |
| -------------- | --------------------------------------- |
| `pix_char_...` | ID público da cobrança PIX transparente |
| `card_...`     | ID público da cobrança no cartão        |
| `char_...`     | ID público do payment intent (genérico) |

**Exemplo mínimo:**

```json theme={null}
{
  "id": "pix_char_abc123xyz"
}
```

**Exemplo com motivo:**

```json theme={null}
{
  "id": "pix_char_abc123xyz",
  "reason": "Cliente pagou em duplicidade."
}
```

**Resposta:**

```json theme={null}
{
  "data": { "refundPublicId": "tran_refund789xyz" },
  "success": true,
  "error": null
}
```

<Tip title="Idempotência">
  Chamar o endpoint para o mesmo `id` retorna sempre o mesmo `refundPublicId` — não cria reembolsos duplicados.
</Tip>

***

## Regras de negócio

* **Reembolso total apenas** — o valor é sempre igual ao valor original da transação.
* **Métodos suportados** — `PIX`, `PIX_QRCODE` e `CARD`. Boletos transparentes não são reembolsáveis via API.
* **Estado exigido:**
  * `PIX` / `PIX_QRCODE` — transação precisa estar `COMPLETE`.
  * `CARD` — transação precisa estar `APPROVED` ou `COMPLETE`.
* **Disputas** — transações em disputa (`UNDER_DISPUTE` ou `metadata.underDispute=true`) não podem ser reembolsadas por este endpoint.
* **Saldo** — o valor é debitado do saldo `available` da loja (ou `pending`, em casos específicos de `CARD`). Sem saldo, retorna `INSUFFICIENT_FUNDS`.
* **Modo dev (sandbox)** — em `devMode` o reembolso é confirmado instantaneamente, sem chamar o provider real.
* **Status final após o reembolso:**
  * A transação original vira `REFUNDED`.
  * O payment intent vira `REFUNDED`.
  * É criada uma nova transação `WITHDRAW` representando o reembolso (retornada em `refundPublicId`).

<Note>
  Ao concluir, é disparado o webhook [`transparent.refunded`](/pages/webhooks/events/transparent) (ou [`checkout.refunded`](/pages/webhooks/events/checkout) quando houver um billing associado à cobrança). Configure seu endpoint em [Webhooks](/pages/webhooks/create) para receber a notificação.
</Note>

***

## Códigos de erro

| Código                       | Significado                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `LOCK_NOT_ACQUIRED`          | Outra operação está em andamento para esta loja — tente novamente em instantes.                                  |
| `TRANSACTION_NOT_FOUND`      | O `id` informado não existe ou não pertence à loja.                                                              |
| `TRANSACTION_NOT_REFUNDABLE` | A transação não está em um estado reembolsável (precisa estar `COMPLETE`, ou `APPROVED`/`COMPLETE` para `CARD`). |
| `TRANSACTION_UNDER_DISPUTE`  | Transação em disputa — não pode ser reembolsada.                                                                 |
| `INVALID_METHOD`             | Apenas `PIX`, `PIX_QRCODE` e `CARD` podem ser reembolsados.                                                      |
| `INSUFFICIENT_FUNDS`         | Saldo da loja menor que o valor da transação.                                                                    |
| `STORE_NOT_FOUND`            | Loja não encontrada.                                                                                             |
| `REFUND_REQUEST_FAILED`      | Falha ao criar a transação no ledger ou ao acionar o provider.                                                   |
| `REFUND_CONFIRMATION_FAILED` | Falha ao confirmar o reembolso após a criação.                                                                   |

**Exemplo de erro:**

```json theme={null}
{
  "data": null,
  "success": false,
  "error": "TRANSACTION_NOT_REFUNDABLE"
}
```

***

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.abacatepay.com/v2/transparents/refund \
  -H "Authorization: Bearer $ABACATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pix_char_abc123xyz",
    "reason": "Cliente pagou em duplicidade."
  }'
```


# Simular Pagamento
Source: https://docs.abacatepay.com/pages/transparents/simulate-payment

POST /transparents/simulate-payment
Simula o pagamento de um QRCode Pix criado no modo de desenvolvimento.

Simula o pagamento de um QR Code PIX no ambiente de desenvolvimento. Só funciona com chaves de API de sandbox.

<Card>
  Requer a permissão `CHECKOUT:READ`. Disponível apenas em `devMode`.
</Card>

Use para testar o fluxo completo sem precisar realizar um PIX real: crie um QR Code, simule o pagamento e confirme que seu webhook ou polling recebe o status `PAID`.

<Note>
  Em produção este endpoint retorna erro. Ative o [modo de desenvolvimento](/pages/devmode) para usá-lo.
</Note>


# Obter Informações do Merchant
Source: https://docs.abacatepay.com/pages/trustMRR/get

GET /public-mrr/merchant-info
Retorna informações básicas da loja (ID, nome, website e data de criação).

<Card>
  Requer a permissão `STORE:READ`.
</Card>


# Obter Receita por Período
Source: https://docs.abacatepay.com/pages/trustMRR/list

GET /public-mrr/revenue
Retorna a receita total, total de transações e transações por dia em um período específico. Os dados são cacheados por 1 hora (3600 segundos) para melhor performance. A data de fim deve ser posterior à data de início.

<Card>
  Requer a permissão `STORE:READ`.
</Card>


# Obter MRR
Source: https://docs.abacatepay.com/pages/trustMRR/mrr

GET /public-mrr/mrr
Retorna o MRR (receita recorrente mensal) e o total de assinaturas ativas da loja.

<Note title="Recurso público">
  Este endpoint (**MRR**) não requer permissões de chave de API.
</Note>


# Referência
Source: https://docs.abacatepay.com/pages/trustMRR/reference

Métricas de receita públicas para integração ou exibição

As rotas **Public MRR** expõem métricas de receita da loja para integração com plataformas Trust MRR ou para exibir no seu site ou dashboard.

## Estrutura

### Merchant (`/public-mrr/merchant-info`)

Dados básicos da loja:

```json theme={null}
{
  "data": {
    "id": "store_abc123xyz",
    "name": "Example Tech",
    "website": "https://www.example.com",
    "createdAt": "2024-12-06T18:53:31.756Z"
  },
  "error": null
}
```

### MRR (`/public-mrr/mrr`)

Receita recorrente mensal:

```json theme={null}
{
  "data": {
    "mrr": 0,
    "totalActiveSubscriptions": 0
  },
  "error": null
}
```

### Receita por período (`/public-mrr/revenue`)

Totais e transações por dia:

```json theme={null}
{
  "data": {
    "totalRevenue": 150000,
    "totalTransactions": 45,
    "transactionsPerDay": {
      "2024-01-15": { "amount": 5000, "count": 3 },
      "2024-01-16": { "amount": 3000, "count": 2 }
    }
  },
  "error": null
}
```

## Atributos

**Merchant (merchant-info):**

| Atributo    | Tipo   | Descrição                  |
| ----------- | ------ | -------------------------- |
| `id`        | string | ID único da loja           |
| `name`      | string | Nome da loja               |
| `website`   | string | Site da loja               |
| `createdAt` | string | Data de criação (ISO 8601) |

**MRR (mrr):**

| Atributo                   | Tipo    | Descrição                                           |
| -------------------------- | ------- | --------------------------------------------------- |
| `mrr`                      | number  | Receita recorrente mensal em centavos (0 = nenhuma) |
| `totalActiveSubscriptions` | integer | Quantidade de assinaturas ativas (0 = nenhuma)      |

**Receita (revenue):**

| Atributo             | Tipo    | Descrição                                                                       |
| -------------------- | ------- | ------------------------------------------------------------------------------- |
| `totalRevenue`       | number  | Receita total do período em centavos                                            |
| `totalTransactions`  | integer | Número de transações no período                                                 |
| `transactionsPerDay` | object  | Por dia (chave = data YYYY-MM-DD); cada valor tem `amount` (centavos) e `count` |

<Tip title="Valores em centavos" icon="coins">
  Valores monetários vêm em centavos. Divida por 100 para reais (ex.: 150000 = R\$ 1.500,00).
</Tip>


# Webhooks
Source: https://docs.abacatepay.com/pages/webhooks

Receba notificações automáticas da AbacatePay sempre que algo importante acontecer — como um pagamento aprovado ou um saque concluído.

Pense nos webhooks como **“mensagens enviadas pela AbacatePay para o seu sistema”**, sem que você precise ficar consultando a API o tempo todo.

***

## Por que usar webhooks?

Sem webhooks, sua aplicação teria que **perguntar para a API a cada segundo**:

> "Esse pagamento já foi confirmado?"

Isso é lento e ineficiente.

Com webhooks, a AbacatePay avisa você **imediatamente**:

> "O pagamento foi confirmado. Aqui estão os dados."

Assim você pode:

* atualizar o status de um pedido
* liberar acesso a um produto
* enviar e-mails automáticos
* registrar movimentações financeiras

Tudo isso sem precisar fazer nada manualmente, e sem fazer seu cliente esperar.

***

## Como funciona na prática?

1. **Você cria um endpoint no seu sistema**\
   Ex.: `https://meusite.com/webhooks/abacatepay`

2. **Você cadastra esse endpoint no dashboard da AbacatePay**

3. **Sempre que algo importante acontece**, como um pagamento aprovado:
   * A AbacatePay envia um POST para a sua URL
   * O POST contém o evento (ex: `checkout.completed`, `transparent.completed`)
   * Seu sistema processa esse evento

É como receber uma notificação push — só que para servidores.

***

## Ambientes (Dev mode vs Produção)

<Card title="Ambientes da AbacatePay">
  * Webhooks criados em **Dev mode** recebem eventos simulados
  * Webhooks criados em **Produção** recebem eventos reais

  Dessa forma, você pode testar tudo antes de ir para produção.
</Card>

***

## Segurança dos webhooks

Webhooks precisam ser seguros — afinal, qualquer pessoa poderia tentar enviar requisições falsas para sua aplicação.

Por isso, recomendamos duas camadas de proteção:

**1. Secret na URL** — cada webhook tem uma chave secreta que vai junto com a URL. Seu sistema verifica se essa chave está correta antes de processar o evento.

**2. Assinatura digital (HMAC)** — a AbacatePay assina cada evento que envia. Seu sistema pode confirmar que o evento realmente veio da AbacatePay e que não foi alterado no caminho. É o mesmo método usado por Stripe, PayPal, Shopify e GitHub.

<Info>
  A configuração de segurança é feita pelo seu desenvolvedor. Veja a documentação técnica completa na [página de segurança de webhooks](/pages/webhooks/security).
</Info>

<AccordionGroup>
  <Accordion title="Ver implementação — Secret na URL (Node.js)">
    Cada webhook tem um secret único, que vai na query string da URL:

    `https://meusite.com/webhook/abacatepay?webhookSecret=SEU_SECRET`

    ```js theme={null}
    if (req.query.webhookSecret !== process.env.WEBHOOK_SECRET) {
      return res.status(401).json({ error: "Unauthorized" });
    }
    ```
  </Accordion>

  <Accordion title="Ver implementação — Validação HMAC (Node.js)">
    Cada webhook enviado pela AbacatePay inclui uma assinatura no header `X-Webhook-Signature` gerada com HMAC-SHA256.

    ```typescript theme={null}
    import crypto from "node:crypto";

    const ABACATEPAY_PUBLIC_KEY =
      "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMUgo6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmUCKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1JhNHDX9";

    export function verifyAbacateSignature(rawBody: string, signatureFromHeader: string) {
      const bodyBuffer = Buffer.from(rawBody, "utf8")

      const expectedSig = crypto
        .createHmac("sha256", ABACATEPAY_PUBLIC_KEY)
        .update(bodyBuffer)
        .digest("base64");

      const A = Buffer.from(expectedSig);
      const B = Buffer.from(signatureFromHeader);

      return A.length === B.length && crypto.timingSafeEqual(A, B);
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Criando um webhook no dashboard

<Steps>
  <Step title="Acesse a seção de Webhooks">
    <Card>
      <img alt="Interface mostrando webhooks" />

      <Card title="Abra a área de Webhooks">
        É aqui que você cria e gerencia seus endpoints de notificação.
      </Card>
    </Card>
  </Step>

  <Step title="Clique em Criar">
    <Card>
      <img alt="Configuração de webhook" />

      <Card title="Inicie a configuração">
        Informe o nome e a URL que receberá os eventos.
      </Card>
    </Card>
  </Step>

  <Step title="Configure os detalhes">
    <Card>
      <Card title="O que você deve informar:">
        * **Nome**: Ex.: “Pagamentos confirmados”
        * **URL**: Endpoint HTTPS que receberá os eventos
        * **Secret**: Chave usada para verificar a autenticidade
      </Card>
    </Card>
  </Step>
</Steps>

***

## Eventos suportados

| Evento                   | Quando é disparado                                     |
| ------------------------ | ------------------------------------------------------ |
| `checkout.completed`     | Pagamento de um checkout foi confirmado                |
| `checkout.refunded`      | Reembolso de um checkout foi concluído                 |
| `checkout.disputed`      | Disputa/chargeback aberta em um checkout               |
| `transparent.completed`  | Pagamento de um checkout transparente confirmado       |
| `transparent.refunded`   | Reembolso de um checkout transparente foi concluído    |
| `transparent.disputed`   | Disputa/chargeback aberta em um pagamento transparente |
| `subscription.completed` | Assinatura criada e ativada                            |
| `subscription.cancelled` | Assinatura cancelada                                   |
| `subscription.renewed`   | Cobrança recorrente da assinatura foi paga             |
| `transfer.completed`     | Transferência concluída com sucesso                    |
| `transfer.failed`        | Transferência falhou                                   |
| `payout.completed`       | Saque concluído com sucesso                            |
| `payout.failed`          | Saque falhou                                           |

Todos os webhooks v2 compartilham o mesmo formato de payload:

```json theme={null}
{
  "id": "log_abc123xyz",
  "event": "checkout.completed",
  "apiVersion": 2,
  "devMode": false,
  "data": { ... }
}
```

<Info>
  **Dados sensíveis:** O campo `taxId` (CPF/CNPJ) é mascarado nos payloads (ex: `123.***.***-**`). Para pagamentos com cartão, apenas os últimos 4 dígitos e a bandeira são enviados.
</Info>

Os payloads detalhados de cada evento estão documentados individualmente na seção **Eventos** na barra lateral.

***

## Estrutura dos payloads

### Quando `customer` está vazio

Se não houver cliente vinculado ao checkout, pagamento ou assinatura, o objeto `customer` será `null`.

***

## Boas práticas

<Card title="Recomendações importantes">
  * Use **HTTPS** em todos os webhooks
  * Valide o **secret** e a **assinatura HMAC**
  * Registre cada evento recebido — processe cada um **uma única vez**
  * Responda **200 OK** somente após concluir o processamento
  * Implemente **retentativas com idempotência**
  * **Não realize validação do payload inteiro** dos webhooks (como com Zod), **evitando que mudanças futuras não quebrem seu endpoint**
</Card>

***

<Card title="Precisa de ajuda?" icon="headset">
  Nossa equipe pode te ajudar. Contate-nos: <Icon icon="envelope" type="solid" /> [ajuda@abacatepay.com](mailto:ajuda@abacatepay.com)
</Card>


# Criar um webhook
Source: https://docs.abacatepay.com/pages/webhooks/create

POST /webhooks/create
Cria um novo webhook para receber notificações automáticas de eventos da sua loja.

O `endpoint` deve ser uma URL HTTPS válida e não pode apontar para endereços locais ou IPs privados.

**Alternativa**: Você também pode criar e gerenciar seus webhooks pelo [Dashboard da AbacatePay](https://app.abacatepay.com/webhooks).


<Card>
  Requer a permissão `WEBHOOK:CREATE`.
</Card>


# Deletar um webhook
Source: https://docs.abacatepay.com/pages/webhooks/delete

POST /webhooks/delete
Remove um webhook da sua loja.

Esta operação é irreversível. Use com cuidado.


<Card>
  Requer a permissão `WEBHOOK:DELETE`.
</Card>


# Checkout
Source: https://docs.abacatepay.com/pages/webhooks/events/checkout

Eventos disparados para pagamentos via Checkout (PIX, Cartão e Boleto).

<Tabs>
  <Tab title="checkout.completed">
    Disparado quando um pagamento via checkout é realizado. O `payerInformation` varia conforme o método.

    <Tabs>
      <Tab title="PIX">
        ```json theme={null}
        {
          "event": "checkout.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 80,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["PIX"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": null,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "João Silva",
                "taxId": "123.***.***-**",
                "isSameAsCustomer": true
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cartão">
        ```json theme={null}
        {
          "event": "checkout.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 120,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["CARD"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": 3,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Boleto">
        ```json theme={null}
        {
          "event": "checkout.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 100,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["BOLETO"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": null,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "BOLETO",
              "BOLETO": {
                "name": "João Silva",
                "taxId": "123.***.***-**",
                "isSameAsCustomer": true
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="checkout.disputed">
    Disparado quando um pagamento via checkout sofre uma disputa. O `payerInformation` varia conforme o método.

    <Tabs>
      <Tab title="PIX">
        ```json theme={null}
        {
          "event": "checkout.disputed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 80,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["PIX"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": null,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "João Silva",
                "taxId": "123.***.***-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Cartão">
        ```json theme={null}
        {
          "event": "checkout.disputed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 120,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["CARD"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": 3,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Boleto">
        ```json theme={null}
        {
          "event": "checkout.disputed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 100,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["BOLETO"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": null,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "BOLETO",
              "BOLETO": {
                "name": "João Silva",
                "taxId": "123.***.***-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="checkout.refunded">
    Disparado quando um pagamento via checkout é reembolsado. O `payerInformation` varia conforme o método.

    <Tabs>
      <Tab title="PIX">
        ```json theme={null}
        {
          "event": "checkout.refunded",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 80,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["PIX"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": null,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "João Silva",
                "taxId": "123.***.***-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Cartão">
        ```json theme={null}
        {
          "event": "checkout.refunded",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 120,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["CARD"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": 3,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Boleto">
        ```json theme={null}
        {
          "event": "checkout.refunded",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "checkout": {
              "id": "bill_abc123xyz",
              "externalId": "pedido-123",
              "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
              "amount": 10000,
              "paidAmount": 10000,
              "platformFee": 100,
              "frequency": "ONE_TIME",
              "items": [{ "id": "prod_xyz", "quantity": 1 }],
              "status": "PAID",
              "methods": ["BOLETO"],
              "customerId": "cust_abc123",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "installmentsCount": null,
              "createdAt": "2024-12-06T18:56:15.538Z",
              "updatedAt": "2024-12-06T18:56:20.000Z"
            },
            "customer": {
              "id": "cust_abc123",
              "name": "João Silva",
              "email": "joao@exemplo.com",
              "taxId": "123.***.***-**"
            },
            "payerInformation": {
              "method": "BOLETO",
              "BOLETO": {
                "name": "João Silva",
                "taxId": "123.***.***-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Saques
Source: https://docs.abacatepay.com/pages/webhooks/events/payouts

Eventos disparados para saques (retirada de saldo da plataforma).

Usados para notificar o status de **saques** (retirada de saldo da plataforma).

<Tabs>
  <Tab title="payout.completed">
    Disparado quando um saque é concluído com sucesso. O campo `endToEndIdentifier` está presente apenas em saques concluídos.

    ```json theme={null}
    {
      "event": "payout.completed",
      "apiVersion": 2,
      "devMode": false,
      "data": {
        "withdraw": {
          "id": "tran_xxx",
          "amount": 1000,
          "status": "COMPLETE",
          "method": "PIX",
          "platformFee": 80,
          "receiptUrl": "https://...",
          "externalId": null,
          "createdAt": "...",
          "updatedAt": "...",
          "endToEndIdentifier": "E123..."
        }
      }
    }
    ```
  </Tab>

  <Tab title="payout.failed">
    Disparado quando um saque falha.

    ```json theme={null}
    {
      "event": "payout.failed",
      "apiVersion": 2,
      "devMode": false,
      "data": {
        "withdraw": {
          "id": "tran_xxx",
          "amount": 1000,
          "status": "FAILED",
          "method": "PIX",
          "platformFee": 80,
          "receiptUrl": "https://...",
          "externalId": null,
          "createdAt": "...",
          "updatedAt": "..."
        }
      }
    }
    ```
  </Tab>
</Tabs>


# Assinaturas
Source: https://docs.abacatepay.com/pages/webhooks/events/subscriptions

Eventos disparados para assinaturas (PIX e Cartão).

<Tabs>
  <Tab title="subscription.trial_started">
    Disparado quando uma assinatura com período de teste gratuito é criada. O cliente não é cobrado neste momento — a primeira cobrança pelo valor integral ocorre ao final do `trialDays`.

    ```json theme={null}
    {
      "id": "log_trialXYZ123abc",
      "event": "subscription.trial_started",
      "apiVersion": 2,
      "devMode": false,
      "data": {
        "subscription": {
          "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
          "amount": 4990,
          "currency": "BRL",
          "method": "CARD",
          "status": "ACTIVE",
          "frequency": "MONTHLY",
          "trialDays": 7,
          "trialEndsAt": "2024-11-11T23:59:59.999Z",
          "createdAt": "2024-11-04T18:38:28.573Z",
          "updatedAt": "2024-11-04T18:38:28.573Z",
          "canceledAt": null,
          "cancelPolicy": null,
          "cancelledDueTo": null
        },
        "customer": {
          "id": "cust_def456",
          "name": "Maria Santos",
          "email": "maria@exemplo.com",
          "taxId": "12.***.***/0001-**"
        }
      }
    }
    ```
  </Tab>

  <Tab title="subscription.completed">
    Disparado quando uma assinatura se torna ativa.

    <Tabs>
      <Tab title="Cartão">
        ```json theme={null}
        {
          "id": "log_taQArRTApemxwcbw5EJeF3hS",
          "event": "subscription.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "CARD",
              "status": "ACTIVE",
              "frequency": "MONTHLY",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z",
              "canceledAt": null,
              "cancelPolicy": null,
              "cancelledDueTo": null
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payment": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 100,
              "status": "PAID",
              "methods": ["CARD"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "checkout": {
              "id": "bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "externalId": null,
              "url": "https://app.abacatepay.com/pay/bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 100,
              "frequency": "SUBSCRIPTION",
              "items": [{ "id": "prod_bx4BstRWhQ2SUcKsPt4c6pmq", "quantity": 1 }],
              "status": "PAID",
              "methods": ["CARD"],
              "customerId": "cust_def456",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:59:57.819Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            }
          }
        }
        ```
      </Tab>

      <Tab title="PIX">
        ```json theme={null}
        {
          "id": "log_taQArRTApemxwcbw5EJeF3hS",
          "event": "subscription.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "PIX",
              "status": "ACTIVE",
              "frequency": "MONTHLY",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z",
              "canceledAt": null,
              "cancelPolicy": null,
              "cancelledDueTo": null
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payment": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 60,
              "status": "PAID",
              "methods": ["PIX"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "Maria Santos",
                "taxId": "12.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "checkout": {
              "id": "bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "externalId": null,
              "url": "https://app.abacatepay.com/pay/bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 60,
              "frequency": "SUBSCRIPTION",
              "items": [{ "id": "prod_bx4BstRWhQ2SUcKsPt4c6pmq", "quantity": 1 }],
              "status": "PAID",
              "methods": ["PIX"],
              "customerId": "cust_def456",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:59:57.819Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="subscription.renewed">
    Disparado sempre que uma assinatura é renovada com sucesso.

    <Tabs>
      <Tab title="Cartão">
        ```json theme={null}
        {
          "id": "log_abc123xyz",
          "event": "subscription.renewed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "CARD",
              "status": "ACTIVE",
              "frequency": "MONTHLY",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2025-01-06T20:00:05.000Z",
              "canceledAt": null,
              "cancelPolicy": null,
              "cancelledDueTo": null
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payment": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 100,
              "status": "PAID",
              "methods": ["CARD"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2025-01-06T20:00:00.000Z",
              "updatedAt": "2025-01-06T20:00:05.000Z"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "checkout": {
              "id": "bill_renewxyz789",
              "externalId": null,
              "url": "https://app.abacatepay.com/pay/bill_renewxyz789",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 100,
              "frequency": "SUBSCRIPTION",
              "items": [{ "id": "prod_bx4BstRWhQ2SUcKsPt4c6pmq", "quantity": 1 }],
              "status": "PAID",
              "methods": ["CARD"],
              "customerId": "cust_def456",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2025-01-06T19:59:57.819Z",
              "updatedAt": "2025-01-06T20:00:05.000Z"
            }
          }
        }
        ```
      </Tab>

      <Tab title="PIX">
        ```json theme={null}
        {
          "id": "log_abc123xyz",
          "event": "subscription.renewed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "PIX",
              "status": "ACTIVE",
              "frequency": "MONTHLY",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2025-01-06T20:00:05.000Z",
              "canceledAt": null,
              "cancelPolicy": null,
              "cancelledDueTo": null
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payment": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 60,
              "status": "PAID",
              "methods": ["PIX"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2025-01-06T20:00:00.000Z",
              "updatedAt": "2025-01-06T20:00:05.000Z"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "Maria Santos",
                "taxId": "12.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "checkout": {
              "id": "bill_renewxyz789",
              "externalId": null,
              "url": "https://app.abacatepay.com/pay/bill_renewxyz789",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 60,
              "frequency": "SUBSCRIPTION",
              "items": [{ "id": "prod_bx4BstRWhQ2SUcKsPt4c6pmq", "quantity": 1 }],
              "status": "PAID",
              "methods": ["PIX"],
              "customerId": "cust_def456",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2025-01-06T19:59:57.819Z",
              "updatedAt": "2025-01-06T20:00:05.000Z"
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="subscription.payment_failed">
    Disparado a cada falha de cobrança de um ciclo. O campo `retryNumber` indica quantas tentativas já foram feitas. Quando `retryNumber` atingir `maxRetry` (configurado em `retryPolicy` ao criar a assinatura), a assinatura é cancelada automaticamente e o evento `subscription.cancelled` é disparado logo em seguida com `cancelledDueTo: "max_payment_retries_exceeded"`.

    ```json theme={null}
    {
      "id": "log_abc123xyz",
      "event": "subscription.payment_failed",
      "apiVersion": 2,
      "devMode": false,
      "data": {
        "subscription": {
          "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
          "amount": 2990,
          "currency": "BRL",
          "method": "CARD",
          "status": "ACTIVE",
          "frequency": "MONTHLY",
          "retryPolicy": {
            "maxRetry": 3,
            "retryEvery": 2
          },
          "createdAt": "2024-12-06T20:00:00.000Z",
          "updatedAt": "2025-01-06T20:00:05.000Z",
          "canceledAt": null,
          "cancelPolicy": null,
          "cancelledDueTo": null
        },
        "installmentId": "intl_abc123xyz",
        "installmentNumber": 2,
        "retryNumber": 1
      }
    }
    ```
  </Tab>

  <Tab title="subscription.cancelled">
    Disparado quando uma assinatura é cancelada — seja via API ou automaticamente após esgotar todas as tentativas de cobrança. Nesse segundo caso, `cancelledDueTo` será `"max_payment_retries_exceeded"`.

    <Tabs>
      <Tab title="Cancelamento manual">
        ```json theme={null}
        {
          "id": "log_abc123xyz",
          "event": "subscription.cancelled",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "CARD",
              "status": "CANCELLED",
              "frequency": "MONTHLY",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z",
              "canceledAt": "2024-12-06T20:00:05.000Z",
              "cancelPolicy": "NOW",
              "cancelledDueTo": null
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payment": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 100,
              "status": "PAID",
              "methods": ["CARD"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "checkout": {
              "id": "bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "externalId": null,
              "url": "https://app.abacatepay.com/pay/bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 100,
              "frequency": "SUBSCRIPTION",
              "items": [{ "id": "prod_bx4BstRWhQ2SUcKsPt4c6pmq", "quantity": 1 }],
              "status": "PAID",
              "methods": ["CARD"],
              "customerId": "cust_def456",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:59:57.819Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cancelamento automático (max retries)">
        Disparado quando todas as tentativas de cobrança são esgotadas. `cancelledDueTo` identifica a causa e `cancelPolicy` é `"NOW"`, indicando que os ciclos futuros também foram cancelados.

        ```json theme={null}
        {
          "id": "log_abc123xyz",
          "event": "subscription.cancelled",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "CARD",
              "status": "CANCELLED",
              "frequency": "MONTHLY",
              "retryPolicy": {
                "maxRetry": 3,
                "retryEvery": 2
              },
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2025-01-06T20:00:05.000Z",
              "canceledAt": "2025-01-06T20:00:05.000Z",
              "cancelPolicy": "NOW",
              "cancelledDueTo": "max_payment_retries_exceeded"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            }
          }
        }
        ```
      </Tab>

      <Tab title="PIX">
        ```json theme={null}
        {
          "id": "log_abc123xyz",
          "event": "subscription.cancelled",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "subscription": {
              "id": "subs_tAFqDWBhcEYTjQh2K0ZYDHau",
              "amount": 2990,
              "currency": "BRL",
              "method": "PIX",
              "status": "CANCELLED",
              "frequency": "MONTHLY",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z",
              "canceledAt": "2024-12-06T20:00:05.000Z",
              "cancelPolicy": "NOW",
              "cancelledDueTo": null
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payment": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 60,
              "status": "PAID",
              "methods": ["PIX"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T20:00:00.000Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "Maria Santos",
                "taxId": "12.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "checkout": {
              "id": "bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "externalId": null,
              "url": "https://app.abacatepay.com/pay/bill_jskd3TMfScHZDJe5NSZjTmQ4",
              "amount": 2990,
              "paidAmount": 2990,
              "platformFee": 60,
              "frequency": "SUBSCRIPTION",
              "items": [{ "id": "prod_bx4BstRWhQ2SUcKsPt4c6pmq", "quantity": 1 }],
              "status": "PAID",
              "methods": ["PIX"],
              "customerId": "cust_def456",
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:59:57.819Z",
              "updatedAt": "2024-12-06T20:00:05.000Z"
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Transferências
Source: https://docs.abacatepay.com/pages/webhooks/events/transfers

Eventos disparados para transferências de valores para contas externas.

Usados para notificar o status de **transferências** (envio de valores para contas externas).

<Tabs>
  <Tab title="transfer.completed">
    Disparado quando uma transferência é concluída com sucesso.

    ```json theme={null}
    {
      "event": "transfer.completed",
      "apiVersion": 2,
      "devMode": false,
      "data": {
        "transfer": {
          "id": "tran_xxx",
          "externalId": "payout-ext-123",
          "amount": 1000,
          "status": "COMPLETE",
          "method": "PIX",
          "platformFee": 80,
          "receiptUrl": "https://...",
          "createdAt": "...",
          "updatedAt": "...",
          "endToEndIdentifier": "E123..."
        }
      }
    }
    ```
  </Tab>

  <Tab title="transfer.failed">
    Disparado quando uma transferência falha.

    ```json theme={null}
    {
      "event": "transfer.failed",
      "apiVersion": 2,
      "devMode": false,
      "data": {
        "transfer": {
          "id": "tran_xxx",
          "externalId": "payout-ext-123",
          "amount": 1000,
          "status": "FAILED",
          "method": "PIX",
          "platformFee": 80,
          "receiptUrl": "https://...",
          "createdAt": "...",
          "updatedAt": "...",
          "endToEndIdentifier": "E123..."
        }
      }
    }
    ```
  </Tab>
</Tabs>


# Checkout Transparente
Source: https://docs.abacatepay.com/pages/webhooks/events/transparent

Eventos disparados para pagamentos via Checkout Transparente (PIX, Cartão e Boleto).

<Tabs>
  <Tab title="transparent.completed">
    Disparado quando um pagamento via checkout transparente é realizado. O `payerInformation` varia conforme o método.

    <Tabs>
      <Tab title="PIX">
        ```json theme={null}
        {
          "event": "transparent.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 5000,
              "paidAmount": 5000,
              "platformFee": 50,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": true,
              "customerId": "cust_abc123",
              "methods": ["PIX"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:00:00.000Z",
              "updatedAt": "2024-12-06T19:00:05.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "Maria Santos",
                "taxId": "12.***.***/0001-**",
                "isSameAsCustomer": true
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cartão">
        ```json theme={null}
        {
          "event": "transparent.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 5000,
              "paidAmount": 5000,
              "platformFee": 78,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": true,
              "customerId": "cust_abc123",
              "methods": ["CARD"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:00:00.000Z",
              "updatedAt": "2024-12-06T19:00:05.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Boleto">
        ```json theme={null}
        {
          "event": "transparent.completed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "bole_k8pqr2mnvx",
              "externalId": "pedido-456",
              "amount": 25000,
              "paidAmount": 25000,
              "platformFee": 250,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": false,
              "customerId": "cust_abc123",
              "methods": ["BOLETO"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-11-04T14:22:10.381Z",
              "updatedAt": "2024-11-04T14:22:15.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Mariana Costa",
              "email": "mariana.costa@empresa.com.br",
              "taxId": "98*.***.***/0001-**"
            },
            "payerInformation": {
              "method": "BOLETO",
              "BOLETO": {
                "name": "Mariana Costa",
                "taxId": "98*.***.***/0001-**",
                "isSameAsCustomer": true
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="transparent.disputed">
    Disparado quando um pagamento via checkout transparente sofre uma disputa. O `payerInformation` varia conforme o método.

    <Tabs>
      <Tab title="PIX">
        ```json theme={null}
        {
          "event": "transparent.disputed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 5000,
              "paidAmount": 5000,
              "platformFee": 50,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": true,
              "customerId": "cust_abc123",
              "methods": ["PIX"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:00:00.000Z",
              "updatedAt": "2024-12-06T19:00:05.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "Maria Santos",
                "taxId": "12.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Cartão">
        ```json theme={null}
        {
          "event": "transparent.disputed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 5000,
              "paidAmount": 5000,
              "platformFee": 78,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": true,
              "customerId": "cust_abc123",
              "methods": ["CARD"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:00:00.000Z",
              "updatedAt": "2024-12-06T19:00:05.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Boleto">
        ```json theme={null}
        {
          "event": "transparent.disputed",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "bole_k8pqr2mnvx",
              "externalId": "pedido-456",
              "amount": 25000,
              "paidAmount": 25000,
              "platformFee": 250,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": false,
              "customerId": "cust_abc123",
              "methods": ["BOLETO"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-11-04T14:22:10.381Z",
              "updatedAt": "2024-11-04T14:22:15.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Mariana Costa",
              "email": "mariana.costa@empresa.com.br",
              "taxId": "98*.***.***/0001-**"
            },
            "payerInformation": {
              "method": "BOLETO",
              "BOLETO": {
                "name": "Mariana Costa",
                "taxId": "98*.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="transparent.refunded">
    Disparado quando um pagamento via checkout transparente é reembolsado. O `payerInformation` varia conforme o método.

    <Tabs>
      <Tab title="PIX">
        ```json theme={null}
        {
          "event": "transparent.refunded",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 5000,
              "paidAmount": 5000,
              "platformFee": 50,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": true,
              "customerId": "cust_abc123",
              "methods": ["PIX"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:00:00.000Z",
              "updatedAt": "2024-12-06T19:00:05.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payerInformation": {
              "method": "PIX",
              "PIX": {
                "name": "Maria Santos",
                "taxId": "12.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Cartão">
        ```json theme={null}
        {
          "event": "transparent.refunded",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "char_xyz789",
              "externalId": "pedido-456",
              "amount": 5000,
              "paidAmount": 5000,
              "platformFee": 78,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": true,
              "customerId": "cust_abc123",
              "methods": ["CARD"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-12-06T19:00:00.000Z",
              "updatedAt": "2024-12-06T19:00:05.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Maria Santos",
              "email": "maria@exemplo.com",
              "taxId": "12.***.***/0001-**"
            },
            "payerInformation": {
              "method": "CARD",
              "CARD": {
                "number": "1234",
                "brand": "VISA"
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>

      <Tab title="Boleto">
        ```json theme={null}
        {
          "event": "transparent.refunded",
          "apiVersion": 2,
          "devMode": false,
          "data": {
            "transparent": {
              "id": "bole_k8pqr2mnvx",
              "externalId": "pedido-456",
              "amount": 25000,
              "paidAmount": 25000,
              "platformFee": 250,
              "status": "PAID",
              "frequency": "ONE_TIME",
              "devMode": false,
              "customerId": "cust_abc123",
              "methods": ["BOLETO"],
              "receiptUrl": "https://app.abacatepay.com/receipt/...",
              "createdAt": "2024-11-04T14:22:10.381Z",
              "updatedAt": "2024-11-04T14:22:15.000Z"
            },
            "customer": {
              "id": "cust_def456",
              "name": "Mariana Costa",
              "email": "mariana.costa@empresa.com.br",
              "taxId": "98*.***.***/0001-**"
            },
            "payerInformation": {
              "method": "BOLETO",
              "BOLETO": {
                "name": "Mariana Costa",
                "taxId": "98*.***.***/0001-**",
                "isSameAsCustomer": true
              }
            },
            "reason": "requested_by_customer"
          }
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Buscar um webhook
Source: https://docs.abacatepay.com/pages/webhooks/get

GET /webhooks/get
Retorna os dados de um webhook específico pelo seu identificador.

<Card>
  Requer a permissão `WEBHOOK:READ`.
</Card>


# Listar webhooks
Source: https://docs.abacatepay.com/pages/webhooks/list

GET /webhooks/list
Retorna todos os webhooks da sua loja com suporte a paginação e busca.

**Alternativa**: Você também pode visualizar e gerenciar seus webhooks pelo [Dashboard da AbacatePay](https://app.abacatepay.com/webhooks).


<Card>
  Requer a permissão `WEBHOOK:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data).


# Referência
Source: https://docs.abacatepay.com/pages/webhooks/reference

Crie e gerencie webhooks para receber notificações automáticas de eventos na sua loja.

Webhooks permitem que a AbacatePay envie notificações automáticas para o seu sistema sempre que um evento relevante ocorrer, como um pagamento aprovado ou uma assinatura renovada.

Para entender como funcionam os webhooks, os eventos disponíveis e como validar as assinaturas HMAC, consulte a [página de webhooks](/pages/webhooks).

## Criar webhook

Use `POST /webhooks/create`.

<Card title="Campos obrigatórios">
  Obrigatórios: `name`, `endpoint` (URL HTTPS), `secret`, `events`.
</Card>

**Exemplo:**

```json theme={null}
POST /webhooks/create
{
  "name": "Meu Webhook de Pagamentos",                    // obrigatório - nome identificador do webhook
  "endpoint": "https://meusite.com/webhooks/abacatepay", // obrigatório - URL HTTPS que receberá os eventos
  "secret": "meu-secret-seguro",                         // obrigatório - chave usada para assinar os payloads
  "events": ["checkout.completed", "subscription.renewed"] // obrigatório - lista de eventos
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "webh_abc123xyz",
    "name": "Meu Webhook de Pagamentos",
    "endpoint": "https://meusite.com/webhooks/abacatepay",
    "events": ["checkout.completed", "subscription.renewed"],
    "devMode": false,
    "v2": true,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "success": true,
  "error": null
}
```

## Eventos suportados

| Evento                       | Quando é disparado                            |
| ---------------------------- | --------------------------------------------- |
| `checkout.completed`         | Pagamento de um checkout foi confirmado       |
| `checkout.refunded`          | Reembolso de um checkout foi concluído        |
| `checkout.disputed`          | Disputa/chargeback aberta em um checkout      |
| `checkout.lost`              | Disputa de checkout perdida                   |
| `transparent.completed`      | Pagamento transparente confirmado             |
| `transparent.refunded`       | Reembolso de pagamento transparente concluído |
| `transparent.disputed`       | Disputa em pagamento transparente             |
| `transparent.lost`           | Disputa de pagamento transparente perdida     |
| `subscription.completed`     | Assinatura criada e ativada                   |
| `subscription.cancelled`     | Assinatura cancelada                          |
| `subscription.renewed`       | Cobrança recorrente da assinatura paga        |
| `subscription.trial_started` | Período de trial iniciado                     |
| `payout.completed`           | Saque concluído com sucesso                   |
| `payout.failed`              | Saque falhou                                  |
| `transfer.completed`         | Transferência concluída com sucesso           |
| `transfer.failed`            | Transferência falhou                          |

## Modelo do webhook

O objeto retornado nas operações de criar, buscar e listar segue este formato:

| Campo       | Tipo       | Descrição                                |
| ----------- | ---------- | ---------------------------------------- |
| `id`        | `string`   | Identificador único do webhook           |
| `name`      | `string`   | Nome do webhook                          |
| `endpoint`  | `string`   | URL HTTPS que recebe os eventos          |
| `events`    | `string[]` | Lista de eventos subscritos              |
| `devMode`   | `boolean`  | Se o webhook é de ambiente de testes     |
| `v2`        | `boolean`  | Se o webhook usa o formato de payload v2 |
| `createdAt` | `string`   | Data de criação (ISO 8601)               |
| `updatedAt` | `string`   | Data da última atualização (ISO 8601)    |

## Segurança

* Requisições autenticadas via Bearer Token
* O `endpoint` deve usar HTTPS e não pode apontar para endereços locais ou IPs privados
* Abusos podem levar à suspensão da conta conforme os [termos de uso](https://abacatepay.com/termos)


# Verificação e Segurança
Source: https://docs.abacatepay.com/pages/webhooks/security

Como validar a autenticidade dos webhooks e lidar com retentativas.

Sem validação, qualquer pessoa que descobrir sua URL de webhook pode forjar eventos e acionar lógica de negócio (ex: liberar acesso sem pagar). Os dois mecanismos abaixo — secret e HMAC — garantem que o evento veio da AbacatePay e que o corpo não foi alterado. Use ambos.

Todo webhook enviado pela AbacatePay inclui dois mecanismos de segurança: um **secret na URL** e uma **assinatura HMAC** no header. Use os dois juntos.

***

## 1. Secret na URL

Ao criar o webhook, você define um `secret`. A AbacatePay inclui esse valor como query parameter em cada requisição:

```
https://meusite.com/webhook/abacatepay?webhookSecret=SEU_SECRET
```

Seu backend valida antes de qualquer processamento:

```ts theme={null}
if (req.query.webhookSecret !== process.env.WEBHOOK_SECRET) {
  return res.status(401).json({ error: "Unauthorized" });
}
```

***

## 2. Assinatura HMAC

Mesmo que alguém descubra sua URL e seu secret, a assinatura HMAC garante que o **corpo da requisição não foi alterado** e que o evento realmente veio da AbacatePay.

O header enviado é:

```
X-Webhook-Signature: <assinatura em base64>
```

A assinatura é calculada com **HMAC-SHA256** sobre o corpo raw da requisição usando a chave pública da AbacatePay.

### Validação em Node.js

```typescript theme={null}
import crypto from "node:crypto";

const ABACATEPAY_PUBLIC_KEY =
  "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMUgo6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmUCKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1JhNHDX9";

export function verifyAbacateSignature(rawBody: string, signatureFromHeader: string): boolean {
  const expectedSig = crypto
    .createHmac("sha256", ABACATEPAY_PUBLIC_KEY)
    .update(Buffer.from(rawBody, "utf8"))
    .digest("base64");

  const A = Buffer.from(expectedSig);
  const B = Buffer.from(signatureFromHeader);

  return A.length === B.length && crypto.timingSafeEqual(A, B);
}
```

### Validação em Python

```python theme={null}
import hmac
import hashlib
import base64

ABACATEPAY_PUBLIC_KEY = "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMUgo6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmUCKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1JhNHDX9"

def verify_abacate_signature(raw_body: bytes, signature_from_header: str) -> bool:
    expected = hmac.new(
        ABACATEPAY_PUBLIC_KEY.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).digest()
    expected_b64 = base64.b64encode(expected).decode("utf-8")
    return hmac.compare_digest(expected_b64, signature_from_header)
```

### Validação em Go

```go theme={null}
package webhook

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
)

const abacatePublicKey = "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMUgo6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmUCKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1JhNHDX9"

func VerifySignature(rawBody []byte, signatureFromHeader string) bool {
    mac := hmac.New(sha256.New, []byte(abacatePublicKey))
    mac.Write(rawBody)
    expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureFromHeader))
}
```

<Warning>
  Use sempre `timingSafeEqual` (ou equivalente) ao comparar assinaturas — nunca `==`. Comparações diretas são vulneráveis a timing attacks.
</Warning>

***

## Retentativas

Se seu endpoint não retornar `2xx` dentro do timeout, a AbacatePay tenta reenviar o evento automaticamente com backoff progressivo.

**O que pode causar retentativa:**

* Timeout na conexão
* Resposta com status `5xx`
* Resposta com status `4xx` (exceto `200`)

**Boas práticas para lidar com retentativas:**

<Card title="Idempotência é obrigatória">
  Armazene o campo `id` de cada evento recebido. Antes de processar, verifique se esse ID já foi tratado anteriormente. Eventos duplicados são raros mas acontecem.
</Card>

```ts theme={null}
// Exemplo de controle de idempotência
const eventId = req.body.id; // ex: "log_abc123xyz"

const alreadyProcessed = await db.events.findOne({ id: eventId });
if (alreadyProcessed) {
  return res.status(200).json({ ok: true }); // responde 200 mas não processa de novo
}

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

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

***

## Checklist de segurança

<Card>
  * Use **HTTPS** — nunca HTTP em produção
  * Valide o **secret** na query string
  * Valide a **assinatura HMAC** do header
  * Responda **200 OK** somente após concluir o processamento
  * Implemente **idempotência** usando o `id` do evento
  * Não valide o payload inteiro com schemas rígidos (como Zod) — campos novos podem ser adicionados futuramente
</Card>


# MCP Server
Source: https://docs.abacatepay.com/pages/ai/mcp

Integre a AbacatePay diretamente em agentes de IA como Claude Desktop e Cursor via Model Context Protocol.

O **AbacatePay MCP Server** expõe toda a API da AbacatePay como ferramentas nativas para agentes de IA compatíveis com o [Model Context Protocol](https://modelcontextprotocol.io). Com ele, você pode criar cobranças, consultar clientes, emitir PIX e muito mais — direto de uma conversa com Claude ou Cursor.

<Info>
  O servidor suporta **v1 e v2 simultaneamente** em um único processo. As ferramentas v2 têm o prefixo `v2`; as v1 não têm prefixo. As chaves **não são intercambiáveis** entre versões.
</Info>

***

## Pré-requisitos

* [Bun](https://bun.sh) 1.x
* Chave de API da AbacatePay — acesse o dashboard em **Integrar → API Keys**

***

## Instalação local

```bash theme={null}
git clone https://github.com/AbacatePay/abacatepay-mcp.git
cd abacatepay-mcp
bun install
```

***

## Configuração

<Tabs>
  <Tab title="Claude Desktop">
    Abra o arquivo de configuração do Claude Desktop (`claude_desktop_config.json`) e adicione:

    ```json theme={null}
    {
      "mcpServers": {
        "abacate-pay": {
          "command": "bun",
          "args": ["/caminho/absoluto/para/abacatepay-mcp/src/index.ts"],
          "env": {
            "ABACATE_PAY_API_KEY": "sua_chave_aqui"
          }
        }
      }
    }
    ```

    <Warning>
      Use o **caminho absoluto** para `src/index.ts`. Caminhos relativos causam falha na inicialização.
    </Warning>
  </Tab>

  <Tab title="Cursor">
    Em `mcp.servers` nas configurações do Cursor, adicione a mesma estrutura:

    ```json theme={null}
    {
      "mcp.servers": {
        "abacate-pay": {
          "command": "bun",
          "args": ["/caminho/absoluto/para/abacatepay-mcp/src/index.ts"],
          "env": {
            "ABACATE_PAY_API_KEY": "sua_chave_aqui"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="HTTP remoto">
    Use o endpoint público hospedado pela AbacatePay — sem precisar instalar nada localmente:

    ```json theme={null}
    {
      "mcpServers": {
        "abacatepay": {
          "url": "https://mcp.abacatepay.com/mcp",
          "headers": {
            "Authorization": "Bearer SUA_CHAVE_API"
          }
        }
      }
    }
    ```

    Também é aceito o header `X-API-Key` como alternativa ao `Authorization`.
  </Tab>
</Tabs>

***

## Ferramentas disponíveis (v2)

Todas as ferramentas v2 têm o prefixo `v2` e cobrem os principais recursos da API:

| Categoria                   | Exemplos de ferramentas                       |
| --------------------------- | --------------------------------------------- |
| Clientes                    | `v2ListCustomers`, `v2CreateCustomer`         |
| Cupons                      | `v2ListCoupons`, `v2CreateCoupon`             |
| Produtos                    | `v2ListProducts`, `v2CreateProduct`           |
| Checkouts                   | `v2CreateCheckout`, `v2ListCheckouts`         |
| Links de pagamento          | `v2CreatePaymentLink`, `v2ListPaymentLinks`   |
| Checkout Transparente (PIX) | `v2CreatePixPayment`                          |
| Saques                      | `v2CreatePayout`, `v2GetPayout`               |
| Transferências PIX          | `v2CreatePixTransfer`                         |
| Assinaturas                 | `v2CreateSubscription`, `v2ListSubscriptions` |
| Loja                        | `v2GetStorefront`                             |
| Métricas públicas           | `v2GetPublicMRR`                              |

***

## Solução de problemas

<AccordionGroup>
  <Accordion title="Erro de chave de API">
    Verifique se a variável `ABACATE_PAY_API_KEY` está definida no lugar certo (dentro do bloco `env` da config, não no shell). Confirme também que a versão da chave (v1 ou v2) corresponde às ferramentas que está usando.
  </Accordion>

  <Accordion title="Servidor não conecta">
    Confirme que o caminho para `src/index.ts` é absoluto e que o Bun está instalado (`bun --version`). Após alterar a configuração, reinicie o Claude Desktop ou o Cursor.
  </Accordion>

  <Accordion title="Ferramenta não encontrada">
    Ferramentas v2 têm o prefixo `v2`. Se uma ferramenta esperada não aparece, verifique se está usando a chave v2 e se o servidor subiu sem erros.
  </Accordion>
</AccordionGroup>

***

<Card title="Repositório" icon="github" href="https://github.com/AbacatePay/abacatepay-mcp">
  Código-fonte, changelog e guia de contribuição no GitHub.
</Card>


# Skills
Source: https://docs.abacatepay.com/pages/ai/skills

Pacotes de contexto especializado para ensinar agentes de IA a integrar com a AbacatePay.

A **AbacatePay Skills** é um conjunto de **conhecimentos estruturados**, **regras técnicas** e **exemplos práticos** projetados para ensinar agentes de IA e desenvolvedores a integrar corretamente com o ecossistema AbacatePay.

Funciona como um **manual inteligente e executável** — focado em reduzir ambiguidade, evitar erros comuns e acelerar integrações reais, especialmente em ambientes assistidos por IA.

***

## O que são Skills?

Skills são **pacotes de contexto especializado** que descrevem:

* Regras de negócio da AbacatePay
* Padrões técnicos oficiais
* Convenções de código por linguagem
* Boas práticas para APIs, SDKs e Webhooks

Elas podem ser consumidas por **IDEs** e **ferramentas de AI coding** como Cursor, Claude Code e similares.

<CardGroup>
  <Card title="Contexto Preciso" icon="pen">
    Informação atualizada e específica sobre APIs, SDKs e Webhooks.
  </Card>

  <Card title="Padronização" icon="ruler">
    Código gerado alinhado às convenções oficiais da AbacatePay.
  </Card>

  <Card title="Aceleração" icon="rocket">
    Menos leitura de docs longas, mais regras diretas.
  </Card>

  <Card title="Exemplos Reais" icon="code">
    Implementações práticas em TypeScript e Go.
  </Card>

  <Card title="IA-friendly" icon="sparkles">
    Estrutura pensada para consumo por agentes de IA.
  </Card>

  <Card title="Menos Erros" icon="shield-check">
    Reduz interpretações erradas e integrações incorretas.
  </Card>
</CardGroup>

***

## Como instalar

<Steps>
  <Step title="Clone o repositório">
    ```bash theme={null}
    git clone https://github.com/abacatepay/skills
    ```
  </Step>

  <Step title="Adicione ao contexto da IA">
    Inclua a pasta `skills/` no contexto do seu editor.

    **Cursor:** adicione o caminho em `.cursorrules` ou workspace rules.

    **Claude Code:** referencie na configuração do projeto.
  </Step>

  <Step title="Use via CLI (opcional)">
    Algumas skills já estão integradas diretamente na [AbacatePay CLI](/pages/cli/overview).
  </Step>
</Steps>

***

## Estrutura do repositório

* **[tests](https://github.com/AbacatePay/skills/tree/main/tests)** — suítes de teste para validar integrações e fluxos críticos
* **[tools](https://github.com/AbacatePay/skills/tree/main/tools)** — documentação técnica de ferramentas auxiliares, SDKs e clientes
* **[examples](https://github.com/AbacatePay/skills/tree/main/examples)** — implementações reais e snippets prontos para uso imediato
* **[rules](https://github.com/AbacatePay/skills/tree/main/rules)** — regras específicas por linguagem (TypeScript / Go) e por módulo (Checkout, Subscriptions, Webhooks, etc.)

***

## Filosofia

As AbacatePay Skills seguem alguns princípios claros:

* **Explícitas** — sem regras implícitas ou achismos
* **Auditáveis** — texto claro, versionado e revisável
* **Modulares** — cada skill resolve um problema específico
* **IA-first** — escritas pensando em consumo automático

<CardGroup>
  <Card title="Human-readable" icon="user">
    Também úteis para humanos, não só para máquinas.
  </Card>

  <Card title="Fonte única de verdade" icon="database">
    Evita divergência entre docs, exemplos e código.
  </Card>
</CardGroup>

***

<Card title="SKILL.md" icon="book-open" href="https://github.com/AbacatePay/skills/blob/main/SKILL.md">
  Documento central que descreve todas as skills disponíveis e como usá-las.
</Card>


# Changelog da API
Source: https://docs.abacatepay.com/pages/changelog/index

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

<Update label="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](/pages/reference/introduction#paginação-e-filtro-por-data) para detalhes completos.

  ***
</Update>

<Update label="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](/pages/payment/reference#data-de-vencimento-do-boleto) e [Criar cobrança Boleto](/pages/transparents/boleto).

  ***
</Update>

<Update label="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](/pages/pix/create) 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.
  </Warning>

  ***
</Update>

<Update label="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
  }
  ```

  ***
</Update>

<Update label="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](/pages/products/reference) para mais detalhes.

  ***
</Update>

<Update label="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`.

  ***
</Update>

<Update label="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.
  </Note>

  ***
</Update>

<Update label="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.
  </Note>

  ***
</Update>

<Update label="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](/pages/subscriptions/reference) para exemplos completos e detalhes de cada endpoint.

  ***
</Update>

<Update label="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 |

  ***
</Update>

<Update label="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**.

  ***
</Update>

<Update label="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": "123.456.789-00",
        "email": "joao@exemplo.com"
      }
    }
  }
  ```

  ***
</Update>

<Update label="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"
    },
    ...
  }
  ```

  ***
</Update>

<Update label="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": { ... }
    }
  }
  ```

  ***
</Update>

<Update label="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](/pages/v1/introduction)

  ***
</Update>

<Update label="Antes da API v2">
  Esquecemos os updates antes da v2. Prometemos que todo novo update aparecerá por aqui.

  <img />
</Update>


# Ecossistema
Source: https://docs.abacatepay.com/pages/ecosystem/ecosystem

Bibliotecas, temas e extensões open source que compõem o ecossistema da AbacatePay.

## O que é o Ecossistema da AbacatePay?

O ecossistema da AbacatePay reúne **projetos open source oficiais ativaments mantidos por [almeida](https://www.eualmeida.com.br/) e [albuquerque](https://links.albuquerquesz.com.br/), e da comunidade** que expandem, facilitam ou personalizam a integração com nossa plataforma de pagamentos.

Aqui você encontra desde SDKs complementares, ferramentas de desenvolvimento, temas, plugins e integrações com outros frameworks e plataformas.

<Card title="O que você encontra no ecossistema">
  * **Projetos oficiais**: Mantidos e suportados pela equipe AbacatePay
  * **Projetos da comunidade**: Criados por desenvolvedores que usam a AbacatePay no dia a dia
  * **Ferramentas de DX**: CLIs, helpers, mocks, templates e automações
  * **Extensões e plugins**: Integrações com frameworks, CMSs e plataformas
  * **Temas e UI kits**: Componentes visuais para acelerar integrações frontend
</Card>

***

## Projetos Oficiais

Projetos mantidos diretamente pela equipe da AbacatePay, com versionamento, documentação e suporte contínuo.

<CardGroup>
  <Card title="SDKs Oficiais" icon="boxes-stacked" href="../sdks">
    Bibliotecas oficiais para integração com a API da AbacatePay em diversas linguagens.
  </Card>

  <Card title="CLI AbacatePay" icon="terminal" href="../cli">
    Ferramenta de linha de comando para desenvolvimento, testes e automações locais.
  </Card>

  <Card title="Templates Oficiais" icon="sparkles">
    Templates prontos para iniciar projetos com AbacatePay em diferentes stacks.
  </Card>

  <Card title="Webhooks & Dev Tools" icon="webhook" href="../webhooks">
    Ferramentas auxiliares para testar, simular e depurar eventos da API.
  </Card>
</CardGroup>

***

## Projetos da Comunidade

Iniciativas criadas e mantidas pela comunidade que ampliam o uso da AbacatePay em diferentes contextos.

> Projetos da comunidade **não são mantidos oficialmente**, mas muitos são amplamente usados e recomendados.

<CardGroup>
  <Card title="Integrações com Frameworks" icon="hammer">
    Plugins e wrappers para frameworks backend e frontend.
  </Card>

  <Card title="Plugins para CMS e E-commerce" icon="shopping-cart">
    Integrações com plataformas como CMSs, lojas virtuais e sistemas de gestão.
  </Card>

  <Card title="UI Kits & Componentes" icon="palette">
    Componentes visuais prontos para checkout, status de pagamento e dashboards.
  </Card>

  <Card title="Ferramentas de Teste & Mock" icon="flask">
    Mocks, simuladores e ferramentas para testes automatizados.
  </Card>
</CardGroup>

***

## Quer contribuir?

Contribuições são **muito bem-vindas**. Você pode:

* Criar uma nova biblioteca ou integração
* Melhorar documentação existente
* Reportar bugs ou inconsistências
* Compartilhar seu projeto com a comunidade

<Card title="Como enviar seu projeto" icon="github">
  Abra uma issue ou pull request no repositório correspondente no GitHub.
  Se quiser destacar seu projeto aqui, entre em contato com a equipe AbacatePay.
</Card>

***

## Perguntas Frequentes

<Accordion title="Qual a diferença entre projetos oficiais e da comunidade?">
  Projetos oficiais são mantidos pela equipe da AbacatePay e contam com suporte direto.
  Projetos da comunidade são desenvolvidos por terceiros e podem ter níveis variados de manutenção.
</Accordion>

<Accordion title="Posso usar projetos da comunidade em produção?">
  Sim, mas recomendamos avaliar o nível de manutenção, testes e compatibilidade com sua stack antes.
</Accordion>

<Accordion title="Meu projeto pode virar oficial?">
  Em alguns casos, sim. Projetos bem adotados, bem documentados e alinhados ao ecossistema podem ser incorporados ou recomendados oficialmente.
</Accordion>

***

## Recursos Relacionados

<CardGroup>
  <Card title="SDKs" icon="boxes-stacked" href="../sdks">
    Bibliotecas oficiais para integração com a API.
  </Card>

  <Card title="Changelog da API" icon="scroll" href="../changelog">
    Acompanhe mudanças e atualizações da API.
  </Card>
</CardGroup>


# ESLint Plugin
Source: https://docs.abacatepay.com/pages/ecosystem/eslint

Plugin ESLint para evitar vazamento de chaves da AbacatePay e reforçar boas práticas de segurança.

## O que é o @abacatepay/eslint-plugin?

O `@abacatepay/eslint-plugin` é um **plugin de segurança para ESLint** que evita o vazamento acidental de **API keys da AbacatePay** diretamente no código-fonte.

Ele detecta **chaves secretas hardcoded** em qualquer contexto (strings, headers, JSX, templates, configs, etc.) e incentiva o uso correto de **variáveis de ambiente**, antes que o problema chegue ao repositório ou à produção.

<Card title="Por que isso importa?" icon="alert-triangle">
  * Vazamento de API keys é um dos erros mais comuns em projetos
  * Linters pegam o problema **antes do commit**
  * Segurança como padrão, sem depender de code review
</Card>

***

## Instalação

Use o *package manager* da sua preferência:

```bash theme={null}
bun add -d @abacatepay/eslint-plugin
# ou
pnpm add -d @abacatepay/eslint-plugin
# ou
npm install -d @abacatepay/eslint-plugin
```

## Configuração

**ESLint v9+ (Flat Config)**

O plugin foi projetado exclusivamente para ESLint v9+, utilizando o novo formato de flat config.

```ts theme={null}
import abacatepay from '@abacatepay/eslint-plugin';

export default [
    {
        plugins: {
            abacatepay,
        },
        rules: {
            'abacatepay/no-secret-key': 'error',
        },
    },
];
```

## Regras Disponíveis

`abacatepay/no-secret-key`

Impede o uso de chaves secretas da AbacatePay diretamente no código, independentemente do contexto:

* Strings literais
* Headers HTTP
* JSX / props
* Templates
* Configurações de clientes

<Card title="Comportamento da regra"> A regra <strong>não aplica autofix destrutivo</strong>. Sempre que possível, ela oferece <strong>sugestões seguras</strong> para substituição. </Card>

### Sugestões Automáticas

Quando detecta uma chave hardcoded, a regra sugere automaticamente o uso de variáveis de ambiente:

```diff theme={null}
- "abc_prod_xxxxxxxxxxxxxxxxxxxxxxx"
+ process.env.ABACATEPAY_API_KEY
```

### Exemplos de Uso Incorreto

```ts theme={null}
import { AbacatePay } from '@abacatepay/sdk';

const abacate = AbacatePay({
    secret: 'abc_dev_xxxxxxxxxxxxxxxxxxxxxxx',
});
```

```ts theme={null}
import { REST } from '@abacatepay/rest';

const client = new REST({
    secret: 'abc_prod_xxxxxxxxxxxxxxxxxxxxxxx',
});
```

```tsx theme={null}
<Component secret="abc_dev_xxxxxxxxxxxxxxxxxxxxxxx" />
```

## Segurança por Design

<CardGroup> <Card title="Preventivo" icon="shield"> O erro é detectado antes do commit ou deploy. </Card> <Card title="Baixo ruído" icon="filter"> Apenas casos reais de risco são reportados. </Card> </CardGroup>

## Recursos Relacionados

<CardGroup> <Card title="@abacatepay/rest" icon="repeat" href="./rest"> Cliente REST oficial para a API da AbacatePay. </Card> <Card title="SDKs Oficiais" icon="boxes-stacked" href="../sdks"> Integrações de alto nível para diversas linguagens. </Card> </CardGroup> <Card title="Open source, de verdade" icon="heart"> O <code>@abacatepay/eslint-plugin</code> é open source e mantido pela equipe AbacatePay. Contribuições e sugestões são bem-vindas. </Card>


# REST
Source: https://docs.abacatepay.com/pages/ecosystem/rest

REST client ergonômico, rápido e totalmente tipado para a API da AbacatePay.

## O que é o @abacatepay/rest?

O [@abacatepay/rest](https://www.npmjs.com/package/@abacatepay/rest) é um **cliente REST leve, rápido e totalmente tipado** para consumir a API da AbacatePay diretamente, sem abstrações pesadas.

Ele foi projetado para **Node.js, Bun e runtimes modernos**, oferecendo controle total sobre as requisições, com **retries inteligentes**, **backoff automático**, **timeouts configuráveis** e **tratamento de erros consistente**.

<Card title="Quando usar o REST Client?" icon="help-circle">
  * Você quer **controle total** sobre endpoints e payloads
  * Está criando **SDKs, CLIs ou ferramentas internas**
  * Prefere uma camada fina sobre HTTP em vez de abstrações de alto nível
  * Precisa de **performance e previsibilidade**
</Card>

***

## Instalação

Use o *package manager* da sua preferência:

```bash theme={null}
bun add @abacatepay/rest
# ou
pnpm add @abacatepay/rest
# ou
npm install @abacatepay/rest
```

## Uso Básico

Exemplo simulando um pagamento Pix via QR Code:

```ts theme={null}
import { REST } from '@abacatepay/rest';

const client = new REST({
    secret: process.env.ABACATEPAY_API_KEY!,
});

const pix = await client.post('/transparents/simulate-payment', {
    query: {
        id: 'pix_char_123456'
    },
});

console.log(pix);
```

## Versionando para usar a API v1

```ts theme={null}
import { REST } from '@abacatepay/rest';

const client = new REST({
    version: 1,
});

const { status, expiresAt } = await client.get('/pixQrCode/check', {
    query: {
        id,
    },
});

console.log(status, expiresAt);
```

Ou você pode configurar a versão em rotas específicas via `version`

```ts theme={null}
await client.post('/coupons/delete', {
    query: {
        id,
    },
    version: 2,
});
```

Sem abstrações, sem plugins, sem boilerplate, apenas **REST**.

## Performance & Design

O `@abacatepay/rest` foi desenhado para ser:

* Zero dependências
* Compatível com fetch nativo
* Rápido por padrão
* Seguro por padrão

<CardGroup> <Card title="Tipagem forte" icon="lasso"> Tipos completos para respostas, erros e configurações. </Card> <Card title="Runtimes modernos" icon="boxes"> Funciona perfeitamente em **Node.js**, **Bun** e ambientes modernos. </Card> </CardGroup>

## Custom-Fetch

Você também pode configurar o seu próprio `fetch` para requisições:

```ts theme={null}
const client = new REST({
    async fetch(route, options) {
        // ...

        return new Response(...);
    },
});
```

O valor retornado deve ser **sempre** um objeto **Response**, caso o contrário, um erro será lançado.

## Retry & Backoff

Por padrão, o REST Client faz 3 tentativas automáticas para erros retryable, como:

* Rate limit (`429`)
* Erros `5xx`
* Falhas de rede

```ts theme={null}
const client = new REST({
    retry: {
        max: 5,
        onRetry({ options, attempt, response }) {
            console.log(`Retrying ${response.url} (${options.method})...`);
        },
    },
});
```

### Backoff customizado

```ts theme={null}
const client = new REST({
    retry: {
        max: 7,
        backoff(attempt) {
            return Math.min(10_000, 500 * 2 ** attempt);
        },
    },
});
```

Se nenhum backoff for definido, o client usa **backoff exponencial com jitter** automaticamente.

### Rate Limit

Você também pode controlar **completamente** com o hook `onRateLimit` quando um rate-limit ocorre:

```ts theme={null}
const client = new REST({
    async onRateLimit(response) {
        ...
    },
});
```

## Configurações Avançadas

Você pode customizar completamente o comportamento do client:

* Timeout por request
* Headers globais
* Retry e backoff
* Versionamento automático
* Base URL (sandbox / production)
* Hooks internos (request / response)

<Card title="Flexível por design" icon="sliders"> O REST Client não impõe padrões — ele se adapta à sua arquitetura. </Card>

### REST Client vs SDKs

<CardGroup> <Card title="REST Client" icon="sparkles" href="#"> Camada fina, controle total, ideal para libs, CLIs e integrações avançadas. </Card> <Card title="SDKs" icon="boxes-stacked" href="../sdks"> Abstrações de alto nível para integração rápida com menos código. </Card> </CardGroup>

### Próximos Passos

<CardGroup> <Card title="Documentação Completa" icon="book-open" href="../payment/reference"> Veja todos os endpoints, opções e exemplos avançados. </Card> <Card title="NPM Package" icon="box" href="https://www.npmjs.com/package/@abacatepay/rest"> Acesse o pacote no NPM e histórico de versões. </Card> </CardGroup> <Card title="Open Source de verdade" icon="heart" href="https://github.com/almeidazs/ecosystem"> O <code>@abacatepay/rest</code> é open source e mantido pela equipe AbacatePay. Contribuições são bem-vindas. </Card>


# Tema
Source: https://docs.abacatepay.com/pages/ecosystem/theme

Tema oficial green-first da AbacatePay para VS Code, IntelliJ e Neovim.

## O que é o AbacatePay Theme?

O **AbacatePay Theme** é o **tema oficial da AbacatePay**, projetado para oferecer uma experiência visual consistente, confortável e produtiva em **ambientes de desenvolvimento modernos**.

Ele segue uma abordagem **green-first**, alinhada à identidade visual da AbacatePay, com foco em:

* Leitura prolongada sem fadiga
* Contraste equilibrado
* Destaque semântico de código
* Consistência entre editores

<Card title="Quando usar o AbacatePay Theme?" icon="help-circle">
  - Você quer **consistência visual** entre ferramentas
  - Trabalha longas horas no editor
  - Valoriza **identidade visual forte** no setup
  - Prefere temas limpos, modernos e sem excesso de cor
</Card>

***

## Editores suportados

O tema é mantido oficialmente para os seguintes editores:

<CardGroup>
  <Card title="VS Code" icon="code" href="#vs-code">
    Tema oficial publicado no Marketplace.
  </Card>

  <Card title="IntelliJ / JetBrains" icon="terminal" href="#intellij-%2F-jetbrains-ides">
    Schemes nativos sem necessidade de plugin.
  </Card>

  <Card title="Neovim" icon="moon-star" href="#neovim">
    Suporte completo com variações e Lualine.
  </Card>
</CardGroup>

***

## Instalação

### VS Code

Instale diretamente pelo Marketplace:

```bash theme={null}
code --install-extension abacatepay.abacatepay-theme
```

Ou acesse o [Marketplace](https://marketplace.visualstudio.com/items?itemName=abacatepay.abacatepay-theme).

**Temas disponíveis**

* AbacatePay Dark Theme
* AbacatePay Light Theme
* AbacatePay Soft Theme

E também temos suporte para temas tem *itálico*

* AbacatePay Dark *Italic* Theme
* AbacatePay Soft *Italic* Theme
* AbacatePay Light *Italic* Theme\*\*

#### Sincronizar com o sistema

Você pode sincronizar facilmente entre seus temas preferidos dark / light mode dentro do VS Code.

```jsonc theme={null}
{
    "window.autoDetectColorScheme": true,
    "workbench.preferredDarkColorTheme": "AbacatePay Dark Theme",
    "workbench.preferredLightColorTheme": "AbacatePay Light Theme"
}
```

O JSON acima deve ficar no arquivo `settings.json` do seu VS Code.

### IntelliJ / JetBrains IDEs

O tema é distribuído como Color Scheme nativo.

#### Como instalar

<Steps>
  <Step title="Intellij">
    Entre na sua IDE JetBrains que você deseja configurar o tema
  </Step>

  <Step title="Configurações">
    Vá em Settings / Preferences → Editor → Color Scheme → Clique no ⚙️ → Import Scheme
  </Step>

  <Step title="Escolhendo o tema">
    Selecione um dos arquivos abaixo que deseja e aplique-o
  </Step>
</Steps>

```bash theme={null}
intellij/abacatepay-theme-dark.json
intellij/abacatepay-theme-light.json
intellij/abacatepay-theme-soft.json
```

<Card title="Sem plugins" icon="check-circle"> Funciona nativamente em IDEs JetBrains, sem dependências externas. </Card>

### Neovim

Tema oficial com suporte a múltiplas variações.

**lazy.nvim**

```lua theme={null}
{
    "AbacatePay/vscode-theme",
    lazy = false,
    priority = 1000,
    config = function()
        vim.cmd.colorscheme("abacatepay-theme")
    end,
}
```

**packer.nvim**

```lua theme={null}
use({
    "AbacatePay/vscode-theme",
        config = function()
        vim.cmd.colorscheme("abacatepay-theme")
    end,
})
```

**Variações**

```lua theme={null}
vim.cmd("colorscheme abacatepay-theme")       -- Dark (default)
vim.cmd("colorscheme abacatepay-theme-light") -- Light
vim.cmd("colorscheme abacatepay-theme-soft")  -- Soft
```

**Lualine**

```lua theme={null}
require("lualine").setup {
    options = {
        theme = "abacatepay-theme"
    }
}
```

## Design & Filosofia

O AbacatePay Theme foi projetado para ser:

* Consistente entre editores
* Confortável para longas sessões
* Semântico (cores com significado)
* Livre de distrações

<CardGroup> <Card title="Identidade forte" icon="sparkles"> Visual alinhado ao ecossistema AbacatePay. </Card> <Card title="Produtividade" icon="zap"> Menos ruído visual, mais foco no código. </Card> </CardGroup>

### Próximos Passos

<CardGroup>
  <Card title="Repositório Open Source" icon="github" href="https://github.com/abacatepay/vscode-theme"> Código-fonte, issues e contribuições. </Card>

  <Card title="Ecossistema AbacatePay" icon="boxes-stacked" href="../ecosystem">
    Veja o ecossistema completo da AbacatePay.
  </Card>
</CardGroup>

<Card title="Open source de verdade" icon="heart"> O AbacatePay Theme é mantido pela equipe AbacatePay e pela comunidade. </Card>


# TypeBox
Source: https://docs.abacatepay.com/pages/ecosystem/typebox

Schemas oficiais da API da AbacatePay com TypeBox para validação runtime, contratos tipados e OpenAPI.

## O que é o @abacatepay/typebox?

O [@abacatepay/typebox](https://www.npmjs.com/package/@abacatepay/typebox) expõe **todos os schemas públicos da API da AbacatePay** usando **TypeBox**, servindo como **fonte única de verdade** para contratos de dados, validação runtime e geração de OpenAPI.

Não há abstrações extras nem “tipos inventados”: os schemas refletem **exatamente** a API documentada.

Projetado para **TypeScript-first**, com integração direta em frameworks modernos como **Elysia**, **Fastify**, **Hono**, além de compatibilidade total com **Node.js** e **Bun**.

<Card title="Quando usar o TypeBox?" icon="help-circle">
  * Você quer **contratos tipados + validação runtime**
  * Precisa garantir **compatibilidade entre versões da API**
  * Quer gerar **OpenAPI 3.1** automaticamente
  * Está construindo SDKs, gateways ou backends tipados
</Card>

***

## Instalação

Use o *package manager* da sua preferência:

```bash theme={null}
bun add @abacatepay/typebox
# ou
pnpm add @abacatepay/typebox
# ou
npm install @abacatepay/typebox
```

## Estrutura e Versionamento

Assim como em outros pacotes da AbacatePay, os schemas são versionados por API.

Importe sempre a versão correspondente à API que você está usando:

```ts theme={null}
import { APICustomer } from '@abacatepay/typebox/v1';
import { APISubscription } from '@abacatepay/typebox/v2';
```

Schemas globais (ex: version, utilitários e helpers) são exportados sem versionamento:

```ts theme={null}
import { version } from '@abacatepay/typebox';
```

<Card title="Por que versionar schemas?" icon="ellipsis"> Isso permite detectar breaking changes, manter compatibilidade e evoluir a API sem quebrar integrações existentes. </Card>

### <Icon icon="zap" type="solid" /> Integração com Elysia

O TypeBox se encaixa diretamente no Elysia, sem camadas extras.

```ts theme={null}
import { Elysia } from 'elysia';
import {
    APIResponse,
    APICheckout,
    RESTPostCreateNewCheckoutBody,
} from '@abacatepay/typebox/v2';

new Elysia().post(
    '/checkouts/create',
    () => {
        ...
    },
    {
        body: RESTPostCreateNewCheckoutBody,
        response: APIResponse(APICheckout),
        detail: {
            tags: ['Checkouts'],
            summary: 'Create a new checkout',
        },
    },
);
```

Isso garante:

* Validação automática de input
* Tipagem forte de output
* OpenAPI gerado corretamente

## Uso Básico (Validação Runtime)

Você pode validar facilmente dados retornados pela API em runtime:

```ts theme={null}
import { Value } from '@sinclair/typebox/value';
import { APICheckout } from '@abacatepay/typebox/v2';

const data = await fetchCheckout();

if (!Value.Check(APICheckout, data)) {
    throw new Error('Invalid checkout payload');
}
```

<Card title="Por que validar em runtime?" icon="shield"> Tipos TypeScript não existem em produção. A validação runtime evita bugs silenciosos e payloads inválidos. </Card>

## OpenAPI & JSON Schema

Todos os schemas são **100% compatíveis com OpenAPI 3.1** via JSON Schema.

Isso permite:

* Geração automática de documentação
* Criação de SDKs tipados
* Validação de breaking changes entre versões
* Integração com ferramentas do ecossistema OpenAPI

## Convenções de Nomenclatura

Para manter consistência e previsibilidade, os schemas seguem convenções claras:

**Prefixo `API*`**

* Estruturas gerais da API
* Objetos retornados
* Modelos públicos

**Prefixo `REST<HTTPMethod>*`**

* Schemas usados em endpoints REST
  * Body → corpo da requisição
  * QueryParams → parâmetros de query
  * Data → dados retornados

**Prefixo `Webhook*`**

* Payloads de eventos de webhook

## Integração com o Ecossistema

<CardGroup> <Card title="@abacatepay/rest" icon="repeat" href="./rest"> Cliente REST oficial que consome esses schemas. </Card> <Card title="SDKs Oficiais" icon="boxes-stacked" href="../sdks"> SDKs de alto nível baseados nos contratos da API. </Card> </CardGroup>
<Icon icon="heart" type="solid" /> **Open Source, de Verdade**

<Card title="Feito para desenvolvedores" icon="heart"> O <code>@abacatepay/typebox</code> é open source e mantido pela equipe AbacatePay. Schemas estáveis, versionados e alinhados à documentação oficial. </Card> <CardGroup> <Card title="Documentação Completa" icon="book" href="./typebox"> Veja todos os schemas, versões e exemplos de uso. </Card> </CardGroup>


# API Types
Source: https://docs.abacatepay.com/pages/ecosystem/types

Tipagens oficiais e helpers modernos para integrar com a API da AbacatePay.

## O que é o @abacatepay/types?

O [@abacatepay/types](https://www.npmjs.com/package/@abacatepay/types) fornece **tipagens oficiais e helpers modernos** para trabalhar com a API da AbacatePay de forma segura, previsível e alinhada à documentação oficial.

O pacote é **TypeScript-first** e serve como base para integrações diretas via `fetch`, SDKs internos, CLIs e validações em aplicações backend.

> O pacote **não adiciona tipos além do que existe na documentação oficial**.\
> Cada tipo reflete fielmente a API pública da AbacatePay.

<Card title="Quando usar API Types?" icon="help-circle">
  * Você quer **tipagem forte** sem abstrações
  * Usa `fetch` ou clientes HTTP próprios
  * Precisa de **contratos estáveis** entre versões da API
  * Quer tipar webhooks, rotas e payloads com precisão
</Card>

***

## Instalação

Use o *package manager* da sua preferência:

```bash theme={null}
bun add @abacatepay/types
# ou
pnpm add @abacatepay/types
# ou
npm install @abacatepay/types
```

## Versionamento dos Tipos

Antes de tudo, você deve especificar a versão da API que deseja usar, adicionando **/v**\* na importação:

```ts theme={null}
import { APICustomer } from '@abacatepay/types/v2';
```

**Tipos Globais**

Tipos e constantes globais não são versionados e devem ser importados diretamente:

```ts theme={null}
import { version, API_BASE_URL, API_VERSION } from '@abacatepay/types';
```

<Card title="Por que versionar tipos?" icon="ellipsis"> Isso garante compatibilidade entre versões da API e evita que breaking changes afetem integrações existentes. </Card>

## Convenções de Nomenclatura

Os tipos seguem convenções claras e previsíveis:

**Prefixo `API*`**

* Estruturas gerais da API
* Objetos retornados
* Modelos públicos

**Prefixo `REST<HTTPMethod>*`**

Tipos usados em requisições diretas à API:

* Body → corpo enviado na requisição
  * Ex.: RESTPostCreateNewChargeBody
* QueryParams → parâmetros de query
  * Ex.: RESTGetCheckQRCodePixStatusQueryParams
* Data → dados retornados
  * Ex.: RESTGetListCouponsData

**Prefixo `Webhook*`**

* Payloads de eventos de webhook

### Campos @unstable

Campos marcados com **@unstable**:

* Ainda não possuem definição formal na documentação
* Foram inferidos a partir de exemplos oficiais
* Podem mudar sem aviso prévio

Exemplo:

```ts theme={null}
WebhookWithdrawDoneEvent.billing.kind // @unstable
```

## Quickstart

**Crie um novo cupom**

```ts theme={null}
import {
    Routes,
    type APICoupon,
    type RESTPostCreateCouponBody,
} from '@abacatepay/types/v2';
import { REST } from '@abacatepay/rest';

const client = new REST({ secret });

async function createCoupon(body: RESTPostCreateCouponBody) {
    const data = await client.post<APICoupon>(Routes.coupons.create, { body });

    return data;
}
```

## Integração com o Ecossistema

<CardGroup> <Card title="@abacatepay/typebox" icon="code" href="./typebox"> Schemas runtime e OpenAPI baseados nesses tipos. </Card> <Card title="@abacatepay/rest" icon="repeat" href="./rest"> Cliente REST oficial que consome esses contratos. </Card> </CardGroup>

<Card title="Open Source, de Verdade" icon="heart"> O [@abacatepay/types](https://www.npmjs.com/package/@abacatepay/types) é open source e mantido pela equipe AbacatePay. Tipos estáveis, versionados e 100% alinhados à documentação oficial. </Card>


# API Types (Golang)
Source: https://docs.abacatepay.com/pages/ecosystem/types-go

Structs oficiais e helpers modernos para integrar com a API da AbacatePay em Golang.

## O que é o abacatepay/go-types?

O pacote **abacatepay-go/types** fornece **structs oficiais e helpers modernos** para trabalhar com a API da AbacatePay em Go, de forma segura, previsível e fiel à documentação oficial.

Ele serve como base para integrações diretas usando `net/http`, clientes HTTP próprios, CLIs, serviços backend e validações de payloads.

> O pacote **não adiciona campos além do que existe na documentação oficial**.\
> Cada struct reflete fielmente a API pública da AbacatePay.

<Card title="Quando usar API Types em Go?" icon="help-circle">
  * Você quer **contratos fortes** com `structs` tipadas
  * Usa `net/http` ou um client HTTP próprio
  * Precisa de **compatibilidade explícita** entre versões da API
  * Quer tipar webhooks, rotas e payloads sem SDKs opinativos
</Card>

***

## Instalação

Use o `go get` normalmente:

```bash theme={null}
go get github.com/AbacatePay/go-types@latest
```

## Versionamento dos Tipos

Os tipos são versionados por package, refletindo a versão da API:

```go theme={null}
import "github.com/AbacatePay/go-types/v2"
```

<Card title="Por que versionar por package?" icon="ellipsis"> Isso evita breaking changes silenciosos e permite múltiplas versões da API coexistirem no mesmo projeto. </Card>

## Convenções de Nomenclatura

Os tipos seguem convenções claras e previsíveis:

**Prefixo `API*`**

* Estruturas gerais da API
* Objetos retornados
* Modelos públicos

```go theme={null}
// https://docs.abacatepay.com/pages/store/reference#estrutura
type APIStoreBalance struct {
	// Balance available for withdrawal in cents.
	Available uint64 `json:"available"`

	// Balance pending confirmation in cents.
	Pending uint64 `json:"pending"`

	// Balance blocked in disputes in cents.
	// The blocked balance represents amounts that are in dispute or under review. These amounts are not available for withdrawal until the situation is resolved.
	Blocked uint64 `json:"blocked"`
}
```

**Prefixo `REST<HTTPMethod>*`**

Tipos usados em requisições diretas à API:

* Body → corpo enviado na requisição
  * Ex.: RESTPostCreateNewChargeBody
* QueryParams → parâmetros de query
  * Ex.: RESTGetCheckQRCodePixStatusQueryParams
* Data → dados retornados
  * Ex.: RESTGetListCouponsData

**Prefixo `Webhook*`**

* Payloads de eventos de webhook

### Campos @unstable

Campos marcados como @unstable:

* Ainda não possuem definição formal na documentação
* Foram inferidos a partir de exemplos oficiais
* Podem mudar sem aviso prévio

Eles são documentados diretamente nos comentários Go:

```go theme={null}
// @unstable
BillingKind string `json:"kind"`
```

## Quickstart

### Criar um cupom

```go theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"net/http"

	types "github.com/AbacatePay/go-types/v2"
)

func CreateCoupon(body types.RESTPostCreateCouponBody) (*types.RESTPostCreateCouponData, error) {
	url := types.APIBaseURL + types.RouteCreateCoupon

	payload, _ := json.Marshal(body)

	req, _ := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(payload))

	req.Header.Set("Authorization", "...")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)

	if err != nil {
		return nil, err
	}

	defer resp.Body.Close()

	var data types.RESTPostCreateCouponData

	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		return nil, err
	}

	return data, nil
}
```

* Todas as structs e types contêm o seu respectivo `json` tag com o seu nome e propriedades, então você pode usar `json.Marshal` sem medo.

## Integração com o Ecossistema

<CardGroup> <Card title="REST Client (Go)" icon="repeat" href="./rest-go"> Cliente HTTP oficial em Go que consome esses contratos diretamente. </Card> <Card title="SDKs & Ferramentas" icon="boxes-stacked" href="../sdks"> SDKs, CLIs e ferramentas que reutilizam os mesmos tipos versionados. </Card> </CardGroup>

<Card title="Open Source, de verdade" icon="heart"> O [abacatepay/go-types](https://github.com/AbacatePay/go-types) é open source e mantido pela equipe AbacatePay. Structs estáveis, versionadas e 100% alinhadas à documentação oficial da API. </Card>


# Zod
Source: https://docs.abacatepay.com/pages/ecosystem/zod

Schemas oficiais da API da AbacatePay com Zod para validação runtime, contratos tipados e OpenAPI.

## O que é o @abacatepay/zod?

O [@abacatepay/zod](https://www.npmjs.com/package/@abacatepay/zod) expõe **todos os schemas públicos da API da AbacatePay** usando **Zod**, servindo como **fonte única de verdade** para contratos de dados, validação runtime e geração de OpenAPI via `.meta()`.

Não há abstrações extras nem “tipos inventados”: os schemas refletem **exatamente** a API documentada.

Projetado para **TypeScript-first**, com integração direta em frameworks modernos como **Elysia**, **Fastify**, **Hono**, além de compatibilidade total com **Node.js** e **Bun**.

<Card title="Quando usar o Zod?" icon="help-circle">
  * Você quer **contratos tipados + validação runtime**
  * Precisa garantir **compatibilidade entre versões da API**
  * Quer gerar **OpenAPI 3.1** automaticamente
  * Está construindo SDKs, gateways ou backends tipados
</Card>

***

## Instalação

Use o *package manager* da sua preferência:

```bash theme={null}
bun add @abacatepay/zod
# ou
pnpm add @abacatepay/zod
# ou
npm install @abacatepay/zod
```

## Estrutura e Versionamento

Assim como em outros pacotes da AbacatePay, os schemas são versionados por API.

Importe sempre a versão correspondente à API que você está usando:

```ts theme={null}
import { APICustomer } from '@abacatepay/zod/v1';
import { APISubscription } from '@abacatepay/zod/v2';
```

Schemas globais (ex: version, utilitários e helpers) são exportados sem versionamento:

```ts theme={null}
import { version } from '@abacatepay/zod';
```

<Card title="Por que versionar schemas?" icon="ellipsis"> Isso permite detectar breaking changes, manter compatibilidade e evoluir a API sem quebrar integrações existentes. </Card>

### <Icon icon="zap" type="solid" /> Integração com Elysia

O Zod se encaixa diretamente no Elysia, sem camadas extras.

```ts theme={null}
import { Elysia } from 'elysia';
import {
    APIResponse,
    APICheckout,
    RESTPostCreateNewCheckoutBody,
} from '@abacatepay/zod/v2';

new Elysia().post(
    '/checkouts/create',
    () => {
        ...
    },
    {
        body: RESTPostCreateNewCheckoutBody,
        response: APIResponse(APICheckout),
        detail: {
            tags: ['Checkouts'],
            summary: 'Create a new checkout',
        },
    },
);
```

Isso garante:

* Validação automática de input
* Tipagem forte de output
* OpenAPI gerado corretamente

## Uso Básico (Validação Runtime)

Você pode validar facilmente dados retornados pela API em runtime:

```ts theme={null}
import { Value } from '@sinclair/zod/value';
import { APICheckout } from '@abacatepay/zod/v2';

const data = await fetchCheckout();

if (!Value.Check(APICheckout, data)) {
    throw new Error('Invalid checkout payload');
}
```

<Card title="Por que validar em runtime?" icon="shield"> Tipos TypeScript não existem em produção. A validação runtime evita bugs silenciosos e payloads inválidos. </Card>

## OpenAPI & JSON Schema

Todos os schemas são **100% compatíveis com OpenAPI 3.1** via JSON Schema.

Isso permite:

* Geração automática de documentação
* Criação de SDKs tipados
* Validação de breaking changes entre versões
* Integração com ferramentas do ecossistema OpenAPI

## Convenções de Nomenclatura

Para manter consistência e previsibilidade, os schemas seguem convenções claras:

**Prefixo `API*`**

* Estruturas gerais da API
* Objetos retornados
* Modelos públicos

**Prefixo `REST<HTTPMethod>*`**

* Schemas usados em endpoints REST
  * Body → corpo da requisição
  * QueryParams → parâmetros de query
  * Data → dados retornados

**Prefixo `Webhook*`**

* Payloads de eventos de webhook

## Integração com o Ecossistema

<CardGroup> <Card title="@abacatepay/rest" icon="repeat" href="./rest"> Cliente REST oficial que consome esses schemas. </Card> <Card title="SDKs Oficiais" icon="boxes-stacked" href="../sdks"> SDKs de alto nível baseados nos contratos da API. </Card> </CardGroup>
<Icon icon="heart" type="solid" /> **Open Source, de Verdade**

<Card title="Feito para desenvolvedores" icon="heart"> O <code>@abacatepay/zod</code> é open source e mantido pela equipe AbacatePay. Schemas estáveis, versionados e alinhados à documentação oficial. </Card> <CardGroup> <Card title="Documentação Completa" icon="book" href="./zod"> Veja todos os schemas, versões e exemplos de uso. </Card> </CardGroup>