---
title: "Criar um Checkout"
method: POST
path: "/checkouts/create"
---

# Criar um Checkout

`POST /checkouts/create`

Cria um Checkout para o cliente realizar o pagamento.

## Request body

- object
  - `items` object[], required — Lista de itens incluídos na cobrança. Este é o único campo obrigatório — o valor total é calculado a partir destes itens.
    - `id` string, required — ID público do produto na sua loja.
    - `quantity` integer, required — Quantidade deste item.
  - `methods` string[] — Métodos de pagamento disponíveis. Padrão ["PIX", "CARD"].
  - `returnUrl` string, uri — URL para onde o cliente será redirecionado ao clicar em "Voltar" no checkout.
  - `completionUrl` string, uri — URL para onde o cliente será redirecionado após o pagamento ser concluído.
  - `customerId` string — ID de um cliente já cadastrado na sua loja. Se informado, o checkout será pré-preenchido com os dados deste cliente. **Exemplo**: `"cust_abcdefghij"`
  - `coupons` string[] — Lista de cupons que podem ser utilizados nesta cobrança. **Exemplo**: `["ABKT10", "ABKT5", "PROMO10"]`
  - `externalId` string — ID da cobrança no seu sistema, caso queira manter uma referência própria. **Exemplo**: `"seu_id_123"`
  - `upSellProductId` string — 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"`
  - `dueDate` string, date — Data de vencimento do boleto no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Opcional. Só é válido quando `methods` inclui `BOLETO`; ignorado nos demais métodos. Se omitido, o vencimento padrão é de 3 dias úteis. Não pode ser data no passado. Máximo de 365 dias no futuro.
  - `interest` BoletoInterest — 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.
    - `value` integer, required — 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.
  - `fine` BoletoFine — 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.
    - `value` integer, required — 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.
    - `type` 'PERCENTAGE' | 'FIXED', required — 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.
  - `metadata` object — Metadados adicionais da cobrança. Campo livre para a sua aplicação. **Exemplo**: ```json { "source": "landing-page-black-friday", "campaign": "BF-2025" } ```

## Response `200`

Cobrança criada com sucesso.

- object
  - `data` Billing
    - `id` string — Identificador único do Checkout.
    - `externalId` string, nullable — ID do Checkout no seu sistema.
    - `url` string, uri — URL onde o usuário pode concluir o pagamento.
    - `amount` number — Valor total a ser pago em centavos.
    - `paidAmount` number, nullable — Valor já pago em centavos. Null se ainda não foi pago.
    - `items` object[] — Lista de itens no Checkout.
      - `id` string — ID do produto.
      - `quantity` integer — Quantidade do item.
    - `status` 'PENDING' | 'EXPIRED' | 'CANCELLED' | 'PAID' | 'REFUNDED' — Status atual do Checkout.
    - `coupons` string[] — Lista de cupons aplicados no Checkout.
    - `devMode` boolean — Indica se a cobrança foi criada em ambiente de testes.
    - `customerId` string, nullable — ID do cliente associado ao Checkout.
    - `returnUrl` string, uri, nullable — URL para onde o cliente será redirecionado ao clicar em "Voltar".
    - `completionUrl` string, uri, nullable — URL para onde o cliente será redirecionado após o pagamento.
    - `receiptUrl` string, uri, nullable — URL do comprovante de pagamento.
    - `upSellProductId` string, nullable — ID do produto de upsell vinculado ao Checkout. Null se nenhum produto de upsell foi informado na criação.
    - `installmentsCount` integer, nullable — 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).
    - `dueDate` string, date, nullable — Data de vencimento do boleto (`YYYY-MM-DD`). `null` quando não foi configurada ou quando o método de pagamento não é BOLETO.
    - `interest` BoletoInterest — 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.
      - `value` integer, required — 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.
    - `fine` BoletoFine — 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.
      - `value` integer, required — 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.
      - `type` 'PERCENTAGE' | 'FIXED', required — 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.
    - `metadata` object — Metadados adicionais do Checkout.
    - `createdAt` string, date-time — Data e hora de criação do Checkout.
    - `updatedAt` string, date-time — Data e hora da última atualização do Checkout.
  - `error` string, nullable
  - `success` boolean — Se a requisição obteve sucesso ou não.

## Other responses

- `401` — Não autorizado. Falha na autenticação.

---

[API](https://skmtc.net/abacatepay/apis/api-abacatepay.md) · [All operations](https://skmtc.net/abacatepay/apis/api-abacatepay/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/abacatepay/api-abacatepay/revisions/6b89a7fa70f5/schema)