@validapay/tokenize

Salva o cartão do comprador na ValidaPay e identifica o dispositivo para a análise antifraude. Roda no navegador, na sua página de pagamento: o cartão vai direto para a ValidaPay, sem passar pelo seu servidor.

npm install @validapay/tokenize

O publicId é o identificador público da sua conta, no painel em Gerenciamento > Minha Conta > Id Público. Ele pode ficar no código da página.

1. Identificar o dispositivo

Chame assim que a página de pagamento abrir, uma vez por pedido: a identificação precisa desse tempo antes do pagamento.

import { collectDevice } from "@validapay/tokenize/browser";

const { deviceId } = await collectDevice({ publicId: "3f1c2a8e-8a4b-4c1e-9d3a-2b7e6f5a4c10" });

• Não coleta dados pessoais nem dados do cartão.
• Guarde o deviceId: ele vai junto na cobrança.

2. Tokenizar o cartão

import { tokenize } from "@validapay/tokenize/browser";

const { cardToken, cardTokenExpiresAt, cardBrand, cardLastFour } = await tokenize({
  publicId: "3f1c2a8e-8a4b-4c1e-9d3a-2b7e6f5a4c10",
  card: { number: "4111111111111111", holderName: "MARIA SILVA", cvv: "123", expiration: "12/2030" },
  customer: { name: "Maria Silva", document: "12345678901", email: "[email protected]" },
});

• Devolve cardToken, cardTokenExpiresAt, cardBrand e cardLastFour.
• O cardToken vale 5 minutos e só funciona na conta que o gerou.
• environment: production (padrão), sandbox ou development.
• Aceita cartões de 13 a 19 dígitos.

Comprador estrangeiro

Informe customer.country com o código ISO 3166-1 alfa-2 do país do comprador (sem ele, o SDK usa customer.address.country, então o mesmo customer do 3DS serve). Com país diferente de BR, o document é opcional e, se enviado (passaporte, por exemplo), segue com letras:

const { cardToken } = await tokenize({
  publicId,
  card: { number: "4111111111111111", holderName: "JOHN SMITH", cvv: "123", expiration: "12/2030" },
  customer: { name: "John Smith", email: "[email protected]", country: "US" },
});

Na cobrança, envie o cliente sem documentNumber, com phone em E.164 e address.country do mesmo país.

Com autenticação do portador

Se usar @validapay/3ds, passe o resultado em authentication:

const { cardToken } = await tokenize({ publicId, card, customer, authentication });

3. Cobrar

Envie cardToken, deviceId e, se usou 3DS, authentication ao seu servidor. Ele cria a cobrança dentro dos 5 minutos:

POST /v1/charges
{
  "paymentMethod": "creditcard",
  "amount": 149.9,
  "cardToken": "ctk_…",
  "deviceId": "…",
  "authentication": { … },
  "customer": { … }
}

Depois de 5 minutos o cardToken vence e a cobrança responde CARD_TOKEN_EXPIRED: tokenize o cartão de novo.

Documentação

https://docs.validapay.com.br/sdks/tokenizacao