> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Referência
> 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.
## Criar checkout
Use `/checkouts/create`. O total é calculado a partir dos itens.
Só `items` é obrigatório (lista com `id` do produto e `quantity`).
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
}
```
Use a `url` retornada para levar o cliente ao checkout e concluir o pagamento.
## 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.
O produto referenciado em `upSellProductId` precisa estar com `status: ACTIVE` e **não pode ter `cycle`** (deve ser avulso, sem assinatura).
**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.
## 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.
Os campos só têm efeito quando o método de pagamento é `BOLETO`. Para `PIX` ou `CARD` são ignorados silenciosamente.
### `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).
**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.
**Exemplo — juros de 1% ao mês + multa de 2%:**
```json theme={null}
POST /checkouts/create
{
"methods": ["BOLETO"],
"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"],
"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.
```json theme={null}
{
"data": {
"id": "bill_abc123xyz",
"amount": 10000,
"status": "PENDING",
"interest": { "value": 100 },
"fine": { "value": 200, "type": "PERCENTAGE" },
...
},
"success": true,
"error": null
}
```