Skip to main content
POST

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

Escopo

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

Corpo da requisição

Resumo dos campos

Detalhamento dos campos

enum<string>
required
Deve ser "credit_card" para pagamentos por cartão sem 3DS.
object
required
Dados do pagador.
array<object>
required
Itens da cobrança. Deve conter exatamente um item.
object
required
Token de cartão obtido via POST /public_api/card-tokens/.
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.
string
Código curto de referência do pedido.
string
Status do pagamento. Valores possíveis:
string
Confirmado como credit_card.
string
Valor final cobrado, em reais, como string decimal.
string
Identificador da transação no adquirente.
string
URL do checkout Cakto associado à cobrança.
string<date-time>
Timestamp ISO 8601.
object
Resumo do produto.
object
Resumo da oferta cobrada.

Exemplo de resposta

Cartão Aprovado

Respostas de erro

Exemplo de requisição

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

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
items
object[]
required

Deve conter exatamente um item.

Required array length: 1 element
address
object
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
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.

id
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
offer
object
pix
object

Presente apenas para pix e pix_auto.

boleto
object

Presente apenas para boleto.