Tokenização de Cartões

A tokenização é o processo de transformar os dados sensíveis do cartão (PAN, CVV, portador) em um token opaco (cvt_*) que você usa no lugar do cartão para criar pagamentos. O cartão real nunca passa pelo seu servidor — só o navegador do comprador e a LegacyPay enxergam os dados completos.

Com o token você:

• Cria transações em /payin sem nunca tocar em PAN/CVV.
• Cobra o mesmo cliente novamente (card-on-file) sem precisar guardar cartão.
• Permite que o comprador escolha entre cartões salvos em uma próxima compra.

Tudo isso é gerenciado pelo SDK LegacyPay (legacy-pay.js) — você não precisa conhecer nem chamar nenhuma rota interna da plataforma.

Importando o SDK

<script src="https://api.legacyecombr.com.br/checkout/sdk/legacy-pay.js"></script>
<script>
  var client = LegacyPay.init({
    publicKey: "pk_live_xxx",
    apiBaseUrl: "https://api.legacyecombr.com.br"
  });
</script>

A publicKey (pk_live_* ou pk_test_*) é segura pra ficar exposta no browser. Nunca coloque a sk_live_* no front.

Criar token a partir do cartão

var tokenized = await client.tokenizeCard({
  amount: 9900,
  installments: 1,
  referenceId: "pedido-123",
  card: {
    holderName: "MARIA OLIVEIRA",
    number: "4111111111111111",
    expirationMonth: "12",
    expirationYear: "2028",
    cvv: "123"
  },
  customer: {
    name: "Maria Oliveira",
    document: "12345678909",
    email: "[email protected]",
    phone: "11988887777",
    address: {
      street: "Av Paulista",
      number: "1000",
      zipCode: "01310100",
      city: "São Paulo",
      state: "SP"
    }
  }
});

Resposta:

{
  "token": "cvt_live_5XY8...",
  "source": "tokenized",
  "brand": "visa",
  "last4": "1111",
  "bin": "411111",
  "expiresAt": "2028-12-31T23:59:59.000Z"
}

tokenizeCard() faz tokenização pura — não executa 3DS nem antifraude. Use prepareCardPayment() para o fluxo completo com 3DS e antifraude. Ver 3DS.

Usar o token no /payin

Esse passo é feito no seu backend, com x-api-key (pk) + x-api-secret (sk):

POST https://api.legacyecombr.com.br/payin
x-api-key: pk_live_...
x-api-secret: sk_live_...

{
  "paymentMethod": "CREDIT_CARD",
  "amount": 9900,
  "referenceId": "pedido-123",
  "isPhysicalProduct": true,
  "payerIp": "203.0.113.1",
  "customer": { /* mesmo customer */ },
  "items": [{ "title": "Produto", "quantity": 1, "unitPrice": 9900 }],
  "card": {
    "token": "cvt_live_5XY8...",
    "installments": 1
  }
}

⚠️

Para lojas com tokenização obrigatória, enviar PAN/CVV bruto no /payin retorna 400 TOKEN_REQUIRED. Use sempre o token gerado pelo SDK.

CVV e PCI-DSS

O CVV é capturado pelo SDK, enviado pra LegacyPay junto com a tokenização, e nunca persiste em banco. Ele fica disponível por até 5 minutos para a primeira /payin após a tokenização — depois disso, é descartado.

Para lojas onde o CVV precisa ser informado em cada cobrança (você descobre via client.getConfig(), campo capabilities.tokenization.cvvRequired), o comprador precisa digitar o CVV novamente em re-cobranças.

Card-on-file (cartões salvos)

Depois que o cliente paga uma primeira vez, o token continua válido até a data de expiração do cartão. Você pode listar cartões salvos do mesmo comprador, cobrar de novo e revogar quando o cliente pedir.

Listar cartões salvos

var cards = await client.listSavedCards({ document: "12345678909" });
// → [
//     {
//       token: "cvt_live_...",
//       brand: "visa",
//       last4: "1111",
//       expMonth: 12,
//       expYear: 2028,
//       lastUsedAt: "2026-05-10T15:00:00Z",
//       useCount: 3
//     }
//   ]

Use document (CPF) — o SDK pede ao backend para identificar o cliente.

Cobrar com cartão salvo

var payload = await client.payWithSavedCard({
  token: "cvt_live_...",
  cvv: "123",          // pode ser exigido — veja capabilities.tokenization.cvvRequired
  amount: 9900,
  referenceId: "pedido-456",
  installments: 1,
  customer: { name, email, document, phone }
});

// payload já está formatado pra você enviar pro /payin no backend.

Se a loja exige CVV em re-cobrança e você não passou, o método lança LegacyPayError("CVV_REQUIRED", ...).

Revogar cartão

await client.revokeCard("cvt_live_...", { reason: "customer_request" });

O token sai de ACTIVE e a próxima /payin que tentar usá-lo é rejeitada.

Detectar capacidades da loja

var config = await client.getConfig();
// config.capabilities.tokenization = {
//   enabled: true,
//   mode: "backend",
//   cardOnFile: true,     // re-cobrança sem PAN
//   cvvRequired: false    // CVV exigido em re-cobrança?
// }

Cada loja configurada na plataforma tem um perfil próprio — você só consulta o que está disponível. Os detalhes de implementação (qual fornecedor de cobrança está atrás, quais regras de fraude se aplicam) não são expostos ao integrador.

Erros possíveis

Detalhe pra /payin: