Tokenização de cartão

1. Instalar

npm install @validapay/tokenize

2. Identificar o dispositivo

Chame uma vez, assim que a página de pagamento carregar (antes do cliente inserir os dados do cartão).

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

const { deviceId } = await collectDevice({ publicId: 'SEU_ID_PUBLICO' });

{
  "deviceId": "60424e5b-01ee-46ec-9d97-b1507dc23ced"
}

3. Gerar o cardToken

Para gerar uma cobrança é necessário antes tokenizar o cartão chamando o método tokenize() do SDK @validapay/tokenize. Este método recebe os inputs: publicId, card, customer. A chamada deve ser feita conforme exemplificado abaixo:

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

const { cardToken } = await tokenize({
  publicId: 'SEU_ID_PUBLICO',
  card: {
    number: '5230552482605921',
    holderName: 'LUKE SKYWALKER',
    cvv: '100',
    expiration: '12/2030',
  },
  customer: {
    name: 'Luke Skywalker',
    document: '86564950039',
    email: 'luke@teste.com',
  },
});

{
  "cardToken": "ctk_9f8s7d6f5g4h3j2k1l0",
  "cardTokenExpiresAt": "2026-09-17T16:37:00.720Z",
  "cardBrand": "MASTERCARD",
  "cardLastFour": "5921"
}

4. Cobrar pelo seu servidor

Com o cardToken e o deviceId em mãos, envie-os ao seu servidor e gere a cobrança em Checkout Transparente → Gerar cobrança Cartão.

Comprador estrangeiro

Informe customer.country com o país do comprador. Com país diferente de BR, o document é opcional e, se enviado, aceita passaporte com letras:

const { deviceId } = await collectDevice({ publicId: 'SEU_ID_PUBLICO', environment: 'sandbox' });

const { cardToken } = await tokenize({
  publicId: 'SEU_ID_PUBLICO',
  environment: 'sandbox',
  card: { number: '4111111111111111', holderName: 'JOHN SMITH', cvv: '123', expiration: '12/2030' },
  customer: { name: 'John Smith', email: 'john@example.com', country: 'US' },
});

Na cobrança, envie o cliente sem documentNumber, com phone em E.164 e address.country do mesmo país. A conta precisa ter o pagamento internacional habilitado pelo suporte. Regras completas em Checkout Transparente → Gerar cobrança Cartão internacional.

POST /v1/charges
{
  "paymentMethod": "creditcard",
  "amount": 149.90,
  "installments": 1,
  "cardToken": "ctk_...",
  "deviceId": "...",
  "customer": {
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+14155552671",
    "address": {
      "country": "US",
      "zipCode": "94105",
      "street": "Market St",
      "number": "100",
      "city": "San Francisco",
      "state": "CA"
    }
  }
}

Parâmetros

Testando em sandbox

A conta de sandbox tem o seu próprio publicId, no painel em Gerenciamento > Minha Conta > Id Público. Passe environment: 'sandbox' nos comandos do SDK para apontar para o ambiente de testes:

const { deviceId } = await collectDevice({ publicId: 'SEU_ID_PUBLICO', environment: 'sandbox' });

const { cardToken } = await tokenize({ publicId: 'SEU_ID_PUBLICO', environment: 'sandbox', card, customer });

Em sandbox nada é cobrado de verdade: o número digitado na tokenização decide o resultado da cobrança.

Qualquer outro número de 13 a 19 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. O cardToken, o deviceId e os erros se comportam como em produção.

Erros

Integrações antigas

Quem já tokenizava pelo servidor, com client_id e client_secret, continua funcionando: a resposta agora traz também o cardToken. Para integrações novas, use o fluxo acima.

Perguntas frequentes