> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar Cobrança Pix Automático
> Inicia uma autorização de débito automático via Pix Automático. O cliente escaneia o QR Code para autorizar cobranças futuras recorrentes — não é uma cobrança pontual.
## Visão geral
O Pix Automático (`pix_auto`) é um método de pagamento recorrente baseado na especificação de Pix Automático do Banco Central do Brasil. O fluxo é diferente de uma cobrança Pix comum:
1. **Primeira cobrança:** sua aplicação chama este endpoint, a Cakto cria o contrato de recorrência junto à adquirente e retorna um QR Code. O cliente escaneia o QR Code no app do banco para **autorizar** os débitos automáticos futuros.
2. **Cobranças seguintes:** são debitadas automaticamente, sem ação do cliente.
A resposta inclui o campo `user_journey`, que indica a jornada de autorização definida pelo banco do cliente conforme a especificação do BCB (JORNADA\_1 a JORNADA\_4). Sua aplicação deve exibir o QR Code e aguardar o evento de webhook `purchase_approved` para confirmar a autorização.
Nenhum método Pix retorna imagem do QR Code. Apenas `qrCode` (copia-e-cola) está disponível na resposta — gere a imagem no seu lado a partir desse texto.
## Autenticação
Todas as requisições exigem um token OAuth2 válido obtido em [`POST /public_api/token/`](/authentication).
| Header | Obrigatório | Descrição |
| ------------------- | ----------- | -------------------------------------------------------------------------- |
| `Authorization` | Sim | `Bearer `. |
| `Content-Type` | Sim | `application/json`. |
| `X-Idempotency-Key` | Sim | Identificador único da cobrança (até 255 caracteres). Recomendado UUID v4. |
#### Escopo
```bash theme={null}
write payments
```
A Chave de API utilizada deve ter o escopo `payments` habilitado. Configure no [Painel Cakto](https://app.cakto.com.br/dashboard/cakto-api).
## Pré-requisitos
**Pix Automático exige conta Cakto Banking.** Pix Automático (`pix_auto`), Pix (`pix`) e Boleto (`boleto`) liquidam em uma conta Cakto Banking do produtor. Sem essa conta, a autorização é rejeitada com `400` antes de o contrato de recorrência ser criado na adquirente.
Cartão (`credit_card`, `threeDs`) **não** exige conta Banking e continua funcionando normalmente.
A conta precisa atender às quatro condições ao mesmo tempo:
* **abertura concluída** — a proposta chegou até o fim; conta em análise, em documentoscopia ou com proposta apenas aprovada ainda não vale;
* **ativa**;
* **principal** do produtor;
* **fora de encerramento** — encerramento solicitado ou concluído invalida a conta, mesmo que ela ainda apareça como ativa.
Confira o status em [Painel Cakto](https://app.cakto.com.br/dashboard). A API pública (`/public_api/`) não expõe o status dessa conta — não há endpoint para consultá-lo antes de cobrar.
## 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 criar contratos de recorrência duplicados.
A resposta original é devolvida (mesmo `id` e mesmo status HTTP). A autorização **não** é recriada. Janela de retenção: **24 horas**.
Resposta `409 Conflict` com a mensagem `Header X-Idempotency-Key reutilizado com payload diferente.` Use uma nova chave para a nova cobrança.
Resposta `409 Conflict` com a mensagem `Requisição idempotente em processamento.` Aguarde a primeira finalizar.
A chave é liberada automaticamente. A próxima retentativa com o mesmo header executa normalmente.
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 |
| --------------------------- | -------------------- | --------------------------------------------------- |
| `paymentMethod` | `"pix_auto"` | 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) |
### Detalhamento dos campos
Deve ser `"pix_auto"` para iniciar uma autorização de débito automático via Pix Automático.
Dados do pagador. O `docType` e `docNumber` são exigidos pelas adquirentes para criação do contrato de recorrência.
Nome completo do pagador.
E-mail do pagador.
Telefone do pagador no formato E.164 (`5511999999999`).
Identificador estável do dispositivo/sessão do pagador. Deve ser uma string não vazia e consistente para a mesma sessão.
Tipo de documento do pagador. Valores aceitos: `cpf`, `cnpj`.
Para Pix Automático, `docType` e `docNumber` são exigidos pela adquirente para criar o contrato de recorrência. A omissão pode causar falha no processamento.
Número do documento (somente dígitos).
Data de nascimento no formato ISO 8601 (`YYYY-MM-DD`).
IP do pagador. Quando omitido, a Cakto utiliza o IP de origem da requisição.
Itens da cobrança. Deve conter exatamente **um** item.
`id` da oferta cadastrada. A oferta deve estar com status `active` e pertencer à sua conta. O produto é resolvido automaticamente a partir da oferta e deve ter `pix_auto` habilitado nos métodos de pagamento.
Quantidade vendida da oferta. Mínimo `1`.
Tipo da oferta dentro do funil. Apenas `main` é aceito.
Endereço do pagador. Obrigatório quando o produto exige entrega física.
País no formato ISO 3166-1 alpha-2.
UF (duas letras), por exemplo `SP`.
CEP, somente dígitos.
`short_id` do afiliado responsável pela venda. Deve estar `active` e cadastrado para o produto.
Código do cupom de desconto. Até 255 caracteres.
Parâmetros de rastreio associados à cobrança.
Expiração do QR Code de autorização em segundos. Mínimo `60`. Deve respeitar o limite máximo configurado no produto (`pixExpiresIn`).
O valor é repassado à adquirente que processar a autorização. Se ela impuser um limite próprio,
vale o dela — confira sempre o `pix.expirationDate` devolvido na resposta. Omitindo o campo,
vale o padrão da adquirente.
## Resposta de sucesso
`201 Created`
Identificador único do pedido criado.
Código curto de referência do pedido.
Status inicial. Normalmente `waiting_payment` — aguardando o cliente escanear e autorizar o QR Code.
Método de pagamento confirmado: `pix_auto`.
Valor da primeira cobrança, em reais, como string decimal.
Valor base da oferta, antes de descontos.
Valor de desconto aplicado.
Taxas aplicadas pela Cakto, já consolidadas.
Identificador da transação na adquirente.
URL do checkout Cakto.
Timestamp ISO 8601 com fuso horário.
Resumo do produto associado.
Resumo da oferta cobrada.
Dados da autorização Pix Automático. Contém apenas o código copia-e-cola — a API não devolve imagem do QR Code.
Código copia-e-cola (BR Code) para o cliente escanear e autorizar os débitos automáticos futuros.
Data e hora de expiração do QR Code de autorização.
Jornada de autorização definida pelo BCB para o banco do cliente. Valores possíveis: `JORNADA_1`, `JORNADA_2`, `JORNADA_3`, `JORNADA_4`. Determinado automaticamente pela adquirente — não precisa ser enviado na requisição.
### Exemplo de resposta
```json Pix Automático theme={null}
{
"id": "30dd73dd-25dg-695e-d6e7-5612987e6218",
"refId": "PIXaUTo",
"status": "waiting_payment",
"paymentMethod": "pix_auto",
"amount": "49.90",
"baseAmount": "49.90",
"discount": "0.00",
"fees": "0.00",
"externalId": "txid-gerado-pela-adquirente",
"checkoutUrl": "https://pay.cakto.com.br/PIXaUTo",
"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...",
"expirationDate": "2026-04-29 01:30:00+00:00",
"user_journey": "JORNADA_1"
}
}
```
## 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` | `paymentMethod` ausente ou fora da lista aceita. | `{ "paymentMethod": ["Método de pagamento não suportado."] }` |
| `400` | Oferta inexistente, inativa ou de outro tenant. | `{ "items": ["Oferta não encontrada."] }` |
| `400` | `pixExpiresIn` acima do limite do produto. | `{ "pixExpiresIn": ["A expiração do Pix excede o limite do produto (3600 segundo(s))."] }` |
| `400` | Produtor sem conta Cakto Banking válida (só afeta `pix`, `pix_auto` e `boleto`). Veja [Pré-requisitos](#pré-requisitos). | `{ "paymentMethod": ["Pix, Pix Automático e boleto só podem ser cobrados por produtores com conta Cakto Banking aberta, ativa e fora de encerramento — é nela que esses métodos liquidam. Confira o status da conta no Painel Cakto (https://app.cakto.com.br/dashboard); se a abertura não foi concluída, conclua-a. Cobranças com cartão (credit_card, threeDs) não dependem dessa conta e seguem disponíveis."] }` |
| `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 normalmente.
## Exemplo de requisição
```bash cURL theme={null}
curl -X POST 'https://api.cakto.com.br/public_api/payments/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
-H 'Content-Type: application/json' \
-H 'X-Idempotency-Key: 9c2b4e7f-ae5g-5g2g-cg8d-3ce5g08gae34' \
-d '{
"paymentMethod": "pix_auto",
"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"
}
}'
```
```python Python theme={null}
import uuid
import requests
response = requests.post(
"https://api.cakto.com.br/public_api/payments/",
headers={
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn...",
"Content-Type": "application/json",
"X-Idempotency-Key": str(uuid.uuid4()),
},
json={
"paymentMethod": "pix_auto",
"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",
},
},
timeout=30,
)
response.raise_for_status()
payment = response.json()
# Exiba o QR Code para o cliente autorizar os débitos automáticos
print(payment["pix"]["qrCode"])
print(payment["pix"]["user_journey"])
```
```javascript Node.js theme={null}
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.cakto.com.br/public_api/payments/", {
method: "POST",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn...",
"Content-Type": "application/json",
"X-Idempotency-Key": randomUUID(),
},
body: JSON.stringify({
paymentMethod: "pix_auto",
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",
},
}),
});
if (!response.ok) throw new Error(`Cakto API error ${response.status}`);
const payment = await response.json();
// Exiba o QR Code para o cliente autorizar os débitos automáticos
console.log(payment.pix.qrCode);
console.log(payment.pix.user_journey);
```
## Fluxo de autorização
```mermaid theme={null}
sequenceDiagram
autonumber
participant App as Sua aplicação
participant API as API Pública Cakto
participant Adquirente as Adquirente Pix Auto
participant Cliente as App do banco do cliente
App->>API: POST /public_api/payments/ (paymentMethod: pix_auto)
API->>Adquirente: Cria Location + Charge + Contrato de Recorrência
Adquirente-->>API: QR Code de autorização + user_journey
API-->>App: 201 Created com pix.qrCode e pix.user_journey
App->>Cliente: Exibe QR Code para o cliente escanear
Cliente->>Adquirente: Escaneia e autoriza os débitos automáticos
Adquirente-->>API: Webhook de autorização confirmada
API-->>App: Evento purchase_approved via webhook
Note over Adquirente,Cliente: Cobranças futuras debitadas automaticamente
```
## Boas práticas
* **Exiba apenas `pix.qrCode`** (texto copia-e-cola) — a API não retorna imagem base64 em nenhum método Pix; gere a imagem no seu lado.
* **Aguarde o webhook `purchase_approved`** para confirmar que o cliente autorizou os débitos. Não ative o acesso ao produto antes da confirmação.
* **`docType` e `docNumber` são essenciais** — sem eles a adquirente pode rejeitar a criação do contrato de recorrência.
* **Persista o `id` retornado** para conciliar com webhooks e com [`GET /public_api/orders/{id}/`](/api-reference/orders/retrieve).
* **Não reuse a chave de idempotência** em situações distintas — uma nova intenção de assinatura exige uma nova chave.
## OpenAPI
````yaml POST /public_api/payments/
openapi: 3.0.3
info:
title: Cakto API
version: 1.0.0
description: Documentação da API pública do Cakto.
servers:
- url: https://api.cakto.com.br
description: Cakto API
security: []
paths:
/public_api/payments/:
post:
tags:
- payments
operationId: payments_create
parameters:
- in: header
name: X-Idempotency-Key
schema:
type: string
description: >-
Identificador único por cobrança. Reuso com payload idêntico devolve
a mesma resposta (24h). Máximo de 255 caracteres; recomenda-se UUID
v4.
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPaymentCreateRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PublicPaymentCreateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/PublicPaymentCreateRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPaymentResponse'
examples:
PixCriadoComSucesso:
value:
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
product:
id: cd287b31-d4b7-4e94-858a-66e05ce2f4a2
short_id: 19bruPi
name: Product Name Example
offer:
id: 77BcHrY
name: Product Name Example
price: 49.9
pix:
qrCode: 00020126360014BR.GOV.BCB.PIX0114+5511999999999...
expirationDate: '2026-04-29 01:30:00+00:00'
user_journey: null
checkoutUrl: https://pay.cakto.com.br/EXAMPLE
createdAt: '2026-04-28T23:30:00-03:00'
summary: Cobrança Pix criada com sucesso
BoletoCriadoComSucesso:
value:
id: 20cc62cc-14cf-584d-c5d6-4501876d5107
refId: BOLLkn4
status: waiting_payment
paymentMethod: boleto
amount: '49.90'
baseAmount: '49.90'
discount: '0.00'
fees: '0.00'
externalId: 8f2g1e48-ac6g-5g2g-cg8d-3ce5g08gae34
product:
id: cd287b31-d4b7-4e94-858a-66e05ce2f4a2
short_id: 19bruPi
name: Product Name Example
offer:
id: 77BcHrY
name: Product Name Example
price: 49.9
boleto:
barcode: 03399.65411 78060.000000 00012.345678 4 12345678901234
pdfUrl: https://api.cakto.com.br/boleto/EXAMPLE.pdf
dueDate: '2026-05-05'
checkoutUrl: https://pay.cakto.com.br/EXAMPLE
createdAt: '2026-04-28T23:30:00-03:00'
summary: Cobrança Boleto criada com sucesso
description: Corpo da resposta status 201
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCreate400'
examples:
HeaderIdempotencyAusente:
value:
detail: Header X-Idempotency-Key é obrigatório.
MetodoNaoSuportado:
value:
paymentMethod:
- Método de pagamento não suportado.
OfertaInvalida:
value:
items:
- Oferta não encontrada.
AfiliadoInvalido:
value:
affiliateShortId:
- Afiliado inválido para o produto informado.
ContaBankingAusente:
value:
paymentMethod:
- >-
Pix, Pix Automático e boleto só podem ser cobrados por
produtores com conta Cakto Banking aberta, ativa e fora
de encerramento — é nela que esses métodos liquidam.
Confira o status da conta no Painel Cakto
(https://app.cakto.com.br/dashboard); se a abertura não
foi concluída, conclua-a. Cobranças com cartão
(credit_card, threeDs) não dependem dessa conta e seguem
disponíveis.
SplitForaDoMVP:
value:
splits: Campo não pode ser enviado no payload do MVP.
VencimentoForaDaPolitica:
value:
dueDate:
- >-
A data de vencimento excede o limite do produto (7
dia(s)).
PixExpirationForaDaPolitica:
value:
pixExpiresIn:
- >-
A expiração do Pix excede o limite do produto (3600
segundo(s)).
description: Corpo da resposta status 400
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCreate401'
examples:
Unauthorized:
value:
detail: As credenciais de autenticação não foram fornecidas.
description: Corpo da resposta status 401
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
EscopoInsuficiente:
value:
detail: Você não tem permissão para executar esta ação.
description: Chave de API sem o escopo `payments`.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCreate409'
examples:
ConflitoIdempotencia:
value:
detail: >-
Header X-Idempotency-Key reutilizado com payload
diferente.
RequisicaoEmProcessamento:
value:
detail: Requisição idempotente em processamento.
description: Corpo da resposta status 409
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCreate422'
examples:
SplitContextoInvalido:
value:
detail: Não foi possível resolver o split com o contexto enviado.
description: Corpo da resposta status 422
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCreate429'
examples:
RateLimitExcedido:
value:
detail: Request was throttled. Expected available in 60 seconds.
description: Corpo da resposta status 429
security:
- OAuth Token: []
components:
schemas:
PublicPaymentCreateRequest:
type: object
properties:
paymentMethod:
allOf:
- $ref: '#/components/schemas/PaymentMethodEnum'
description: |-
Método de pagamento.
* `pix` - pix
* `pix_auto` - pix_auto
* `boleto` - boleto
* `credit_card` - credit_card
* `threeDs` - threeDs
customer:
allOf:
- $ref: '#/components/schemas/PublicPaymentCustomer'
description: >-
Dados do pagador. CPF e CPNJ aceitos conforme contrato existente do
checkout.
address:
allOf:
- $ref: '#/components/schemas/PublicPaymentAddress'
nullable: true
description: >-
Endereço do pagador. Obrigatório quando o produto exige envio
físico.
items:
type: array
items:
$ref: '#/components/schemas/PublicPaymentItem'
description: Deve conter exatamente um item.
affiliateShortId:
type: string
description: >-
`short_id` do afiliado responsável pela venda, usado para resolver o
split interno. Deve estar com status `active` e cadastrado para o
produto informado.
maxLength: 40
coupon:
type: string
description: Código do cupom de desconto.
maxLength: 255
metadata:
$ref: '#/components/schemas/PublicPaymentMetadata'
dueDate:
type: string
format: date
description: >-
Somente para `boleto`. Data de vencimento (`YYYY-MM-DD`). Deve ser
futura e respeitar o `ticketExpiration` do produto.
pixExpiresIn:
type: integer
minimum: 60
description: >-
Somente para `pix` e `pix_auto`. Expiração do código Pix em
segundos. Mínimo 60. Deve respeitar o `pixExpiresIn` do produto.
card:
allOf:
- $ref: '#/components/schemas/PublicPaymentCard'
description: >-
Dados do cartão de crédito. Obrigatório quando paymentMethod é
credit_card ou threeDs.
threeDSecure:
allOf:
- $ref: '#/components/schemas/PublicPaymentThreeDs'
description: >-
Dados de autenticação 3DS. Opcional para credit_card; recomendado
para threeDs.
installments:
type: integer
maximum: 12
minimum: 1
nullable: true
description: >-
Número de parcelas. Aplicável apenas para pagamentos com cartão de
crédito.
antifraud_profiling_attempt_reference:
type: string
description: >-
Referência de profiling do antifraude. Obrigatório para credit_card
e threeDs; deve ser o mesmo `attemptReference` usado ao inicializar
o profiler no navegador.
required:
- customer
- items
- paymentMethod
PublicPaymentResponse:
type: object
description: Cobrança criada pelo endpoint público.
properties:
id:
type: string
description: Identificador único do pedido criado.
refId:
type: string
nullable: true
description: Código curto de referência do pedido.
status:
type: string
nullable: true
description: >-
Status inicial do pedido. Para Pix e Boleto, normalmente
`waiting_payment`.
paymentMethod:
allOf:
- $ref: '#/components/schemas/PaymentMethodEnum'
description: >-
Método de pagamento da cobrança, ecoando o valor enviado na
requisição.
* `pix` - pix
* `pix_auto` - pix_auto
* `boleto` - boleto
* `credit_card` - credit_card
* `threeDs` - threeDs
amount:
type: string
description: Valor final cobrado, em reais, como string decimal.
baseAmount:
type: string
nullable: true
description: Valor da oferta antes de descontos.
discount:
type: string
nullable: true
description: Desconto aplicado.
fees:
type: string
nullable: true
description: Taxas da transação.
externalId:
type: string
nullable: true
description: Identificador da transação no provedor.
checkoutUrl:
type: string
nullable: true
description: URL do checkout Cakto.
createdAt:
type: string
format: date-time
nullable: true
description: Data e hora de criação da cobrança.
product:
$ref: '#/components/schemas/PublicPaymentResponseProduct'
offer:
$ref: '#/components/schemas/PublicPaymentResponseOffer'
pix:
allOf:
- $ref: '#/components/schemas/PublicPaymentResponsePix'
description: Presente apenas para `pix` e `pix_auto`.
boleto:
allOf:
- $ref: '#/components/schemas/PublicPaymentResponseBoleto'
description: Presente apenas para `boleto`.
PaymentCreate400:
type: object
properties:
detail:
type: string
required:
- detail
PaymentCreate401:
type: object
properties:
detail:
type: string
required:
- detail
PaymentCreate409:
type: object
properties:
detail:
type: string
required:
- detail
PaymentCreate422:
type: object
properties:
detail:
type: string
required:
- detail
PaymentCreate429:
type: object
properties:
detail:
type: string
required:
- detail
PaymentMethodEnum:
enum:
- pix
- pix_auto
- boleto
- credit_card
- threeDs
type: string
description: |-
* `pix` - pix
* `pix_auto` - pix_auto
* `boleto` - boleto
* `credit_card` - credit_card
* `threeDs` - threeDs
PublicPaymentCustomer:
type: object
properties:
name:
type: string
title: Nome
description: Nome completo do pagador.
maxLength: 255
birthDate:
type: string
format: date
nullable: true
title: Nascimento
description: Data de nascimento do pagador (`YYYY-MM-DD`).
email:
type: string
format: email
description: E-mail do pagador.
maxLength: 254
phone:
type: string
title: Telefone
description: Telefone do pagador no formato E.164 (`5511999999999`).
maxLength: 255
docType:
type: string
description: >-
Tipo de documento do pagador (`cpf` ou `cnpj`). Apesar do contrato
aceitar omitir, envie sempre para cobranças no Brasil (necessário
para nota fiscal).
docNumber:
type: string
description: Número do documento, somente dígitos.
ip:
type: string
nullable: true
title: Endereço IP
description: >-
IP do pagador. Quando omitido, a Cakto utiliza o IP de origem da
requisição.
maxLength: 255
fingerprint:
type: string
description: >-
Identificador estável do dispositivo/sessão do pagador. Quando
enviado, deve ser consistente para a mesma sessão.
required:
- email
- name
- phone
PublicPaymentAddress:
type: object
properties:
country:
type: string
title: País
description: 'País no formato ISO 3166-1 alpha-2 (ex.: `BR`).'
maxLength: 2
state:
type: string
title: Estado
description: 'UF, duas letras (ISO 3166-2 alpha-2, ex.: `SP`).'
maxLength: 2
city:
type: string
title: Cidade
description: Nome da cidade
maxLength: 255
zipcode:
type: string
title: CEP
description: CEP, somente dígitos.
maxLength: 30
street:
type: string
title: Rua
description: Nome da rua
maxLength: 255
neighborhood:
type: string
nullable: true
title: Bairro
description: Nome do bairro
maxLength: 255
complement:
type: string
nullable: true
title: Complemento
description: Complemento do endereço
maxLength: 255
number:
type: string
title: Número
description: Número do endereço
maxLength: 255
required:
- city
- country
- number
- state
- street
- zipcode
PublicPaymentItem:
type: object
description: Single item (offer reference) in a public payment request.
properties:
offerId:
type: string
description: >-
`short_id` da oferta. Deve pertencer a um produto do tenant
autenticado.
quantity:
type: integer
minimum: 1
default: 1
description: Quantidade vendida da oferta.
offerType:
allOf:
- $ref: '#/components/schemas/OfferTypeEnum'
default: main
description: |-
Tipo da oferta dentro do funil. No MVP, somente `main` é aceito.
* `main` - Principal
* `upsell` - Upsell
* `downsell` - Downsell
* `orderbump` - Order Bump
installments:
type: integer
maximum: 12
minimum: 1
nullable: true
description: >-
Número de parcelas. Aplicável apenas para pagamentos com cartão de
crédito.
required:
- offerId
PublicPaymentMetadata:
type: object
description: Optional UTM/tracking metadata associated with the payment.
properties:
utm_source:
type: string
nullable: true
maxLength: 255
utm_medium:
type: string
nullable: true
maxLength: 255
utm_campaign:
type: string
nullable: true
maxLength: 255
utm_term:
type: string
nullable: true
maxLength: 255
utm_content:
type: string
nullable: true
maxLength: 255
sck:
type: string
nullable: true
maxLength: 255
PublicPaymentCard:
type: object
description: Card data for credit card and 3DS payments.
properties:
token:
type: string
PublicPaymentThreeDs:
type: object
description: 3DS authentication data forwarded to the acquirer.
properties:
cavv:
type: string
eci:
type: string
xid:
type: string
referenceId:
type: string
version:
type: string
dataOnly:
type: boolean
default: false
PublicPaymentResponseProduct:
type: object
description: Produto resolvido a partir da oferta enviada.
properties:
id:
type: string
description: Identificador único do produto.
short_id:
type: string
description: Código curto do produto.
name:
type: string
description: Nome do produto.
PublicPaymentResponseOffer:
type: object
description: >-
Oferta cobrada. Campos vazios no checkout são preenchidos com a oferta
validada.
properties:
id:
type: string
nullable: true
description: Identificador da oferta.
name:
type: string
nullable: true
description: Nome da oferta.
price:
type: number
format: double
nullable: true
description: Preço da oferta.
PublicPaymentResponsePix:
type: object
description: Dados do Pix. Presente apenas para `pix` e `pix_auto`.
properties:
qrCode:
type: string
description: Código copia-e-cola (BR Code).
expirationDate:
type: string
description: >-
Data e hora de expiração do QR Code, no formato devolvido pelo
provedor.
user_journey:
type: string
nullable: true
description: >-
Jornada do Pix Automático negociada com o provedor (`JORNADA_1`,
`JORNADA_2`, `JORNADA_3` ou `JORNADA_4`). Nulo para Pix avulso.
PublicPaymentResponseBoleto:
type: object
description: Dados do boleto. Presente apenas para `boleto`.
properties:
barcode:
type: string
description: Linha digitável do boleto.
pdfUrl:
type: string
description: URL do PDF do boleto.
dueDate:
type: string
description: Data e hora de vencimento, no formato devolvido pelo provedor.
OfferTypeEnum:
enum:
- main
- upsell
- downsell
- orderbump
type: string
description: |-
* `main` - Principal
* `upsell` - Upsell
* `downsell` - Downsell
* `orderbump` - Order Bump
securitySchemes:
OAuth Token:
type: http
scheme: bearer
in: header
name: Authorization
description: >-
Token de autenticação do tipo `Bearer {access_token}`, onde
`{access_token}` é o token obtido no fluxo de
[autenticação](/authentication).
````