> ## 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 PIX
> 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 **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.
Para cobrar via Boleto, veja [Criar cobrança Boleto](/pages/transparents/boleto).
***
## 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
}
```
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.
## 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).
````