---
title: "POST /public_api/payments/"
method: POST
path: "/public_api/payments/"
tags: ["payments"]
---

# POST /public_api/payments/

`POST /public_api/payments/`

Cria uma cobrança transacional Pix ou Boleto vinculada a um produto e oferta da
conta autenticada. O split entre produtor, coprodutores e afiliados é resolvido
internamente pela Cakto.

## Headers

- `X-Idempotency-Key` string, required

## Request body

- PublicPaymentCreateRequest
  - `productId` string, required — `short_id` ou `id` (UUID) do produto. O produto deve pertencer ao tenant autenticado e estar ativo.
  - `paymentMethod` 'pix' | 'pix_auto' | 'boleto', required — Método de pagamento da cobrança.
  - `customer` PublicPaymentCustomer, required
    - `name` string, required — Nome completo do pagador.
    - `email` string, email, required — E-mail do pagador.
    - `phone` string, required — Telefone do pagador no formato E.164 (`5511999999999`).
    - `fingerprint` string, required — Identificador estável do dispositivo/sessão do pagador. Deve ser uma string não vazia, consistente para a mesma sessão.
    - `docType` 'cpf' | 'cnpj' — Tipo de documento do pagador. Apesar do contrato aceitar omitir, envie sempre para cobranças no Brasil (necessário para nota fiscal).
    - `docNumber` string — Número do documento, somente dígitos.
    - `birthDate` string, date — Data de nascimento (`YYYY-MM-DD`).
    - `ip` string — IP do pagador. Quando omitido, a Cakto utiliza o IP de origem da requisição.
  - `items` PublicPaymentItem[], required — Deve conter exatamente um item.
    - `offerId` string, required — `id` da oferta cadastrada. A oferta deve estar com status `active` e pertencer ao `productId` informado.
    - `quantity` integer — Quantidade vendida da oferta.
    - `offerType` 'main' — Tipo da oferta dentro do funil. Apenas `main` é aceito.
  - `address` PublicPaymentAddress
    - `country` string — País no formato ISO 3166-1 alpha-2.
    - `state` string — UF (duas letras).
    - `city` string
    - `zipcode` string — CEP, somente dígitos.
    - `street` string
    - `neighborhood` string
    - `number` string
    - `complement` string
  - `affiliateShortId` string — `short_id` do afiliado responsável pela venda. Deve estar com status `active` e cadastrado para o produto informado.
  - `coupon` string — Código do cupom de desconto.
  - `metadata` PublicPaymentMetadata
    - `utm_source` string
    - `utm_medium` string
    - `utm_campaign` string
    - `utm_term` string
    - `utm_content` string
    - `sck` string
  - `dueDate` string, date — Somente para `boleto`. Data de vencimento (`YYYY-MM-DD`). Deve ser futura e respeitar o `ticketExpiration` do produto.
  - `pixExpiresIn` integer — Somente para `pix` e `pix_auto`. Expiração do código Pix em segundos. Mínimo 60. Deve respeitar o `pixExpiresIn` do produto.

## Response `201`

Cobrança criada com sucesso.

- PublicPaymentResponse
  - `id` string — Identificador único do pedido criado.
  - `refId` string — Código curto de referência do pedido.
  - `status` string — Status inicial do pedido. Para Pix e Boleto, normalmente `waiting_payment`.
  - `paymentMethod` 'pix' | 'pix_auto' | 'boleto'
  - `amount` string — Valor final cobrado, em reais, como string decimal.
  - `baseAmount` string, nullable
  - `discount` string, nullable
  - `fees` string, nullable
  - `externalId` string, nullable — Identificador da transação no provedor.
  - `checkoutUrl` string, nullable — URL do checkout Cakto.
  - `createdAt` string, date-time
  - `product` PublicPaymentResponseProduct
    - `id` string
    - `short_id` string
    - `name` string
  - `offer` PublicPaymentResponseOffer
    - `id` string, nullable
    - `name` string, nullable
    - `price` number, nullable
  - `pix` PublicPaymentResponsePix
    - `qrCode` string — Código copia-e-cola (BR Code).
    - `qrCodeBase64` string — Imagem do QR Code em base64 (`data:image/png;base64,...`).
    - `expirationDate` string, date-time — Data e hora de expiração do QR Code.
  - `boleto` PublicPaymentResponseBoleto
    - `barcode` string — Linha digitável do boleto.
    - `pdfUrl` string — URL do PDF do boleto.
    - `dueDate` string, date — Data de vencimento.

## Other responses

- `400` — Erro de validação no payload ou no header de idempotência.
- `401` — Request não autenticado devido à ausência ou invalidez do token.
- `403` — Chave de API sem o escopo `payments`.
- `409` — Conflito de idempotência (chave reutilizada com payload diferente ou requisição em curso).
- `429` — Rate limit excedido (por IP ou por token).

---

[API](https://skmtc.dev/cakto/apis/cakto-api.md) · [All operations](https://skmtc.dev/cakto/apis/cakto-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cakto/cakto-api/revisions/cba77b0560b5/schema)