Criar Cobrança 3DS

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

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:

Tokenizar o cartão

O front-end coleta os dados do cartão e chama POST /public_api/card-tokens/ para obter um cardToken de uso único, válido por 15 minutos.

Iniciar sessão 3DS

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.

Autenticar o comprador

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.

Autorizar o pagamento (este endpoint)

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/.

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

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 — 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
`productId`	string	Sim
`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`)
`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

productId

string

required

Identificador do produto da sua conta. Aceita o short_id ou o id (UUID). O produto deve pertencer ao tenant autenticado.

paymentMethod

enum<string>

required

Deve ser "threeDs" para pagamentos com autenticação 3DS.

customer

object

required

Dados do pagador.

Show Campos

customer.name

string

required

Nome completo do portador do cartão.

customer.email

string

required

E-mail do pagador.

customer.phone

string

required

Telefone no formato E.164 (5511999999999).

customer.fingerprint

string

required

Identificador estável do dispositivo/sessão do pagador.

customer.docType

enum<string>

Tipo de documento. Valores aceitos: cpf, cnpj.

customer.docNumber

string

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

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. Deve estar ativa e pertencer ao productId.

items[].quantity

integer

default:"1"

Quantidade. Mínimo 1.

items[].offerType

enum<string>

default:"main"

Tipo da oferta. Apenas main é aceito.

card

object

required

Token de cartão obtido via POST /public_api/card-tokens/.

Show Campos

card.token

string

required

Token de uso único gerado pelo endpoint de tokenização. Válido por 15 minutos. Após consumido, não pode ser reutilizado.

threeDSecure

object

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.

Show Campos

threeDSecure.cavv

string

Cardholder Authentication Verification Value. Prova criptográfica de que o portador do cartão se autenticou. Gerado pelo banco emissor.

threeDSecure.eci

string

Electronic Commerce Indicator. Código de nível de autenticação. Valores típicos: 05 (totalmente autenticado), 06 (tentativa aceita).

threeDSecure.xid

string

Identificador da transação 3DS no banco emissor (também chamado dsTransactionId no 3DS 2.x).

threeDSecure.referenceId

string

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}.

threeDSecure.version

string

Versão do protocolo 3DS utilizado. Exemplo: 2.2.0.

threeDSecure.dataOnly

boolean

default:"false"

Indica que a autenticação foi feita no modo Data Only (sem desafio ao portador). Aplicável apenas em alguns adquirentes.

affiliateShortId

string

short_id do afiliado responsável pela venda.

coupon

string

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

metadata

object

Parâmetros de rastreio.

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

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 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).

paymentMethod

string

Confirmado como threeDs.

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 da Cakto consolidadas.

externalId

string

Identificador da transação no adquirente.

checkoutUrl

string

URL do checkout Cakto associado à cobrança.

createdAt

string<date-time>

Timestamp ISO 8601.

product

object

Resumo do produto.

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

Exemplo de resposta

3DS Aprovado

{
  "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`	`productId` inválido ou de outro tenant.	`{ "productId": ["Produto não encontrado."] }`
`400`	Oferta inexistente ou de outro produto.	`{ "items": ["Oferta não encontrada para o produto informado."] }`
`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

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 '{
    "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"
    },
    "antifraudProfilingAttemptReference": "a3d90c10-c0c6-4c33-8af3-944f694ea633",
    "metadata": {
      "utm_source": "facebook",
      "utm_campaign": "lancamento-mai"
    }
  }'

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.

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

Criar Cobrança Boleto Listar Pedidos

​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