### Quickstart: Create a New Coupon

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/types.mdx

Example demonstrating how to create a new coupon using the REST client and types from @abacatepay/types.

```typescript
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;
}
```

--------------------------------

### Complete Checkout Example with Installments

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

This is a complete example of creating a checkout with multiple payment methods and a specified number of installments. The `url` returned can be used to redirect the customer to the checkout page.

```json
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
  }
}
```

--------------------------------

### Install AbacatePay Go SDK

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/go.mdx

Use this command to install the AbacatePay Go SDK.

```bash
go get github.com/AbacatePay/abacatepay-go-sdk
```

--------------------------------

### Install Go Types Package

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/types-go.mdx

Use go get to install the latest version of the AbacatePay go-types package.

```bash
go get github.com/AbacatePay/go-types@latest
```

--------------------------------

### Install AbacatePay MCP Server Locally

Source: https://github.com/abacatepay/documentation/blob/main/pages/ai/mcp.mdx

Clone the repository, navigate to the directory, and install dependencies using Bun.

```bash
git clone https://github.com/AbacatePay/abacatepay-mcp.git
cd abacatepay-mcp
bun install
```

--------------------------------

### Install AbacatePay SDK

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/nodejs.mdx

Install the AbacatePay SDK using your preferred package manager.

```bash
npm install @abacatepay/sdk
```

```bash
yarn add @abacatepay/sdk
```

```bash
pnpm add @abacatepay/sdk
```

```bash
bun add @abacatepay/sdk
```

--------------------------------

### Install @abacatepay/rest

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/rest.mdx

Install the REST client using your preferred package manager.

```bash
bun add @abacatepay/rest
# ou
pnpm add @abacatepay/rest
# ou
npm install @abacatepay/rest
```

--------------------------------

### Install AbacatePay Python SDK

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/python.mdx

Install the AbacatePay SDK using pip, poetry, or uv.

```bash
pip install abacatepay
```

```bash
poetry add abacatepay
```

```bash
uv add abacatepay
```

--------------------------------

### Install @abacatepay/typebox

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/typebox.mdx

Install the package using your preferred package manager.

```bash
bun add @abacatepay/typebox
# or
pnpm add @abacatepay/typebox
# or
npm install @abacatepay/typebox
```

--------------------------------

### Install @abacatepay/zod

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/zod.mdx

Install the package using your preferred package manager.

```bash
bun add @abacatepay/zod
# ou
pnpm add @abacatepay/zod
# ou
npm install @abacatepay/zod
```

--------------------------------

### Complete Checkout Example

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/create.mdx

A comprehensive example demonstrating all available fields for checkout creation, including customer details, URLs, payment methods, card options, and metadata.

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

--------------------------------

### Checkout Example with Upsell

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/create.mdx

This example shows how to include an upsell product in the checkout. The upsell product must be standalone and active.

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

--------------------------------

### Install @abacatepay/types

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/types.mdx

Install the @abacatepay/types package using your preferred package manager.

```bash
bun add @abacatepay/types
# ou
pnpm add @abacatepay/types
# ou
npm install @abacatepay/types
```

--------------------------------

### Install AbacatePay Ruby SDK

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/ruby.mdx

Add the AbacatePay gem to your Gemfile and run bundle install, or install it directly using the gem command.

```bash
# Adicione ao seu Gemfile:
gem 'abacatepay-ruby'
# Depois execute:
bundle install
```

```bash
gem install abacatepay-ruby
```

--------------------------------

### Install @abacatepay/eslint-plugin

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/eslint.mdx

Install the ESLint plugin as a development dependency using your preferred package manager.

```bash
bun add -d @abacatepay/eslint-plugin
# or
pnpm add -d @abacatepay/eslint-plugin
# or
npm install -d @abacatepay/eslint-plugin
```

--------------------------------

### Install AbacatePay Theme with lazy.nvim

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/theme.mdx

Configure the AbacatePay theme for Neovim using the lazy.nvim plugin manager. This setup ensures the theme is loaded with high priority.

```lua
{
    "AbacatePay/vscode-theme",
    lazy = false,
    priority = 1000,
    config = function()
        vim.cmd.colorscheme("abacatepay-theme")
    end,
}
```

--------------------------------

### Checkout Example with Boleto Interest and Fine

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/create.mdx

This example configures interest and fine for late payments, applicable only when the payment method is BOLETO.

```json
{
  "methods": ["BOLETO"],
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "interest": { "value": 100 },
  "fine": { "value": 200, "type": "PERCENTAGE" }
}
```

--------------------------------

### Full Boleto Payment Request Example

Source: https://github.com/abacatepay/documentation/blob/main/pages/transparents/boleto.mdx

A comprehensive example of a Boleto payment request including description, customer details, and metadata.

```json
{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "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"
    }
  }
}
```

--------------------------------

### Install AbacatePay Theme in VS Code

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/theme.mdx

Install the official AbacatePay theme directly from the VS Code Marketplace using the command line.

```bash
code --install-extension abacatepay.abacatepay-theme
```

--------------------------------

### Refund Response Example

Source: https://github.com/abacatepay/documentation/blob/main/pages/changelog/index.mdx

This is an example of a successful refund response, indicating the refund is pending.

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

--------------------------------

### Install AbacatePay Rust SDK

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/rust.mdx

Add the AbacatePay Rust SDK and Tokio to your project dependencies using Cargo.

```bash
cargo add abacatepay-rust-sdk
cargo add tokio --features full
```

```toml
[dependencies]
abacatepay-rust-sdk = "0.1.0"
tokio = { version = "1", features = ["full"] }
```

--------------------------------

### Add Usage Units

Source: https://github.com/abacatepay/documentation/blob/main/pages/subscriptions/record-usage.mdx

Use this example to add units for a pay-as-you-go product. Ensure the `productId` refers to a product without a cycle.

```json
{
  "id": "subs_abc123xyz",
  "productId": "prod_api_calls",
  "units": 50,
  "action": "add"
}
```

--------------------------------

### Install AbacatePay PHP SDK

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/php.mdx

Use Composer to add the AbacatePay PHP SDK to your project dependencies.

```bash
composer require abacatepay/php-sdk
```

--------------------------------

### GET /products/list

Source: https://github.com/abacatepay/documentation/blob/main/pages/products/list.mdx

Retorna todos os produtos do seu catálogo. Requer a permissão `PRODUCT:READ`. Use `limit`, `after` e `before` para paginar.

```APIDOC
## GET /products/list

### Description
Retorna todos os produtos do seu catálogo. Requer a permissão `PRODUCT:READ`. Use `limit`, `after` e `before` para paginar.

### Method
GET

### Endpoint
/products/list

### Query Parameters
- **limit** (integer) - Optional - Define o número máximo de itens a serem retornados.
- **after** (string) - Optional - ID do último item da página anterior para paginação.
- **before** (string) - Optional - ID do primeiro item da página atual para paginação.

### Response
#### Success Response (200)
- **id** (string) - Identificador único do produto.
- **name** (string) - Nome do produto.
- **price** (number) - Preço do produto.
- **cycle** (integer) - Ciclo de faturamento do produto em meses.
- **trialDays** (integer) - Número de dias de teste gratuito.
- **status** (string) - Status do produto (ex: 'active', 'inactive').
```

--------------------------------

### Get Checkout

Source: https://github.com/abacatepay/documentation/blob/main/pages/start/introduction.mdx

Example of how to retrieve a specific checkout using its ID.

```APIDOC
## GET /checkouts/get

### Description
Retrieves a specific payment checkout by its ID.

### Method
GET

### Endpoint
/checkouts/get

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the checkout to retrieve.
```

--------------------------------

### Get Checkout Details

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

Retrieve the details of a specific checkout, including the number of installments chosen by the customer after payment.

```APIDOC
## GET /checkouts/get

### Description
Retrieves the details of a specific checkout.

### Method
GET

### Endpoint
/checkouts/get

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the checkout to retrieve.

### Response
#### Success Response (200)
- **data** (object) - Contains checkout details.
  - **id** (string) - The ID of the checkout.
  - **status** (string) - The current status of the checkout (e.g., "PAID").
  - **methods** (array) - Payment methods used for the checkout.
  - **installmentsCount** (integer | null) - The number of installments chosen by the customer. This field is populated after payment if installments were used; otherwise, it is null.

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

--------------------------------

### Instalar AbacatePay CLI com Go

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/overview.mdx

Instala a versão mais recente da AbacatePay CLI usando o gerenciador de pacotes Go. Recomendado para usuários com Go instalado.

```bash
go install github.com/AbacatePay/abacatepay-cli@latest
```

--------------------------------

### Create Product with Free Trial

Source: https://github.com/abacatepay/documentation/blob/main/pages/subscriptions/reference.mdx

Configure a free trial period for a subscription product by setting the 'trialDays' field. The customer is not charged during the trial, and the first charge occurs at the end of the trial period.

```json
POST /products/create
{
  "externalId": "plano-pro-trial",
  "name": "Plano Pro — 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7
}
```

--------------------------------

### Instalar gnome-keyring no Fedora

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/flags.mdx

Comando para instalar o pacote gnome-keyring em sistemas Fedora.

```bash
sudo dnf install gnome-keyring
```

--------------------------------

### Instalar gnome-keyring no Debian/Ubuntu

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/flags.mdx

Comando para instalar o pacote gnome-keyring em sistemas baseados em Debian ou Ubuntu.

```bash
sudo apt install gnome-keyring
```

--------------------------------

### Verificar Instalação da AbacatePay CLI

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/overview.mdx

Comando para verificar se a AbacatePay CLI foi instalada corretamente e exibir sua versão.

```bash
abacatepay --version
```

--------------------------------

### Create Product

Source: https://github.com/abacatepay/documentation/blob/main/pages/products/reference.mdx

Use the `/products/create` endpoint to create a new product. Products can be one-time payments or subscriptions, and can optionally include a downloadable file. The currency is always BRL.

```APIDOC
## POST /products/create

### Description
Creates a new product that can be used in charges. Products can be one-time payments or subscriptions, and can optionally include a downloadable file.

### Method
POST

### Endpoint
/products/create

### Parameters
#### Request Body
- **externalId** (string) - Required - Unique identifier for the product in your system.
- **name** (string) - Required - The name of the product.
- **price** (integer) - Required - The price in cents.
- **currency** (string) - Required - The currency, always 'BRL'.
- **description** (string) - Optional - A description of the product.
- **imageUrl** (string | null) - Optional - URL of the product image.
- **fileUrl** (string) - Optional - URL of a PDF file to be associated with the product. Maximum size is 20 MB. If provided, the `hasFile` field in the response will be true.
- **cycle** (string | null) - Optional - Defines the subscription cycle. Accepted values are `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`. If omitted or null, the product is a one-time payment.
- **trialDays** (integer) - Optional - The number of free trial days for a subscription product. Must be between 1 and 90. Requires `cycle` to be set.

### Request Example (One-time product)
```json
{
  "externalId": "prod-123",
  "name": "Produto Exemplo",
  "price": 10000,
  "currency": "BRL",
  "description": "Descrição do produto",
  "imageUrl": null
}
```

### Request Example (Subscription product)
```json
{
  "externalId": "prod-assinatura-1",
  "name": "Plano Mensal",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY"
}
```

### Request Example (Subscription product with free trial)
```json
{
  "externalId": "prod-assinatura-trial",
  "name": "Plano Mensal com 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7
}
```

### Request Example (Product with downloadable file)
```json
{
  "externalId": "ebook-001",
  "name": "E-book: Guia Completo",
  "price": 4990,
  "currency": "BRL",
  "fileUrl": "https://exemplo.com/guia-completo.pdf"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created product details.
  - **id** (string) - The unique identifier for the product in AbacatePay.
  - **externalId** (string) - The unique identifier for the product in your system.
  - **name** (string) - The name of the product.
  - **description** (string | null) - The description of the product.
  - **imageUrl** (string | null) - The URL of the product image.
  - **hasFile** (boolean) - Indicates if the product has a downloadable file linked (`true` or `false`).
  - **price** (integer) - The price of the product in cents.
  - **currency** (string) - The currency of the product (always 'BRL').
  - **status** (string) - The status of the product (e.g., 'ACTIVE').
  - **cycle** (string | null) - The subscription cycle (`WEEKLY`, `MONTHLY`, etc.), or null for one-time products.
  - **trialDays** (integer | null) - The number of free trial days, if applicable.
  - **createdAt** (string) - The timestamp when the product was created.
  - **updatedAt** (string) - The timestamp when the product was last updated.
- **success** (boolean) - Indicates if the operation was successful.
- **error** (object | null) - Contains error details if the operation failed.

### Response Example
```json
{
  "data": {
    "id": "prod_abc123xyz",
    "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",
    "cycle": "MONTHLY",
    "trialDays": 7
  },
  "success": true,
  "error": null
}
```
```

--------------------------------

### Instalar AbacatePay CLI com Homebrew

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/overview.mdx

Instala a AbacatePay CLI usando o Homebrew em sistemas macOS ou Linux. Requer que o Homebrew esteja instalado.

```bash
brew install --build-from-source github.com/AbacatePay/abacatepay-cli
```

--------------------------------

### Produto de assinatura com período de teste gratuito

Source: https://github.com/abacatepay/documentation/blob/main/pages/products/create.mdx

Create a subscription product with a free trial period by setting the 'trialDays' field. This requires the 'cycle' field to be defined, and the trial duration must be between 1 and 90 days. Customers are not charged during the trial.

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

--------------------------------

### Example of Unstable Field Usage

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/types.mdx

Fields marked with @unstable are inferred from official examples and may change without notice.

```typescript
WebhookWithdrawDoneEvent.billing.kind // @unstable
```

--------------------------------

### Install AbacatePay Theme with packer.nvim

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/theme.mdx

Configure the AbacatePay theme for Neovim using the packer.nvim plugin manager. The theme is set after installation.

```lua
use({
    "AbacatePay/vscode-theme",
        config = function()
        vim.cmd.colorscheme("abacatepay-theme")
    end,
})
```

--------------------------------

### Abrir Documentação da CLI

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/utils.mdx

Use `abacatepay docs` para abrir a documentação oficial da CLI no seu navegador.

```bash
abacatepay docs
```

--------------------------------

### Basic REST Client Usage

Source: https://github.com/abacatepay/documentation/blob/main/pages/ecosystem/rest.mdx

Initialize the REST client with your API key and make a POST request to simulate a Pix payment.

```typescript
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);
```

--------------------------------

### Accept Only Card Installments

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

To exclusively accept card installments, remove other payment methods like PIX from the `methods` array and set `maxInstallments`.

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

--------------------------------

### Iniciar Listener de Webhooks

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/overview.mdx

Inicia o listener de webhooks da AbacatePay CLI, encaminhando eventos para a URL especificada. Alternativamente, pode ser executado sem argumentos para configurar o encaminhamento via menu interativo.

```bash
abacatepay listen --forward-to http://localhost:3000/webhooks/abacatepay
```

--------------------------------

### Create Checkout with Installments

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

Send the `card` object with the `maxInstallments` field to create a checkout that supports credit card installments. The value must be an integer between 1 and 12.

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

--------------------------------

### Gerenciamento de Múltiplas Contas com AbacatePay CLI

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/cases.mdx

Crie e alterne entre perfis para gerenciar diferentes contas ou ambientes (produção, sandbox, desenvolvimento) usando a AbacatePay CLI.

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

--------------------------------

### Confirm Installments Count After Payment

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

After a successful payment, the `installmentsCount` field in the checkout object will reflect the number of installments chosen by the customer. For one-time payments or other methods like PIX/Boleto, this value will be null.

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

--------------------------------

### Create Checkout with Installments

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

To enable installment payments, include the `card` object with the `maxInstallments` field when creating a checkout. The `maxInstallments` value must be an integer between 1 and 12. The `CARD` method must also be included in the `methods` array.

```APIDOC
## POST /checkouts/create

### Description
Creates a checkout session, allowing customers to pay in installments using a credit card.

### Method
POST

### Endpoint
/checkouts/create

### Parameters
#### Request Body
- **items** (array) - Required - List of items to be purchased.
- **methods** (array) - Required - Payment methods to be offered. Must include "CARD".
- **card** (object) - Optional - Configuration for card payments.
  - **maxInstallments** (integer) - Required if using installments - The maximum number of installments allowed (1-12).

### Request Example
```json
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "methods": ["CARD"],
  "card": {
    "maxInstallments": 12
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains checkout details.
  - **id** (string) - The ID of the created checkout.
  - **url** (string) - The URL for the customer to complete the payment.
  - **card** (object) - Card payment configuration.
    - **maxInstallments** (integer) - The maximum number of installments configured.
  - **installmentsCount** (integer | null) - The number of installments chosen by the customer (null if not applicable).

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

### Rules and Restrictions
- **Minimum per installment**: R$ 10.00. The total amount must be at least R$ 10.00 multiplied by the number of installments.
- **Maximum installments**: 12.
- **Mandatory method**: `CARD` must be present in the `methods` array.
- **Frequency**: Supported for `ONE_TIME` and `MULTIPLE_PAYMENTS`. Not supported for `SUBSCRIPTION`.

### Error Handling
- If the total amount is insufficient for the configured number of installments, the API returns an error: `"Total below minimum for Nx (R$10 per installment)"`.
```

--------------------------------

### Teste de Integração Local com AbacatePay CLI

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/cases.mdx

Use estes comandos para autenticar em modo de teste, iniciar um listener para webhooks e criar/simular pagamentos localmente.

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

--------------------------------

### Create Checkout

Source: https://github.com/abacatepay/documentation/blob/main/pages/start/introduction.mdx

Example of how to create a checkout using the AbacatePay SDK.

```APIDOC
## POST /checkouts/create

### Description
Creates a new payment checkout.

### Method
POST

### Endpoint
/checkouts/create

### Request Example
```json
{
  "items": [
    { "id": "pro", "quantity": 1 }
  ]
}
```

### Response
#### Success Response (200)
Returns a checkout object with details including ID, URL, amount, and status.

```json
{
   "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",
      "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
}
```
```

--------------------------------

### Get Payment Link

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment-links/reference.mdx

Retrieves a specific payment link by its ID.

```APIDOC
## GET /checkouts/get

### Description
Retrieves a specific payment link by its ID.

### Method
GET

### Endpoint
/checkouts/get

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the payment link to retrieve.
```

--------------------------------

### Autenticar com AbacatePay CLI

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/overview.mdx

Inicia o processo de login na AbacatePay CLI via OAuth. O navegador será aberto para autorização, e você precisará fornecer a URL do seu servidor local para recebimento de webhooks.

```bash
abacatepay login
```

--------------------------------

### Create First Billing Charge

Source: https://github.com/abacatepay/documentation/blob/main/pages/sdks/php.mdx

Use the BillingClient to create a one-time PIX billing charge with product details and return URLs. The `price` is in cents.

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

--------------------------------

### Cancel Subscription

Source: https://github.com/abacatepay/documentation/blob/main/pages/subscriptions/cancel.mdx

Cancels an active subscription immediately. Pending future installments are also cancelled.

```APIDOC
## POST /subscriptions/cancel

### Description
Cancels an active subscription immediately. Pending future installments are also cancelled.

### Method
POST

### Endpoint
/subscriptions/cancel

### Parameters
#### Request Body
- **id** (string) - Required - ID of the subscription (`subs_...`)

### Request Example
```json
{
  "id": "subs_abc123xyz"
}
```

### Response
#### Success Response (200)
- **data** (object) - The subscription object with status updated to CANCELLED.
- **success** (boolean) - Indicates if the operation was successful.
- **error** (object) - Contains error details if the operation failed.

#### Response Example
```json
{
  "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="Immediate Cancellation" horizontal>The cancellation is applied immediately (`cancelPolicy: NOW`). There is no grace period - the customer loses access immediately.</Warning>
```

--------------------------------

### Error Refund Response

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/refund.mdx

Example of an error response when a refund cannot be processed, indicating the specific error code.

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

--------------------------------

### Get Coupon by Code

Source: https://github.com/abacatepay/documentation/blob/main/pages/coupons/get.mdx

Fetches the details of a coupon using its unique code. Requires the COUPON:READ permission.

```APIDOC
## GET /coupons/get

### Description
Returns the data of a coupon by its `code`.

### Method
GET

### Endpoint
/coupons/get

### Query Parameters
- **code** (string) - Required - The unique code of the coupon to retrieve.

### Response
#### Success Response (200)
- **redeemsCount** (integer) - The number of times the coupon has been redeemed.
- **status** (string) - The current status of the coupon (e.g., 'active', 'inactive').
```

--------------------------------

### Checkout Response with Installments

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/installments.mdx

The checkout response will include the `card.maxInstallments` field if it was set during creation. The `installmentsCount` will be null until payment is completed.

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

--------------------------------

### Debug de Webhooks com AbacatePay CLI

Source: https://github.com/abacatepay/documentation/blob/main/pages/cli/cases.mdx

Capture detalhes de webhooks com o modo verbose e verifique assinaturas manualmente para diagnosticar problemas.

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

--------------------------------

### Minimum Checkout Example

Source: https://github.com/abacatepay/documentation/blob/main/pages/payment/create.mdx

This is the minimum required payload to create a checkout. It only includes the items list with product ID and quantity.

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

--------------------------------

### Checkout Disputed Event - Boleto

Source: https://github.com/abacatepay/documentation/blob/main/pages/webhooks/events/checkout.mdx

Example of a checkout.disputed event when the payment method was Boleto. The payerInformation object includes Boleto-specific fields.

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