Skip to main content

​
Inicialização

Instancie o SDK fora do componente, no nível do módulo. Isso garante uma única instância por página — necessário para o antifraude funcionar corretamente. 
const caktoSdk = new Cakto.CaktoSDK({
  client_id: process.env.CAKTO_SDK_CLIENT_ID,
});

​
1. Antifraude — no carregamento da página

Chame initAntifraud() o mais cedo possível. Quanto mais cedo rodar, mais dados comportamentais são coletados (movimentos de mouse, tempo de preenchimento do formulário). Exemplo em React: 
useEffect(() => {
  caktoSdk.initAntifraud().catch(console.error);
}, []);

​
2. Envio do Formulário

Tudo dentro de um único handler de submit.
1

Tokenize o cartão (obrigatório)

Troca o número do cartão por um token de uso único.
const card = {
  holderName: "João da Silva",
  cardNumber: "4111111111111111",
  cvv: "123",
  expMonth: "12",
  expYear: "30",
};

const { cardToken } = await caktoSdk.createToken(card);
2

Autentique com 3DS (recomendado)

Provider padrão: Cielo (browser-only). Valide authResult.success para capturar falhas de autenticação.
const authResult = await caktoSdk.authenticate3DS({
  card,
  provider: "cielo", // 'cielo' | 'pagarme'
  customer: {
    amount: 10000,
    currency: "BRL",
    email: "joao@exemplo.com",
    name: "João da Silva",
    phone: "11999999999",
    paymentMethod: "credit", // credit | debit
    address: {
      street: "Rua Exemplo",
      number: "123",
      complement: "Apto 1",
      city: "São Paulo",
      state: "SP",
      zipcode: "01234-567",
    },
  },
});

if (!authResult.success) {
  throw new Error(authResult.error || "Falha na autenticação 3DS");
}
3

Finalize o antifraude (recomendado)

Chame antes de enviar o pagamento ao backend.
await caktoSdk.completeAntifraudProfile();
4

Envie ao seu backend

Repasse o token, os dados de 3DS e a referência antifraude (getAntifraudReference()) ao endpoint de pagamentos do seu backend.
await fetch("https://seu-backend.com/pagamentos", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    cardToken,
    threeDSecure: {
      cavv: authResult.cavv,
      eci: authResult.eci,
      xid: authResult.xid,
      referenceId: authResult.referenceId,
      version: authResult.version,
    },
    antifraud_profiling_attempt_reference: caktoSdk.getAntifraudReference(),
  }),
});
5

Limpe o antifraude (opcional)

Remove o script do DOM após o pagamento.
caktoSdk.cleanupAntifraud();
O endpoint /pagamentos é exemplo — use o endpoint de pagamentos do seu backend, onde roda a chamada à API da Cakto da seção Backend — Autenticação e Pagamento.

​
Pagar.me — Configuração Extra

Se usar provider: 'pagarme', adicione este formulário oculto no HTML da página antes de chamar authenticate3DS: 
<form data-pagarmecheckout-form style="display: none;"></form>
Passe provider: 'pagarme' ao chamar authenticate3DS. Os campos de retorno diferem do padrão Cielo:
CieloPagar.me
Form HTML obrigatórioNãoSim (data-pagarmecheckout-form)
holderName e cvvOpcionaisObrigatórios
Campos retornadoscavv, xid, eci, version, referenceIdeci, trans_status, tds_server_trans_id

​
3. Backend — Autenticação e Pagamento

Este é o endpoint chamado no passo 4 do submit. Ele usa o par de chaves API (client_id + client_secret) para obter um Bearer token e chamar a API de pagamento da Cakto.
1

Obtenha o Bearer token

Server-side, com o par de chaves API.
const tokenRes = await fetch("https://api.cakto.com.br/public_api/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    client_id: process.env.CAKTO_API_CLIENT_ID,
    client_secret: process.env.CAKTO_API_CLIENT_SECRET,
  }),
});

const { access_token } = await tokenRes.json();
2

Processe o pagamento

Envie o payload recebido do frontend com o token no header.
await fetch("https://api.cakto.com.br/public_api/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
Consulte o endpoint Criar Cobrança 3DS para ver todos os campos aceitos no payload de pagamento.

​
O que enviar ao backend

CampoOrigemObrigatório
cardTokencreateToken()Sim
cavv, eci, xid, version, referenceIdauthenticate3DS() (Cielo)Recomendado
eci, trans_status, tds_server_trans_idauthenticate3DS() (Pagar.me)Recomendado
antifraud_profiling_attempt_referencegetAntifraudReference()Recomendado

​
Importante

  • Nunca exponha client_secret no frontend — use apenas no backend
  • Nunca logue CVV ou número completo do cartão
  • Nunca envie o número do cartão ao backend — use apenas o cardToken
  • authenticate3DS e antifraude são browser-only — não funcionam em SSR/Node.js