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.

POST /transparents/create

Criar Checkout Transparente

cURL

curl --request POST \
  --url https://api.abacatepay.com/v2/transparents/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "method": "PIX",
  "data": {
    "amount": 123,
    "expiresIn": 123,
    "description": "<string>",
    "externalId": "<string>",
    "metadata": {},
    "utm": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>",
      "content": "<string>"
    }
  }
}
'

200

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

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.

---

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:

{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00"
    }
  }
}

Com utm:

{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00"
    },
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "boleto_teste"
    }
  }
}

---

Requisição

{
  "method": "BOLETO",
  "data": {
    "amount": 25000,
    "description": "Fatura de serviço mensal",
    "customer": {
      "name": "Mariana Costa",
      "taxId": "987.654.321-00",
      "email": "[e-mail]",
      "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:

{
  "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%:

{
  "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.

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

Authorizations

Authorization · string · header · required

Todas as requisições devem incluir sua chave de API no header Authorization usando o formato Bearer <abacatepay-api-key>. Sem esse header a requisição será rejeitada.

Saiba mais sobre como criar e usar chaves de API na documentação de autenticação.

Body

application/json

method · enum<string> · default: PIX · required

Método de pagamento.

Available options: PIX, BOLETO

Example:

"PIX"

data · object · required

Dados da cobrança.

Show child attributes

Response

200

application/json

Checkout transparente criado com sucesso

data · object

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.

Show child attributes

error · string | null

Example:

null

success · boolean

Se a requisição obteve sucesso ou não.

Example:

true