> ## 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 Cartão
> Processa um pagamento por cartão de crédito a partir de uma oferta da sua conta. Requer um token de cartão obtido previamente no front-end via SDK.
## Visão geral
O método `credit_card` processa um pagamento por cartão de crédito sem autenticação 3DS. O front-end [tokeniza](/sdk/tokenizacao) o cartão e envia apenas o `cardToken` ao seu backend, que chama este endpoint.
Para transferir a responsabilidade de chargeback por fraude ao banco emissor (*liability shift*), use a [Cobrança 3DS](/api-reference/payments/create-3ds). Sem 3DS, o risco de chargeback fica com o produtor.
## 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
```
## 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, 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` | `"credit_card"` | 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 |
| `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 |
| `antifraudProfilingAttemptReference` | string | Sim |
### Detalhamento dos campos
Deve ser `"credit_card"` para pagamentos por cartão sem 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/`](/api-reference/payments/card-tokens).
Token de uso único gerado pelo endpoint de tokenização. Válido por 15 minutos.
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`
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. |
Confirmado como `credit_card`.
Valor final cobrado, em reais, como string decimal.
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 Cartão Aprovado theme={null}
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"refId": "CARDpay",
"status": "paid",
"paymentMethod": "credit_card",
"amount": "199.90",
"externalId": "cakto-card-abc123def456",
"checkoutUrl": "https://pay.cakto.com.br/CARDpay",
"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` | `antifraudProfilingAttemptReference` ausente. | `{ "antifraudProfilingAttemptReference": ["Este campo é obrigatório."] }` |
| `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: c4d3e2f1-a0b9-4e8f-9d7c-6b5a4f3e2d1c' \
-d '{
"paymentMethod": "credit_card",
"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"
},
"antifraudProfilingAttemptReference": "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": "credit_card",
"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"},
"antifraudProfilingAttemptReference": "a3d90c10-c0c6-4c33-8af3-944f694ea633",
},
timeout=30,
)
response.raise_for_status()
payment = response.json()
print(payment["status"])
```
```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: "credit_card",
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" },
antifraudProfilingAttemptReference: "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);
```
## Boas práticas
* **Obtenha o `cardToken` imediatamente antes de chamar este endpoint.** O token expira em 15 minutos e é de uso único.
* **Prefira a [Cobrança 3DS](/api-reference/payments/create-3ds)** sempre que possível. Ela reduz chargebacks via liability shift.
* **Não confunda `declined` com `refused`.** `declined` é recusa financeira do banco. `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
description: >-
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.
operationId: payments_create
parameters:
- name: X-Idempotency-Key
in: header
required: true
description: >-
Identificador único da cobrança (até 255 caracteres). Recomendado
UUID v4.
Reuso com payload idêntico devolve a resposta original por 24h.
schema:
type: string
maxLength: 255
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPaymentCreateRequest'
examples:
Pix:
summary: Cobrança Pix
value:
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
PixAuto:
summary: Autorização Pix Automático
value:
productId: 19bruPi
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
ThreeDs:
summary: Cobrança 3DS
value:
productId: 19bruPi
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
quantity: 1
offerType: main
card:
token: tok_abc123def456
threeDSecure:
cavv: AAIBBYNoEwAAACcKhAJkdQAAAAA=
eci: '05'
version: 2.2.0
referenceId: cakto-3ds-abc123def456
metadata:
utm_source: facebook
utm_campaign: lancamento-mai
Boleto:
summary: Cobrança Boleto
value:
productId: 19bruPi
paymentMethod: boleto
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
dueDate: '2026-05-05'
metadata:
utm_source: facebook
utm_campaign: lancamento-mai
responses:
'201':
description: Cobrança criada com sucesso.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicPaymentResponse'
examples:
PixCriadoComSucesso:
summary: Cobrança Pix criada com sucesso
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
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'
PixAutoCriadoComSucesso:
summary: Autorização Pix Automático criada com sucesso
value:
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-29T01:30:00-03:00'
user_journey: JORNADA_1
ThreeDsCriadoComSucesso:
summary: Cobrança 3DS processada com sucesso
value:
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
BoletoCriadoComSucesso:
summary: Cobrança Boleto criada com sucesso
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
checkoutUrl: https://pay.cakto.com.br/BOLLkn4
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
boleto:
barcode: 03399.65411 78060.000000 00012.345678 4 12345678901234
pdfUrl: https://api.cakto.com.br/boleto/EXAMPLE.pdf
dueDate: '2026-05-05'
'400':
description: Erro de validação no payload ou no header de idempotência.
content:
application/json:
examples:
HeaderIdempotencyAusente:
value:
detail: Header X-Idempotency-Key é obrigatório.
ProdutoInvalido:
value:
productId:
- Produto não encontrado.
MetodoNaoSuportado:
value:
paymentMethod:
- Método de pagamento não suportado.
OfertaInvalida:
value:
items:
- Oferta não encontrada para o produto informado.
AfiliadoInvalido:
value:
affiliateShortId:
- Afiliado inválido para o produto informado.
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)).
CampoProibido:
value:
splits: Campo não pode ser enviado no payload.
CampoNaoSuportado:
value:
campo_desconhecido: Campo não suportado pelo contrato público.
ContaBloqueada:
value:
detail: Conta bloqueada.
'401':
description: Request não autenticado devido à ausência ou invalidez do token.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedError'
examples:
Token ausente ou inválido:
$ref: '#/components/examples/UnauthenticatedErrorExample'
'403':
description: Chave de API sem o escopo `payments`.
content:
application/json:
examples:
EscopoInsuficiente:
value:
detail: Você não tem permissão para executar esta ação.
'409':
description: >-
Conflito de idempotência (chave reutilizada com payload diferente ou
requisição em curso).
content:
application/json:
examples:
ConflitoIdempotencia:
value:
detail: >-
Header X-Idempotency-Key reutilizado com payload
diferente.
RequisicaoEmProcessamento:
value:
detail: Requisição idempotente em processamento.
'429':
description: Rate limit excedido (por IP ou por token).
content:
application/json:
examples:
RateLimitExcedido:
value:
detail: Request was throttled. Expected available in 60 seconds.
security:
- OAuth Token:
- payments
components:
schemas:
PublicPaymentCreateRequest:
type: object
required:
- productId
- paymentMethod
- customer
- items
properties:
productId:
type: string
description: |-
`short_id` ou `id` (UUID) do produto. O produto deve pertencer ao
tenant autenticado e estar ativo.
paymentMethod:
type: string
enum:
- pix
- pix_auto
- boleto
description: Método de pagamento da cobrança.
customer:
$ref: '#/components/schemas/PublicPaymentCustomer'
items:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/PublicPaymentItem'
description: Deve conter exatamente um item.
address:
$ref: '#/components/schemas/PublicPaymentAddress'
affiliateShortId:
type: string
maxLength: 40
description: |-
`short_id` do afiliado responsável pela venda. Deve estar com status
`active` e cadastrado para o produto informado.
coupon:
type: string
maxLength: 255
description: Código do cupom de desconto.
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.
PublicPaymentResponse:
type: object
properties:
id:
type: string
description: Identificador único do pedido criado.
refId:
type: string
description: Código curto de referência do pedido.
status:
type: string
description: >-
Status inicial do pedido. Para Pix e Boleto, normalmente
`waiting_payment`.
paymentMethod:
type: string
enum:
- pix
- pix_auto
- boleto
amount:
type: string
description: Valor final cobrado, em reais, como string decimal.
baseAmount:
type: string
nullable: true
discount:
type: string
nullable: true
fees:
type: string
nullable: true
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
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`.
UnauthenticatedError:
type: object
properties:
detail:
type: string
PublicPaymentCustomer:
type: object
required:
- name
- email
- phone
- fingerprint
properties:
name:
type: string
description: Nome completo do pagador.
email:
type: string
format: email
description: E-mail do pagador.
phone:
type: string
description: Telefone do pagador no formato E.164 (`5511999999999`).
fingerprint:
type: string
description: |-
Identificador estável do dispositivo/sessão do pagador. Deve ser uma
string não vazia, consistente para a mesma sessão.
docType:
type: string
enum:
- cpf
- cnpj
description: |-
Tipo de documento do pagador. 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.
birthDate:
type: string
format: date
description: Data de nascimento (`YYYY-MM-DD`).
ip:
type: string
description: >-
IP do pagador. Quando omitido, a Cakto utiliza o IP de origem da
requisição.
PublicPaymentItem:
type: object
required:
- offerId
properties:
offerId:
type: string
description: |-
`id` da oferta cadastrada. A oferta deve estar com status `active`
e pertencer ao `productId` informado.
quantity:
type: integer
minimum: 1
default: 1
description: Quantidade vendida da oferta.
offerType:
type: string
enum:
- main
default: main
description: Tipo da oferta dentro do funil. Apenas `main` é aceito.
PublicPaymentAddress:
type: object
properties:
country:
type: string
default: BR
description: País no formato ISO 3166-1 alpha-2.
state:
type: string
description: UF (duas letras).
city:
type: string
zipcode:
type: string
description: CEP, somente dígitos.
street:
type: string
neighborhood:
type: string
number:
type: string
complement:
type: string
PublicPaymentMetadata:
type: object
properties:
utm_source:
type: string
maxLength: 255
utm_medium:
type: string
maxLength: 255
utm_campaign:
type: string
maxLength: 255
utm_term:
type: string
maxLength: 255
utm_content:
type: string
maxLength: 255
sck:
type: string
maxLength: 255
PublicPaymentResponseProduct:
type: object
properties:
id:
type: string
short_id:
type: string
name:
type: string
PublicPaymentResponseOffer:
type: object
properties:
id:
type: string
nullable: true
name:
type: string
nullable: true
price:
type: number
nullable: true
PublicPaymentResponsePix:
type: object
properties:
qrCode:
type: string
description: Código copia-e-cola (BR Code).
qrCodeBase64:
type: string
description: Imagem do QR Code em base64 (`data:image/png;base64,...`).
expirationDate:
type: string
format: date-time
description: Data e hora de expiração do QR Code.
PublicPaymentResponseBoleto:
type: object
properties:
barcode:
type: string
description: Linha digitável do boleto.
pdfUrl:
type: string
description: URL do PDF do boleto.
dueDate:
type: string
format: date
description: Data de vencimento.
examples:
UnauthenticatedErrorExample:
summary: Token ausente ou inválido
description: Token ausente ou inválido
value:
detail: As credenciais de autenticação não foram fornecidas.
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).
````