> ## 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 3DS
> Processa um pagamento por cartão de crédito com autenticação 3DS. Requer token de cartão e dados da autenticação 3DS obtidos previamente no front-end.
## Visão geral
O método `threeDs` processa um pagamento por cartão de crédito com autenticação 3-D Secure (3DS). Esse fluxo garante que o portador do cartão foi autenticado pelo banco emissor antes da cobrança, transferindo a responsabilidade de chargeback por fraude do produtor para o emissor (**liability shift**).
Este endpoint representa a **Etapa 2** do fluxo 3DS, a autorização. A **Etapa 1** (autenticação do comprador com o banco) é realizada pelo front-end do integrador usando o SDK do adquirente (Worldpay.js, BP.MPI da Cielo etc.) antes de chamar esta API.
O fluxo completo tem quatro passos:
O front-end coleta os dados do cartão e chama [`POST /public_api/card-tokens/`](/sdk/tokenizacao) para obter um `cardToken` de uso único, válido por 15 minutos.
O front-end usa o SDK do adquirente com os dados do cartão para iniciar o fluxo 3DS e obter um `referenceId` de sessão.
O banco emissor apresenta o desafio ao comprador (SMS, biometria etc.) e devolve ao front-end os dados de autenticação: `cavv`, `eci`, `version` e `referenceId`.
O integrador chama `POST /public_api/payments/` com `paymentMethod: "threeDs"`, o `cardToken` e os dados de autenticação. A Cakto autoriza e captura o pagamento junto ao adquirente.
## 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
```
3DS **não** exige conta Cakto Banking. O pré-requisito de conta Banking vale só para `pix`, `pix_auto` e `boleto` — veja [Pré-requisitos de Pix](/api-reference/payments/create-pix#pré-requisitos).
## Idempotência
O header `X-Idempotency-Key` é obrigatório e permite reenviar a mesma requisição com segurança sem gerar cobranças duplicadas. Janela de retenção: **24 horas**.
O `card.token` tem validade de **15 minutos** e uso único. Se a idempotência reutilizar uma chave existente, o token original já foi consumido, e a resposta armazenada é devolvida sem reprocessar.
## Rate limit
| Critério | Padrão |
| ------------------- | ------------------------ |
| Por IP de origem | 60 requisições / minuto |
| Por token de acesso | 120 requisições / minuto |
## Corpo da requisição
### Resumo dos campos
| Campo | Tipo | Obrigatório |
| --------------------------------------- | -------------------- | --------------------------------------------------- |
| `paymentMethod` | `"threeDs"` | 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) |
| `items` (exatamente 1 item) | array | Sim |
| `items[].offerId` | string | Sim |
| `card` | object | Sim |
| `card.token` | string | Sim |
| `threeDSecure` | object | Não (fortemente recomendado) |
| `threeDSecure.cavv` | string | Não |
| `threeDSecure.eci` | string | Não |
| `threeDSecure.xid` | string | Não |
| `threeDSecure.referenceId` | string | Não |
| `threeDSecure.version` | string | Não |
| `threeDSecure.dataOnly` | boolean | Não (default `false`) |
| `installments` | integer (1 a 12) | Não |
| `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 |
| `antifraud_profiling_attempt_reference` | string | Sim |
### Detalhamento dos campos
Deve ser `"threeDs"` para pagamentos com autenticação 3DS.
Dados do pagador.
Nome completo do portador do cartão.
E-mail do pagador.
Telefone no formato E.164 (`5511999999999`).
Identificador estável do dispositivo/sessão do pagador.
Tipo de documento. Valores aceitos: `cpf`, `cnpj`.
Número do documento (somente dígitos).
Itens da cobrança. Deve conter exatamente **um** item.
`id` da oferta cobrada. Deve estar `active` e pertencer à sua conta. Encontre o ID no [Painel Cakto](https://app.cakto.com.br/dashboard) em **Produtos**. O produto é resolvido automaticamente a partir da oferta.
Quantidade. Mínimo `1`.
Tipo da oferta. Apenas `main` é aceito.
Token de cartão obtido via [`POST /public_api/card-tokens/`](/sdk/tokenizacao).
Token de uso único gerado pelo endpoint de tokenização. Válido por 15 minutos. Após consumido, não pode ser reutilizado.
Dados de autenticação 3DS fornecidos pelo SDK do adquirente após o comprador completar o desafio. Fortemente recomendado. Sem esses dados, o pagamento pode ser processado sem liability shift.
Cardholder Authentication Verification Value. Prova criptográfica de que o portador do cartão se autenticou. Gerado pelo banco emissor.
Electronic Commerce Indicator. Código de nível de autenticação. Valores típicos: `05` (totalmente autenticado), `06` (tentativa aceita).
Identificador da transação 3DS no banco emissor (também chamado `dsTransactionId` no 3DS 2.x).
Referência da sessão 3DS iniciada pelo backend da Cakto. Obrigatório para adquirentes que usam fluxo backend-driven (ex.: Worldpay). Formato esperado: `cakto-3ds-{id}`.
Versão do protocolo 3DS utilizado. Exemplo: `2.2.0`.
Indica que a autenticação foi feita no modo Data Only (sem desafio ao portador). Aplicável apenas em alguns adquirentes.
Número de parcelas, de `1` a `12`. Aceito apenas com `credit_card` e `threeDs`.
`short_id` do afiliado responsável pela venda.
Código do cupom de desconto. Até 255 caracteres.
Parâmetros de rastreio.
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.
Este é o único campo **de topo** do payload em `snake_case`; todos os demais campos de topo são camelCase (campos aninhados, como `metadata.utm_source`, também usam `snake_case`). Enviar `antifraudProfilingAttemptReference` resulta em `400` com `{ "antifraudProfilingAttemptReference": "Campo não suportado pelo contrato público." }`.
## Resposta de sucesso
`201 Created`
Identificador único do pedido criado.
Código curto de referência do pedido.
Status do pagamento. Valores possíveis:
| Valor | Significado |
| ---------- | --------------------------------------------------------------- |
| `paid` | Pagamento autorizado e capturado. |
| `declined` | Recusado pelo banco ou adquirente (limite, bloqueio, fraude). |
| `refused` | Recusado por falha técnica no adquirente. |
| `pending` | Desafio 3DS ainda em andamento (fluxo Worldpay backend-driven). |
Confirmado como `threeDs`.
Valor final cobrado, em reais, como string decimal.
Valor base da oferta antes de descontos.
Valor de desconto aplicado.
Taxas da Cakto consolidadas.
Identificador da transação no adquirente.
URL do checkout Cakto associado à cobrança.
Timestamp ISO 8601.
Resumo do produto.
Resumo da oferta cobrada.
### Exemplo de resposta
```json 3DS Aprovado theme={null}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"refId": "3DSpayX",
"status": "paid",
"paymentMethod": "threeDs",
"amount": "199.90",
"baseAmount": "199.90",
"discount": "0.00",
"fees": "0.00",
"externalId": "cakto-3ds-abc123def456",
"checkoutUrl": "https://pay.cakto.com.br/3DSpayX",
"createdAt": "2026-05-29T14:00:00-03:00",
"product": {
"id": "cd287b31-d4b7-4e94-858a-66e05ce2f4a2",
"short_id": "19bruPi",
"name": "Cakto Pro Plan"
},
"offer": {
"id": "77BcHrY",
"name": "Plano Anual",
"price": 199.9
}
}
```
## Respostas de erro
| Código | Quando ocorre | Corpo de exemplo |
| ------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Header `X-Idempotency-Key` ausente ou inválido. | `{ "detail": "Header X-Idempotency-Key é obrigatório." }` |
| `400` | Campo `card` ausente no payload. | `{ "card": "Este campo é obrigatório quando o método de pagamento é credit_card ou threeDs." }` |
| `400` | Oferta inexistente, inativa ou de outra conta. | `{ "items": ["Oferta não encontrada."] }` |
| `400` | `antifraud_profiling_attempt_reference` ausente. | `{ "antifraud_profiling_attempt_reference": ["Este campo é obrigatório quando o método de pagamento é credit_card ou threeDs. Envie a mesma referência usada no profiling do antifraude no navegador."] }` |
| `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." }` |
| `429` | Rate limit excedido. | `{ "detail": "Request was throttled. Expected available in 60 seconds." }` |
## 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: f3a2d1c0-b9e8-4f7a-8c6b-5d4e3f2a1b0c' \
-d '{
"paymentMethod": "threeDs",
"customer": {
"name": "Maria Souza",
"email": "maria@example.com",
"phone": "5511999999999",
"fingerprint": "fp_2f8c1e5e-1aa8-4d4d-b9d4-19f7e5e0e1ab",
"docType": "cpf",
"docNumber": "12345678909"
},
"items": [
{ "offerId": "77BcHrY" }
],
"card": {
"token": "tok_abc123def456"
},
"threeDSecure": {
"cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
"eci": "05",
"version": "2.2.0",
"referenceId": "cakto-3ds-abc123def456"
},
"antifraud_profiling_attempt_reference": "a3d90c10-c0c6-4c33-8af3-944f694ea633"
}'
```
```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": "threeDs",
"customer": {
"name": "Maria Souza",
"email": "maria@example.com",
"phone": "5511999999999",
"fingerprint": "fp_2f8c1e5e-1aa8-4d4d-b9d4-19f7e5e0e1ab",
"docType": "cpf",
"docNumber": "12345678909",
},
"items": [{"offerId": "77BcHrY"}],
"card": {
"token": "tok_abc123def456",
},
"threeDSecure": {
"cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
"eci": "05",
"version": "2.2.0",
"referenceId": "cakto-3ds-abc123def456",
},
"antifraud_profiling_attempt_reference": "a3d90c10-c0c6-4c33-8af3-944f694ea633",
},
timeout=30,
)
response.raise_for_status()
payment = response.json()
print(payment["status"]) # "paid", "declined", "refused" ou "pending"
print(payment["id"])
```
```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: "threeDs",
customer: {
name: "Maria Souza",
email: "maria@example.com",
phone: "5511999999999",
fingerprint: "fp_2f8c1e5e-1aa8-4d4d-b9d4-19f7e5e0e1ab",
docType: "cpf",
docNumber: "12345678909",
},
items: [{ offerId: "77BcHrY" }],
card: {
token: "tok_abc123def456",
},
threeDSecure: {
cavv: "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
eci: "05",
version: "2.2.0",
referenceId: "cakto-3ds-abc123def456",
},
antifraud_profiling_attempt_reference: "a3d90c10-c0c6-4c33-8af3-944f694ea633",
}),
});
if (!response.ok) throw new Error(`Cakto API error ${response.status}`);
const payment = await response.json();
console.log(payment.status); // "paid", "declined", "refused" ou "pending"
console.log(payment.id);
```
## Boas práticas
* **Sempre obtenha o `cardToken` imediatamente antes de chamar este endpoint.** O token expira em 15 minutos e é de uso único.
* **Trate o status `pending`.** Ocorre quando o adquirente (ex.: Worldpay) ainda está processando o desafio 3DS iniciado pelo backend. Monitore via webhook `purchase_approved` ou `purchase_refused` para atualizar o estado na sua aplicação.
* **Envie `threeDSecure` sempre que disponível.** Sem ele, a transação pode ser processada sem liability shift, expondo o produtor a chargebacks por fraude.
* **Não confunda `declined` com `refused`.** `declined` é recusa financeira do banco (limite, suspeita de fraude). `refused` é falha técnica no adquirente.
## 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).
````