Comece Aqui

SDK de Tokenização

O @validapay/tokenize converte os dados do cartão em um paymentMethodId seguro — sem que os dados brutos trafeguem pelo seu servidor.

Como funciona

Chame tokenize() com suas credenciais e os dados do cartão

O SDK obtém o token de acesso internamente

Retorna um paymentMethodId seguro (pm_xxx)

Use o ID para criar cobranças — o cartão nunca trafega pelo seu servidor

1. Instalar o SDK

npm install @validapay/tokenize

2. Tokenizar o cartão

Chame tokenize() passando suas credenciais e os dados do cartão. O SDK obtém o token de acesso internamente — você não precisa gerenciar o fluxo OAuth.

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

const result = await tokenize({
  clientId: 'seu_client_id',
  clientSecret: 'seu_client_secret',
  card: {
    number: '5230552482605921',
    cardHolderName: 'LUKE SKYWALKER',
    cvv: '100',
    expiration: '12/2030',
  },
  customer: {
    name: 'Luke Skywalker',
    document: '86564950039',
    email: 'luke@teste.com',
  },
});

console.log(result.paymentMethodId); // pm_abc123

Parâmetros de tokenize()

Parâmetro	Tipo	Descrição
clientId	string	Client ID das suas credenciais ValidaPay
clientSecret	string	Client Secret das suas credenciais ValidaPay
card.number	string	Número do cartão sem espaços (16 dígitos)
card.cardHolderName	string	Nome impresso no cartão (caixa alta)
card.cvv	string	Código de segurança (3 ou 4 dígitos)
card.expiration	string	Validade no formato MM/YYYY
customer.name	string	Nome completo do portador do cartão
customer.document	string	CPF sem formatação (11 dígitos)
customer.email	string	E-mail do portador

Retorno — 200 OK

{
  "paymentMethodId": "pm_1781878250527_57pqifbga",
  "customerId": "cus_1781730599969_0xkofruxu",
  "accountNumber": "4218590",
  "type": "CREDIT_CARD",
  "status": "ACTIVE",
  "isDefault": false,
  "cardBrand": "MASTERCARD",
  "cardLastFour": "5921",
  "cardExpirationMonth": "12",
  "cardExpirationYear": "2030",
  "cardHolderName": "jose teste",
  "createdAt": "2026-06-19T14:10:50.666Z",
  "updatedAt": "2026-06-19T14:10:50.666Z"
}

Erros comuns

400Dados do cartão inválidos

{ "message": "Falha ao tokenizar cartão", "code": "CARD_TOKENIZATION_FAILED" }

400Campo obrigatório ausente ou formato inválido

{ "message": "card.number is required", "code": "VALIDATION_ERROR" }

403Escopo não autorizado

{ "message": "Forbidden", "code": "FORBIDDEN" }

404Conta não encontrada (pode ser transitório)

{ "message": "Conta não encontrada", "code": "ACCOUNT_NOT_FOUND" }