Referência
Campos da Resposta
Referência completa dos campos retornados pelo endpoint de checkout.
Campos da Resposta
Campos de status
| Campo | Tipo | Descrição |
|---|---|---|
id | string (UUID) | ID único do pagamento na Cakto |
status | string | Status atual — ver tabela abaixo |
amount | float | Valor cobrado em reais |
paidAmount | float | Valor efetivamente pago |
liquidAmount | float | Valor líquido após taxas |
fee | float | Valor total das taxas |
refundedAmount | float | Valor devolvido (em reembolso) |
installments | integer | Número de parcelas |
tid | string | ID da transação no adquirente |
return_code | string | Código ABECS do adquirente — ver tabela abaixo |
merchant_advice_code | string | Código de orientação para retry |
reason | string | Motivo de recusa em linguagem legível |
acquirerType | string | Adquirente usado: "cielo", "worldpay", etc. |
currency | string | Código da moeda ("BRL") |
exId | string | Seu ID externo, se enviado |
Valores de status
| Status | Significado | Ação recomendada |
|---|---|---|
paid | ✅ Aprovado | Liberar acesso ao produto/serviço |
declined | ❌ Recusado pelo emissor | Exibir mensagem genérica, sugerir outro cartão |
refused | ❌ Recusado por regra interna | Exibir mensagem genérica |
pending | ⏳ Em processamento | Aguardar webhook no postbackUrl |
blocked | 🚫 Bloqueado por fraude | Não revelar motivo — mensagem genérica |
expired | ⌛ Expirado | Criar nova transação |
refunded | 💰 Reembolsado | Confirmação do reembolso |
chargedback | ⚠️ Chargeback | Disputa em andamento |
canceled | ✖️ Cancelado | Transação cancelada |
Para status: "blocked", nunca revele ao usuário que foi fraude. Exiba uma mensagem genérica como "Não foi possível processar o pagamento. Tente outro cartão."
Objeto card na resposta
Retornado sem dados sensíveis (sem PAN completo).
| Campo | Descrição |
|---|---|
lastDigits | Últimos 4 dígitos do cartão |
holderName | Nome no cartão |
brand | Bandeira: "visa", "master", "elo", "amex", "hipercard" |
token | Token para cobranças futuras (se saveCard: true foi enviado) |
Objeto threeDs na resposta
Presente somente quando paymentMethod: "threeDs".
| Campo | Descrição |
|---|---|
eci | ECI da transação |
cavv | Criptograma usado |
version | Versão do protocolo |
liability_shift | true se chargeback por não-reconhecimento é responsabilidade do emissor |
Códigos return_code comuns (ABECS)
| Código | Mensagem recomendada ao usuário |
|---|---|
4 / 00 | (Aprovado — não exibir mensagem de erro) |
03 / 05 | "Transação não autorizada. Entre em contato com seu banco." |
51 | "Saldo ou limite insuficiente." |
54 | "Cartão vencido. Verifique a data de validade." |
55 | "Senha incorreta." |
57 | "Transação não permitida para este cartão." |
59 | "Transação suspeita. Entre em contato com seu banco." |
62 | "Cartão com restrição. Use outro cartão." |
78 | "Cartão bloqueado. Entre em contato com seu banco." |
91 / 96 | "Falha temporária. Tente novamente em alguns minutos." |
Exiba mensagens ao usuário baseadas no código, não no campo reason. O campo reason é para logs internos — pode conter informações operacionais não adequadas para exibição ao cliente.