> ## 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.
# Criar cobrança Boleto
> Cria um checkout transparente. Use `"method": "PIX"` para gerar um QR Code ou `"method": "BOLETO"` para emitir um boleto com PIX alternativo incluído.
Requer a permissão `CHECKOUT:READ`.
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.
Para cobrar via PIX, veja [Criar cobrança PIX](/pages/transparents/create).
***
## 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.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 `utm`:
```json theme={null}
{
"method": "BOLETO",
"data": {
"amount": 25000,
"customer": {
"name": "Mariana Costa",
"taxId": "987.654.321-00"
}
}
}
```
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,
"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,
"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" }
}
}
```
**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.
***
## 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.
```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": "2024-11-07T03:00:00.000Z",
"createdAt": "2024-11-04T14:22:10.381Z",
"updatedAt": "2024-11-04T14:22:10.381Z",
"metadata": {
"faturaId": "fatura-456",
"plano": "pro"
}
},
"success": true,
"error": null
}
```
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.
## OpenAPI
````yaml POST /transparents/create
openapi: 3.1.0
info:
title: API AbacatePay
description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
version: 1.0.0
servers:
- url: https://api.abacatepay.com/v2
description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
/transparents/create:
post:
summary: Criar Checkout Transparente
description: >-
Cria um checkout transparente. Use `"method": "PIX"` para gerar um QR
Code ou `"method": "BOLETO"` para emitir um boleto com PIX alternativo
incluído.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
method:
type: string
description: Método de pagamento.
enum:
- PIX
- BOLETO
default: PIX
example: PIX
data:
type: object
description: Dados da cobrança.
properties:
amount:
type: number
description: Valor da cobrança em centavos.
expiresIn:
type: number
description: PIX — expiração em segundos.
x-mint:
hidden: true
description:
type: string
maxLength: 500
description: Descrição da cobrança.
x-mint:
hidden: true
customer:
type: object
description: >
Dados do pagador. Obrigatório para BOLETO (`name` e
`taxId` sempre exigidos). Para PIX, se informado, todos
os campos são obrigatórios.
required:
- name
- taxId
additionalProperties: false
x-mint:
hidden: true
properties:
name:
type: string
example: Daniel Lima
taxId:
type: string
example: 123.456.789-01
email:
type: string
example: daniel_lima@abacatepay.com
cellphone:
type: string
example: (11) 4002-8922
externalId:
type: string
description: ID no seu sistema para idempotência.
x-mint:
hidden: true
interest:
description: >-
BOLETO — juros por atraso. Ignorado quando `method` é
`PIX`.
allOf:
- $ref: '#/components/schemas/BoletoInterest'
x-mint:
hidden: true
fine:
description: >-
BOLETO — multa por atraso. Ignorado quando `method` é
`PIX`.
allOf:
- $ref: '#/components/schemas/BoletoFine'
x-mint:
hidden: true
metadata:
type: object
additionalProperties: true
x-mint:
hidden: true
utm:
description: >-
Parâmetros opcionais de campanha (UTM). Objeto e campos
internos opcionais; valores enviados podem ser vistos no
dashboard.
allOf:
- $ref: '#/components/schemas/TransparentCreateUtm'
required:
- amount
additionalProperties: false
required:
- method
- data
additionalProperties: false
responses:
'200':
description: Checkout transparente criado com sucesso
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TransparentCharge'
error:
type: string
nullable: true
example: null
success:
$ref: '#/components/schemas/Success'
example:
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-34567890abcd5204000053039865802BR5914Mariana
Costa6009SAO PAULO62070503***6304F1C2
brCodeBase64: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
platformFee: 250
receiptUrl: null
expiresAt: '2024-11-07T03:00:00.000Z'
createdAt: '2024-11-04T14:22:10.381Z'
updatedAt: '2024-11-04T14:22:10.381Z'
metadata:
faturaId: fatura-456
plano: pro
error: null
success:
message: Checkout transparente criado com sucesso
'401':
description: Não autorizado. Falha na autenticação.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Token de autenticação inválido ou ausente.
security:
- bearerAuth: []
components:
schemas:
BoletoInterest:
type: object
description: >-
Juros por atraso aplicados ao boleto após o vencimento. Late interest
applied to the boleto after the due date. Aplica-se apenas a `method:
"BOLETO"`; ignorado nos demais métodos.
additionalProperties: false
required:
- value
properties:
value:
type: integer
minimum: 0
description: >-
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, sem juros.
Calculado pro rata die após o vencimento.
EN: Monthly late-interest rate in hundredths of a percent (`100` =
1%/month). Accrues pro rata die after the due date; `0` or omitted
disables interest.
example: 100
BoletoFine:
type: object
description: >-
Multa por atraso aplicada uma única vez após o vencimento do boleto.
One-time late fine applied after the due date. Aplica-se apenas a
`method: "BOLETO"`; ignorado nos demais métodos.
additionalProperties: false
required:
- value
- type
properties:
value:
type: integer
minimum: 0
description: >-
Quando `type = "PERCENTAGE"`: centésimos de percentual sobre o valor
do boleto (`200` = 2%). Quando `type = "FIXED"`: valor fixo em
centavos (`1000` = R$ 10,00). Quando `0` ou omitido, sem multa.
EN: With `type: "PERCENTAGE"`, value is in hundredths of a percent
(`200` = 2%). With `type: "FIXED"`, value is in cents (`1000` = R$
10.00). `0` or omitted disables the fine.
example: 200
type:
type: string
description: >-
Tipo da multa. `PERCENTAGE` aplica percentual sobre o valor do
boleto; `FIXED` aplica um valor fixo em centavos.
EN: Fine type. `PERCENTAGE` applies a percent of the boleto amount;
`FIXED` applies a fixed amount in cents.
enum:
- PERCENTAGE
- FIXED
example: PERCENTAGE
TransparentCreateUtm:
type: object
description: >
Parâmetros UTM opcionais para campanha. Objeto inteiro e campos internos
opcionais; podem ser consultados no dashboard.
additionalProperties: false
properties:
source:
type: string
description: 'Opcional — ex.: origem ou fonte da campanha.'
medium:
type: string
description: 'Opcional — ex.: meio ou canal.'
campaign:
type: string
description: Opcional — nome ou identificador da campanha.
term:
type: string
description: 'Opcional — ex.: palavras-chave de anúncio.'
content:
type: string
description: 'Opcional — ex.: variante criativa ou conteúdo.'
TransparentCharge:
type: object
description: >-
Dados da cobrança retornados pelo checkout transparente. Os campos
`brCode` e `brCodeBase64` são sempre retornados (PIX direto ou PIX
alternativo do boleto). Para boleto também retornam `barCode` e `url`.
properties:
id:
type: string
description: Identificador único da cobrança.
example: bole_k8pqr2mnvx
amount:
type: number
description: Valor a ser pago em centavos.
example: 25000
status:
type: string
description: Status atual da cobrança.
enum:
- PENDING
- EXPIRED
- CANCELLED
- PAID
- UNDER_DISPUTE
- REFUNDED
- REDEEMED
- APPROVED
- FAILED
example: PENDING
devMode:
type: boolean
description: Indica se a cobrança foi criada em ambiente sandbox.
example: false
brCode:
type: string
description: >-
Código copia-e-cola do QR Code PIX. Para `method: "BOLETO"`,
representa o PIX alternativo da mesma cobrança.
example: >-
00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Daniel
Lima6009SAO PAULO62070503***6304F1C2
brCodeBase64:
type: string
description: >-
Imagem em Base64 do QR Code PIX. Para `method: "BOLETO"`, representa
o PIX alternativo da mesma cobrança.
example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
barCode:
type: string
description: >-
Linha digitável do boleto para pagamento no app do banco. Retornado
quando `method` é `"BOLETO"`.
example: 23793.38128 60007.827263 37000.963779 4 10010000025000
url:
type: string
description: >-
URL para visualização e impressão do boleto. Retornado quando
`method` é `"BOLETO"`.
example: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto
platformFee:
type: number
description: Taxa da plataforma em centavos.
example: 250
interest:
nullable: true
description: >-
Juros por atraso configurados para o boleto. `null` para `method:
"PIX"` ou quando não foi configurado.
allOf:
- $ref: '#/components/schemas/BoletoInterest'
fine:
nullable: true
description: >-
Multa por atraso configurada para o boleto. `null` para `method:
"PIX"` ou quando não foi configurada.
allOf:
- $ref: '#/components/schemas/BoletoFine'
receiptUrl:
type: string
nullable: true
description: >-
URL do comprovante de pagamento. Preenchido após o pagamento ser
confirmado; `null` enquanto a cobrança estiver pendente.
example: null
expiresAt:
type: string
description: >-
Data de expiração da cobrança (ISO 8601). Para boleto, representa a
data de vencimento.
example: '2024-11-07T03:00:00.000Z'
createdAt:
type: string
description: Data de criação.
example: '2024-11-04T14:22:10.381Z'
updatedAt:
type: string
description: Data da última atualização.
example: '2024-11-04T14:22:10.381Z'
metadata:
type: object
description: Campos livres enviados na requisição.
additionalProperties: true
Success:
type: boolean
description: Se a requisição obteve sucesso ou não.
example: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Todas as requisições devem incluir sua chave de API no header
Authorization usando o formato `Bearer `. Sem esse
header a requisição será rejeitada.
Saiba mais sobre como criar e usar chaves de API na [documentação de
autenticação](/pages/authentication).
````