Criar Cobrança Pix

curl --request POST \
  --url https://api.cakto.com.br/public_api/payments/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "productId": "19bruPi",
  "paymentMethod": "pix",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone": "5511999999999",
    "fingerprint": "fp_2f8c1e5e-1aa8-4d4d-b9d4-19f7e5e0e1ab",
    "docType": "cpf",
    "docNumber": "12345678909"
  },
  "items": [
    {
      "offerId": "77BcHrY",
      "quantity": 1,
      "offerType": "main"
    }
  ],
  "pixExpiresIn": 3600,
  "metadata": {
    "utm_source": "facebook",
    "utm_campaign": "lancamento-mai"
  }
}
'

{
  "id": "10bb51bb-03be-473c-b4c5-3490765c4096",
  "refId": "CATDiPp",
  "status": "waiting_payment",
  "paymentMethod": "pix",
  "amount": "49.90",
  "baseAmount": "49.90",
  "discount": "0.00",
  "fees": "0.00",
  "externalId": "7e1f0d37-9b5f-4f1f-bf7c-2bd4f97f9d23",
  "checkoutUrl": "https://pay.cakto.com.br/CATDiPp",
  "createdAt": "2026-04-28T23:30:00-03:00",
  "product": {
    "id": "cd287b31-d4b7-4e94-858a-66e05ce2f4a2",
    "short_id": "19bruPi",
    "name": "Cakto Pro Plan"
  },
  "offer": {
    "id": "77BcHrY",
    "name": "Plano Mensal",
    "price": 49.9
  },
  "pix": {
    "qrCode": "00020126360014BR.GOV.BCB.PIX0114+5511999999999...",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "expirationDate": "2026-04-29T01:30:00-03:00"
  }
}

POST

public_api

payments

curl --request POST \
  --url https://api.cakto.com.br/public_api/payments/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "productId": "19bruPi",
  "paymentMethod": "pix",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone": "5511999999999",
    "fingerprint": "fp_2f8c1e5e-1aa8-4d4d-b9d4-19f7e5e0e1ab",
    "docType": "cpf",
    "docNumber": "12345678909"
  },
  "items": [
    {
      "offerId": "77BcHrY",
      "quantity": 1,
      "offerType": "main"
    }
  ],
  "pixExpiresIn": 3600,
  "metadata": {
    "utm_source": "facebook",
    "utm_campaign": "lancamento-mai"
  }
}
'

{
  "id": "10bb51bb-03be-473c-b4c5-3490765c4096",
  "refId": "CATDiPp",
  "status": "waiting_payment",
  "paymentMethod": "pix",
  "amount": "49.90",
  "baseAmount": "49.90",
  "discount": "0.00",
  "fees": "0.00",
  "externalId": "7e1f0d37-9b5f-4f1f-bf7c-2bd4f97f9d23",
  "checkoutUrl": "https://pay.cakto.com.br/CATDiPp",
  "createdAt": "2026-04-28T23:30:00-03:00",
  "product": {
    "id": "cd287b31-d4b7-4e94-858a-66e05ce2f4a2",
    "short_id": "19bruPi",
    "name": "Cakto Pro Plan"
  },
  "offer": {
    "id": "77BcHrY",
    "name": "Plano Mensal",
    "price": 49.9
  },
  "pix": {
    "qrCode": "00020126360014BR.GOV.BCB.PIX0114+5511999999999...",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "expirationDate": "2026-04-29T01:30:00-03:00"
  }
}

Visão geral

Este endpoint gera uma cobrança Pix e devolve o QR Code que deve ser apresentado ao cliente final.

Retorna qrCode (código copia-e-cola) e qrCodeBase64 para exibição imediata.
Use pixExpiresIn para definir o tempo de expiração do QR Code.

O split financeiro (produtor, coprodutores e afiliados) é aplicado automaticamente a partir das configurações do painel — sua aplicação não precisa enviar dados financeiros.

Autenticação

Todas as requisições exigem um token OAuth2 válido obtido em POST /public_api/token/.

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <access_token>`.
`Content-Type`	Sim	`application/json`.
`X-Idempotency-Key`	Sim	Identificador único da cobrança (até 255 caracteres). Recomendado UUID v4.

Escopo

write payments

A Chave de API utilizada deve ter o escopo payments habilitado. Configure no Painel Cakto.

Idempotência

O header X-Idempotency-Key é obrigatório e permite reenviar a mesma requisição com segurança em caso de instabilidade de rede, sem gerar cobranças duplicadas.

Reuso com payload idêntico

A resposta original é devolvida (mesmo id e mesmo status HTTP). A cobrança não é recriada. Janela de retenção: 24 horas.

Reuso com payload diferente

Resposta 409 Conflict com a mensagem Header X-Idempotency-Key reutilizado com payload diferente. Use uma nova chave para a nova cobrança.

Reuso enquanto a requisição original ainda processa

Resposta 409 Conflict com a mensagem Requisição idempotente em processamento. Aguarde a primeira finalizar.

Falha do servidor (5xx)

A chave é liberada automaticamente. A próxima retentativa com o mesmo header executa uma cobrança nova.

Gere a chave antes de chamar o endpoint e persista-a junto da operação de negócio. Use a mesma chave em todas as retentativas dessa operação.

Rate limit

Critério	Padrão
Por IP de origem	60 requisições / minuto
Por token de acesso	120 requisições / minuto

Ao exceder qualquer um dos limites, a resposta é 429 Too Many Requests com o header Retry-After indicando os segundos restantes.

Corpo da requisição

Resumo dos campos

Campo	Tipo	Obrigatório
`productId`	string	Sim
`paymentMethod`	`"pix"`	Sim
`customer`	object	Sim
`customer.name`	string	Sim
`customer.email`	string	Sim
`customer.phone`	string	Sim
`customer.fingerprint`	string	Sim
`customer.docType`	enum (`cpf`, `cnpj`)	Não (obrigatório na prática)
`customer.docNumber`	string	Não (obrigatório na prática)
`customer.birthDate`	string (ISO 8601)	Não
`customer.ip`	string	Não
`items` (exatamente 1 item)	array	Sim
`items[].offerId`	string	Sim
`items[].quantity`	integer	Não (default `1`)
`items[].offerType`	enum (`main`)	Não (default `main`)
`address`	object	Não (obrigatório se o produto exige entrega física)
`affiliateShortId`	string	Não
`coupon`	string	Não
`metadata`	object	Não
`pixExpiresIn`	integer (segundos)	Não (respeita o limite do produto)
`antifraudProfilingAttemptReference`	string	Sim

Detalhamento dos campos

productId

string

required

Identificador do produto da sua conta. Aceita o short_id (ex.: 19bruPi) ou o id em formato UUID. O produto deve pertencer ao tenant autenticado e estar ativo.

paymentMethod

enum<string>

required

Deve ser "pix" para cobranças Pix transacionais.

customer

object

required

Dados do pagador.

Show Campos

customer.name

string

required

Nome completo do pagador.

customer.email

string

required

E-mail do pagador.

customer.phone

string

required

Telefone do pagador no formato E.164 (5511999999999).

customer.fingerprint

string

required

Identificador estável do dispositivo/sessão do pagador. Deve ser uma string não vazia e consistente para a mesma sessão.

customer.docType

enum<string>

Tipo de documento do pagador. Valores aceitos: cpf, cnpj.

Em cobranças com produtores brasileiros, envie sempre docType e docNumber. Os dois campos são exigidos para emissão de nota fiscal e conformidade com adquirentes.

customer.docNumber

string

Número do documento (somente dígitos).

customer.birthDate

string

Data de nascimento no formato ISO 8601 (YYYY-MM-DD).

customer.ip

string

IP do pagador. Quando omitido, a Cakto utiliza o IP de origem da requisição.

items

array<object>

required

Itens da cobrança. Deve conter exatamente um item.

Show Campos do item

items[].offerId

string

required

id da oferta cadastrada. A oferta deve estar com status active e pertencer ao productId informado.

items[].quantity

integer

default:"1"

Quantidade vendida da oferta. Mínimo 1.

items[].offerType

enum<string>

default:"main"

Tipo da oferta dentro do funil. Apenas main é aceito.

address

object

Endereço do pagador. Obrigatório quando o produto exige entrega física.

Show Campos

address.country

string

default:"BR"

País no formato ISO 3166-1 alpha-2.

address.state

string

required

UF (duas letras), por exemplo SP.

address.city

string

required

address.zipcode

string

required

CEP, somente dígitos.

address.street

string

required

address.neighborhood

string

required

address.number

string

required

address.complement

string

affiliateShortId

string

short_id do afiliado responsável pela venda. Deve estar active e cadastrado para o produto.

coupon

string

Código do cupom de desconto. Até 255 caracteres.

metadata

object

Parâmetros de rastreio associados à cobrança.

Show Campos

metadata.utm_source

string

metadata.utm_medium

string

metadata.utm_campaign

string

metadata.utm_term

string

metadata.utm_content

string

metadata.sck

string

pixExpiresIn

integer

Expiração do código Pix em segundos. Mínimo 60. Deve respeitar o limite máximo configurado no produto (pixExpiresIn).

antifraudProfilingAttemptReference

string

required

Referência da sessão de profiling do antifraude (Nethone) gerada no front-end antes de iniciar o pagamento. Usada para correlacionar a análise de comportamento do usuário com a transação.

Resposta de sucesso

201 Created

string

Identificador único do pedido criado.

refId

string

Código curto de referência do pedido.

status

string

Status inicial do pedido. Normalmente waiting_payment.

paymentMethod

string

Método de pagamento confirmado: pix.

amount

string

Valor final cobrado, em reais, como string decimal.

baseAmount

string

Valor base da oferta, antes de descontos.

discount

string

Valor de desconto aplicado.

fees

string

Taxas aplicadas pela Cakto, já consolidadas.

externalId

string

Identificador da transação no provedor de pagamento.

checkoutUrl

string

URL do checkout Cakto, útil para reapresentar a cobrança ao cliente.

createdAt

string<date-time>

Timestamp ISO 8601 com fuso horário.

product

object

Resumo do produto associado.

Show Campos

product.id

string

product.short_id

string

product.name

string

offer

object

Resumo da oferta cobrada.

Show Campos

offer.id

string

offer.name

string

offer.price

number

pix

object

Dados do Pix gerado.

Show Campos

pix.qrCode

string

Código copia-e-cola (BR Code).

pix.qrCodeBase64

string

Imagem do QR Code em base64 (data:image/png;base64,...).

pix.expiresAt

string<date-time>

Data e hora de expiração do QR Code.

Exemplo de resposta

Pix

{
  "id": "10bb51bb-03be-473c-b4c5-3490765c4096",
  "refId": "CATDiPp",
  "status": "waiting_payment",
  "paymentMethod": "pix",
  "amount": "49.90",
  "baseAmount": "49.90",
  "discount": "0.00",
  "fees": "0.00",
  "externalId": "7e1f0d37-9b5f-4f1f-bf7c-2bd4f97f9d23",
  "checkoutUrl": "https://pay.cakto.com.br/CATDiPp",
  "createdAt": "2026-04-28T23:30:00-03:00",
  "product": {
    "id": "cd287b31-d4b7-4e94-858a-66e05ce2f4a2",
    "short_id": "19bruPi",
    "name": "Cakto Pro Plan"
  },
  "offer": {
    "id": "77BcHrY",
    "name": "Plano Mensal",
    "price": 49.9
  },
  "pix": {
    "qrCode": "00020126360014BR.GOV.BCB.PIX0114+5511999999999...",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "expiresAt": "2026-04-29T01:30:00-03:00"
  }
}

Respostas de erro

Código	Quando ocorre	Corpo de exemplo
`400`	Header `X-Idempotency-Key` ausente, vazio ou maior que 255 caracteres.	`{ "detail": "Header X-Idempotency-Key é obrigatório." }`
`400`	`productId` ausente, inválido ou de outro tenant.	`{ "productId": ["Produto não encontrado."] }`
`400`	`paymentMethod` ausente ou fora da lista aceita.	`{ "paymentMethod": ["Método de pagamento não suportado."] }`
`400`	Oferta inexistente, inativa ou de outro produto.	`{ "items": ["Oferta não encontrada para o produto informado."] }`
`400`	`pixExpiresIn` acima do limite do produto.	`{ "pixExpiresIn": ["A expiração do Pix excede o limite do produto (3600 segundo(s))."] }`
`400`	`antifraudProfilingAttemptReference` ausente.	`{ "antifraudProfilingAttemptReference": ["Este campo é obrigatório."] }`
`400`	Conta do produtor bloqueada.	`{ "detail": "Conta bloqueada." }`
`401`	Token ausente, inválido ou expirado.	`{ "detail": "As credenciais de autenticação não foram fornecidas." }`
`403`	Chave de API sem escopo `payments`.	`{ "detail": "Você não tem permissão para executar esta ação." }`
`409`	`X-Idempotency-Key` reutilizado com payload diferente.	`{ "detail": "Header X-Idempotency-Key reutilizado com payload diferente." }`
`409`	`X-Idempotency-Key` em processamento.	`{ "detail": "Requisição idempotente em processamento." }`
`429`	Rate limit excedido.	`{ "detail": "Request was throttled. Expected available in 60 seconds." }`

Erros 5xx indicam falha temporária da Cakto. A chave de idempotência é liberada automaticamente — a próxima retentativa executa a cobrança normalmente.

Exemplo de requisição

curl -X POST 'https://api.cakto.com.br/public_api/payments/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: 7b1a3d6e-9e4f-4f1f-bf7c-2bd4f97f9d23' \
  -d '{
    "productId": "19bruPi",
    "paymentMethod": "pix",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "5511999999999",
      "fingerprint": "fp_2f8c1e5e-1aa8-4d4d-b9d4-19f7e5e0e1ab",
      "docType": "cpf",
      "docNumber": "12345678909"
    },
    "items": [
      { "offerId": "77BcHrY", "quantity": 1, "offerType": "main" }
    ],
    "pixExpiresIn": 3600,
    "antifraudProfilingAttemptReference": "a3d90c10-c0c6-4c33-8af3-944f694ea633",
    "metadata": {
      "utm_source": "facebook",
      "utm_campaign": "lancamento-mai"
    }
  }'

Boas práticas

Gere uma chave de idempotência por intenção de compra, não por retentativa. Se o usuário recarregar o carrinho e mudar o item, gere uma nova chave.
Persista o id retornado junto à intenção de compra. Use-o para conciliar com webhooks e com GET /public_api/orders/{id}/.
Exiba o QR Code assim que receber a resposta — o campo qrCodeBase64 pode ser usado diretamente em uma tag <img>.
Não envie dados sensíveis em metadata. Os campos UTM e sck são propagados para webhooks e relatórios.

Authorizations

Authorization

string

header

required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Headers

X-Idempotency-Key

string

required

Identificador único da cobrança (até 255 caracteres). Recomendado UUID v4. Reuso com payload idêntico devolve a resposta original por 24h.

Maximum string length: 255

Body

application/json

productId

string

required

short_id ou id (UUID) do produto. O produto deve pertencer ao tenant autenticado e estar ativo.

paymentMethod

enum<string>

required

Método de pagamento da cobrança.

Available options:

pix,

pix_auto,

boleto

customer

object

required

Show child attributes

items

object[]

required

Deve conter exatamente um item.

Required array length: 1 element

Show child attributes

address

object

Show child attributes

affiliateShortId

string

short_id do afiliado responsável pela venda. Deve estar com status active e cadastrado para o produto informado.

Maximum string length: 40

coupon

string

Código do cupom de desconto.

Maximum string length: 255

metadata

object

Show child attributes

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.

Required range: x >= 60

Response

Cobrança criada com sucesso.

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

enum<string>

Available options:

pix,

pix_auto,

boleto

amount

string

Valor final cobrado, em reais, como string decimal.

baseAmount

string | null

discount

string | null

fees

string | null

externalId

string | null

Identificador da transação no provedor.

checkoutUrl

string | null

URL do checkout Cakto.

createdAt

string<date-time>

product

object

Show child attributes

offer

object

Show child attributes

pix

object

Presente apenas para pix e pix_auto.

Show child attributes

boleto

object

Presente apenas para boleto.

Show child attributes

Guia de Integração Criar Cobrança Pix Automático

​Visão geral

​Autenticação

​Escopo

​Idempotência

​Rate limit

​Corpo da requisição

​Resumo dos campos

​Detalhamento dos campos

​Resposta de sucesso

​Exemplo de resposta

​Respostas de erro

​Exemplo de requisição

​Boas práticas

Authorizations

Headers

Body

Response

Visão geral

Autenticação

Escopo

Idempotência

Rate limit

Corpo da requisição

Resumo dos campos

Detalhamento dos campos

Resposta de sucesso

Exemplo de resposta

Respostas de erro

Exemplo de requisição

Boas práticas