> ## 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 um Checkout
> Cria um Checkout para o cliente realizar o pagamento.
Gera uma página de pagamento hospedada. Você envia os produtos; a API devolve a `url` para redirecionar o cliente.
Só `items` é obrigatório — lista com `id` do produto e `quantity`.
**Exemplo mínimo:**
```json theme={null}
{
"items": [
{ "id": "prod_abc123xyz", "quantity": 1 }
]
}
```
**Exemplo completo:**
```json theme={null}
{
"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" }
}
```
**Exemplo com upsell:**
```json theme={null}
{
"items": [
{ "id": "prod_abc123xyz", "quantity": 1 }
],
"upSellProductId": "prod_bump456xyz"
}
```
**Exemplo com multa e juros (apenas BOLETO):**
```json theme={null}
{
"methods": ["BOLETO"],
"items": [
{ "id": "prod_abc123xyz", "quantity": 1 }
],
"interest": { "value": 100 },
"fine": { "value": 200, "type": "PERCENTAGE" }
}
```
Use `upSellProductId` para oferecer um produto adicional ao cliente após a conclusão do pagamento. O produto deve ser **avulso** (sem `cycle`) e estar com status `ACTIVE`. Veja a [referência completa de upsell](/pages/payment/reference#upsell).
Use `interest` e `fine` para configurar juros por atraso e multa caso o cliente pague depois do vencimento. Os campos só se aplicam a `methods: ["BOLETO"]` e são ignorados nos demais métodos. Veja a [referência completa](/pages/payment/reference#multa-e-juros-no-boleto).
Use `card.maxInstallments` (1–12) para permitir que o cliente parcele no cartão. O valor mínimo por parcela é R\$ 10,00. Veja a [doc completa de parcelamento](/pages/payment/installments).
Redirecione o cliente para `data.url` — é lá que ele finaliza o pagamento.
Para cobranças recorrentes use [Assinaturas](/pages/subscriptions/create). Para um link que múltiplos clientes podem pagar use [Links de pagamento](/pages/payment-links/create).
## OpenAPI
````yaml POST /checkouts/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:
/checkouts/create:
post:
summary: Criar um Checkout
description: Cria um Checkout para o cliente realizar o pagamento.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
additionalProperties: false
example:
items:
- id: prod-1234
quantity: 2
methods:
- PIX
- CARD
properties:
items:
type: array
description: >
Lista de itens incluídos na cobrança.
Este é o único campo obrigatório — o valor total é calculado
a partir destes itens.
minItems: 1
items:
type: object
additionalProperties: false
required:
- id
- quantity
properties:
id:
type: string
description: ID público do produto na sua loja.
example: prod-1234
quantity:
type: integer
description: Quantidade deste item.
minimum: 1
example: 2
methods:
type: array
description: Métodos de pagamento disponíveis. Padrão ["PIX", "CARD"].
items:
type: string
enum:
- PIX
- CARD
minItems: 1
default:
- PIX
- CARD
x-mint:
hidden: true
returnUrl:
type: string
format: uri
description: >-
URL para onde o cliente será redirecionado ao clicar em
"Voltar" no checkout.
x-mint:
hidden: true
completionUrl:
type: string
format: uri
description: >-
URL para onde o cliente será redirecionado após o pagamento
ser concluído.
x-mint:
hidden: true
customerId:
type: string
description: >
ID de um cliente já cadastrado na sua loja.
Se informado, o checkout será pré-preenchido com os dados
deste cliente.
**Exemplo**: `"cust_abcdefghij"`
x-mint:
hidden: true
coupons:
type: array
description: |
Lista de cupons que podem ser utilizados nesta cobrança.
**Exemplo**: `["ABKT10", "ABKT5", "PROMO10"]`
items:
type: string
maxItems: 50
x-mint:
hidden: true
externalId:
type: string
description: >
ID da cobrança no seu sistema, caso queira manter uma
referência própria.
**Exemplo**: `"seu_id_123"`
x-mint:
hidden: true
upSellProductId:
type: string
description: >
ID de um produto avulso (sem `cycle`) a ser ofertado como
upsell após a conclusão do pagamento.
O produto deve estar com `status: ACTIVE` e **não pode ter
`cycle`** — apenas produtos de pagamento único são aceitos.
**Exemplo**: `"prod_bump456xyz"`
x-mint:
hidden: true
interest:
description: >-
Juros por atraso, aplicados apenas quando `methods` inclui
`BOLETO`. Ignorado para PIX/CARD.
allOf:
- $ref: '#/components/schemas/BoletoInterest'
x-mint:
hidden: true
fine:
description: >-
Multa por atraso, aplicada apenas quando `methods` inclui
`BOLETO`. Ignorado para PIX/CARD.
allOf:
- $ref: '#/components/schemas/BoletoFine'
x-mint:
hidden: true
metadata:
type: object
description: >
Metadados adicionais da cobrança. Campo livre para a sua
aplicação.
**Exemplo**:
```json
{
"source": "landing-page-black-friday",
"campaign": "BF-2025"
}
```
additionalProperties: true
x-mint:
hidden: true
responses:
'200':
description: Cobrança criada com sucesso.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Billing'
error:
type: string
nullable: true
example: null
success:
$ref: '#/components/schemas/Success'
'401':
description: Não autorizado. Falha na autenticação.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Motivo da falha na autenticação.
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
Billing:
type: object
properties:
id:
type: string
description: Identificador único do Checkout.
example: bill_abc123xyz
externalId:
type: string
nullable: true
description: ID do Checkout no seu sistema.
example: pedido-123
url:
type: string
format: uri
description: URL onde o usuário pode concluir o pagamento.
example: https://app.abacatepay.com/pay/bill_abc123xyz
amount:
type: number
description: Valor total a ser pago em centavos.
example: 10000
paidAmount:
type: number
nullable: true
description: Valor já pago em centavos. Null se ainda não foi pago.
example: null
items:
type: array
description: Lista de itens no Checkout.
items:
type: object
properties:
id:
type: string
description: ID do produto.
example: prod_456
quantity:
type: integer
description: Quantidade do item.
example: 2
status:
type: string
description: Status atual do Checkout.
enum:
- PENDING
- EXPIRED
- CANCELLED
- PAID
- REFUNDED
example: PENDING
coupons:
type: array
description: Lista de cupons aplicados no Checkout.
items:
type: string
example: []
devMode:
type: boolean
description: Indica se a cobrança foi criada em ambiente de testes.
example: false
customerId:
type: string
nullable: true
description: ID do cliente associado ao Checkout.
example: null
returnUrl:
type: string
format: uri
nullable: true
description: URL para onde o cliente será redirecionado ao clicar em "Voltar".
example: null
completionUrl:
type: string
format: uri
nullable: true
description: URL para onde o cliente será redirecionado após o pagamento.
example: null
receiptUrl:
type: string
format: uri
nullable: true
description: URL do comprovante de pagamento.
example: null
upSellProductId:
type: string
nullable: true
description: >-
ID do produto de upsell vinculado ao Checkout. Null se nenhum
produto de upsell foi informado na criação.
example: prod_bump456xyz
installmentsCount:
type: integer
nullable: true
description: >-
Número de parcelas do pagamento quando realizado via Cartão de
crédito com mais de uma parcela. `null` para pagamentos à vista ou
realizados por outros métodos (PIX, Boleto).
example: 3
interest:
nullable: true
description: >-
Juros por atraso configurados para o boleto. `null` quando não foi
configurado ou quando o método de pagamento não é BOLETO.
allOf:
- $ref: '#/components/schemas/BoletoInterest'
fine:
nullable: true
description: >-
Multa por atraso configurada para o boleto. `null` quando não foi
configurada ou quando o método de pagamento não é BOLETO.
allOf:
- $ref: '#/components/schemas/BoletoFine'
metadata:
type: object
description: Metadados adicionais do Checkout.
additionalProperties: true
example: {}
createdAt:
type: string
format: date-time
description: Data e hora de criação do Checkout.
example: '2024-11-04T18:38:28.573Z'
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do Checkout.
example: '2024-11-04T18:38:28.573Z'
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).
````