@validapay/tokenize 1.1.0 → 1.3.0

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@validapay/tokenize",
-  "version": "1.1.0",
-  "description": "SDK de tokenização de cartão ValidaPay",
+  "version": "1.3.0",
+  "description": "Tokenização de cartão e identificação do dispositivo para antifraude ValidaPay",
   "type": "module",
-  "main": "index.js",
+  "main": "src/index.js",
   "exports": {
-    ".": "./index.js"
+    ".": "./src/index.js",
+    "./browser": "./src/browser.js"
   },
   "files": [
-    "index.js"
+    "src"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "access": "public"
   },
   "keywords": [
     "validapay",
     "tokenize",
+    "antifraude",
     "cartao",
     "pagamento",
     "sdk"

package/readme.md

@@ -0,0 +1,83 @@
+# @validapay/tokenize
+
+Salva o cartão do comprador na ValidaPay e identifica o dispositivo para a análise antifraude.
+
+```bash
+npm install @validapay/tokenize
+```
+
+Funciona de dois jeitos, conforme onde o cartão é recebido.
+
+## No servidor, com `clientId` e `clientSecret`
+
+```js
+import { tokenize } from "@validapay/tokenize";
+
+const paymentMethod = await tokenize({
+  clientId: process.env.VALIDAPAY_CLIENT_ID,
+  clientSecret: process.env.VALIDAPAY_CLIENT_SECRET,
+  card: { number: "4111111111111111", holderName: "MARIA SILVA", cvv: "123", expiration: "12/2030" },
+  customer: { name: "Maria Silva", document: "12345678901", email: "maria@exemplo.com" },
+});
+```
+
+- Devolve o cartão salvo com o `cardToken`, que vale 5 minutos. Integrações que já usavam o `paymentMethodId` continuam recebendo o campo; as novas recebem só o `cardToken`.
+- `dev: true` usa o ambiente de desenvolvimento.
+- `card.cardHolderName` continua aceito no lugar de `card.holderName`.
+- O `clientSecret` nunca deve ir para o navegador.
+
+## No navegador, com `publicId`
+
+```js
+import { tokenize } from "@validapay/tokenize/browser";
+
+const { cardToken, cardBrand, cardLastFour } = await tokenize({
+  publicId: "3f1c2a8e-8a4b-4c1e-9d3a-2b7e6f5a4c10",
+  card,
+  customer,
+});
+```
+
+- O cartão vai do navegador direto para a ValidaPay, sem passar pelo seu servidor.
+- Devolve só `cardToken`, `cardTokenExpiresAt`, `cardBrand` e `cardLastFour`.
+- `environment`: `production` (padrão), `sandbox` ou `development`.
+
+## Identificação do dispositivo (antifraude)
+
+Roda no navegador. Chame assim que a página de checkout abrir, uma vez por pedido: a identificação precisa desse tempo antes do pagamento.
+
+```js
+import { collectDevice } from "@validapay/tokenize/browser";
+
+const { deviceId } = await collectDevice({ publicId: "3f1c2a8e-8a4b-4c1e-9d3a-2b7e6f5a4c10" });
+```
+
+- `deviceId` é `null` quando a conta não usa análise antifraude. Pode chamar sempre.
+- Não coleta dados pessoais nem dados do cartão.
+- Vale para as duas formas de tokenizar: se o cartão vai para o seu servidor, envie o `deviceId` junto.
+
+## Com autenticação do portador
+
+Se usar `@validapay/3ds`, passe o resultado em `authentication`. Vale para as duas formas:
+
+```js
+const paymentMethod = await tokenize({ ..., authentication });
+```
+
+## Cobrança
+
+Seu servidor cria a cobrança com o `cardToken` em até 5 minutos:
+
+```http
+POST /v1/charges
+{ "paymentMethod": "creditcard", "amount": 149.9, "cardToken": "ctk_…", "customer": { … } }
+```
+
+Inclua também `deviceId` e, se usar `@validapay/3ds`, `authentication` no mesmo corpo:
+
+```http
+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.

package/src/browser.js

@@ -0,0 +1,52 @@
+import { ValidaPayError } from "./shared/errors.js";
+import { openPaymentSession, postJson, resolveApiUrl } from "./shared/api.js";
+import { assertBrowser, assertRequired, holderNameOf, onlyDigits } from "./shared/runtime.js";
+import { mountFingerprint } from "./fingerprint.js";
+
+function assertInput({ publicId, card, customer }) {
+    assertRequired([
+        ["publicId", publicId],
+        ["card.number", card?.number],
+        ["card.holderName", holderNameOf(card)],
+        ["card.cvv", card?.cvv],
+        ["card.expiration", card?.expiration],
+        ["customer.document", customer?.document],
+        ["customer.name", customer?.name],
+        ["customer.email", customer?.email],
+    ]);
+}
+
+function toRequestBody({ publicId, card, customer, authentication }) {
+    return {
+        publicId,
+        cardHolderName: holderNameOf(card),
+        number: onlyDigits(card.number),
+        cvv: card.cvv,
+        expiration: card.expiration,
+        customer: { document: onlyDigits(customer.document), name: customer.name, email: customer.email },
+        ...(authentication?.cardId && { threeDsCardId: authentication.cardId }),
+    };
+}
+
+export async function collectDevice({ publicId, environment = "production" }) {
+    assertBrowser("@validapay/tokenize/browser");
+    assertRequired([["publicId", publicId]]);
+
+    const session = await openPaymentSession(environment, publicId);
+    mountFingerprint(session.fingerprint);
+
+    return { deviceId: session.fingerprint?.dfpId ?? null };
+}
+
+export async function tokenize({ publicId, environment = "production", card, customer, authentication = null }) {
+    assertBrowser("@validapay/tokenize/browser");
+    assertInput({ publicId, card, customer });
+
+    return postJson(
+        `${resolveApiUrl(environment)}/v1/payment-sessions/payment-methods`,
+        toRequestBody({ publicId, card, customer, authentication }),
+        "Não foi possível salvar o cartão"
+    );
+}
+
+export { ValidaPayError };

package/src/fingerprint.js

@@ -0,0 +1,36 @@
+const FINGERPRINT_BASE_URL = "https://h.online-metrix.net/fp";
+const HIDDEN_FRAME_STYLE = "width:100px;height:100px;border:0;position:absolute;top:-5000px;";
+const MOUNTED_ATTRIBUTE = "data-validapay-fingerprint";
+
+function fingerprintQuery({ orgId, merchantId, dfpId }) {
+    return new URLSearchParams({ org_id: orgId, session_id: `${merchantId}${dfpId}` }).toString();
+}
+
+function isMounted(dfpId) {
+    return Boolean(document.querySelector(`[${MOUNTED_ATTRIBUTE}="${dfpId}"]`));
+}
+
+function appendScript(query, dfpId) {
+    const script = document.createElement("script");
+    script.src = `${FINGERPRINT_BASE_URL}/tags.js?${query}`;
+    script.async = true;
+    script.setAttribute(MOUNTED_ATTRIBUTE, dfpId);
+    document.head.appendChild(script);
+}
+
+function appendFallbackFrame(query, dfpId) {
+    const frame = document.createElement("iframe");
+    frame.src = `${FINGERPRINT_BASE_URL}/tags?${query}`;
+    frame.style.cssText = HIDDEN_FRAME_STYLE;
+    frame.setAttribute("aria-hidden", "true");
+    frame.setAttribute(MOUNTED_ATTRIBUTE, `${dfpId}-frame`);
+    document.body.appendChild(frame);
+}
+
+export function mountFingerprint(fingerprint) {
+    if (!fingerprint || isMounted(fingerprint.dfpId)) return;
+
+    const query = fingerprintQuery(fingerprint);
+    appendScript(query, fingerprint.dfpId);
+    appendFallbackFrame(query, fingerprint.dfpId);
+}

package/src/index.js

@@ -0,0 +1,68 @@
+import { ValidaPayError, toApiError } from "./shared/errors.js";
+import { assertRequired, holderNameOf } from "./shared/runtime.js";
+
+const OAUTH_URL_PRD = "https://oauth2.validapay.com.br/auth/token";
+const OAUTH_URL_DEV = "https://oauth2-dev.validapay.com.br/auth/token";
+const API_URL_PRD = "https://api.validapay.com.br";
+const API_URL_DEV = "https://dev.validapay.com.br";
+const TOKENIZE_SCOPE = "payment.methods/write";
+
+async function fetchToken({ clientId, clientSecret, dev }) {
+    const response = await fetch(dev ? OAUTH_URL_DEV : OAUTH_URL_PRD, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: clientId,
+            client_secret: clientSecret,
+            scope: TOKENIZE_SCOPE,
+        }).toString(),
+    });
+
+    if (!response.ok) throw await toApiError(response, "Falha ao obter token");
+
+    const data = await response.json();
+    return data.access_token;
+}
+
+function assertInput({ clientId, clientSecret, card, customer }) {
+    assertRequired([
+        ["clientId", clientId],
+        ["clientSecret", clientSecret],
+        ["card.number", card?.number],
+        ["card.cardHolderName", holderNameOf(card)],
+        ["card.cvv", card?.cvv],
+        ["card.expiration", card?.expiration],
+        ["customer.document", customer?.document],
+        ["customer.name", customer?.name],
+        ["customer.email", customer?.email],
+    ]);
+}
+
+export async function tokenize({ clientId, clientSecret, dev = false, card, customer, authentication = null }) {
+    assertInput({ clientId, clientSecret, card, customer });
+
+    const token = await fetchToken({ clientId, clientSecret, dev });
+
+    const response = await fetch(`${dev ? API_URL_DEV : API_URL_PRD}/v1/payment-methods/tokenize`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+            cardHolderName: holderNameOf(card),
+            number: card.number,
+            cvv: card.cvv,
+            expiration: card.expiration,
+            customer,
+            ...(authentication?.cardId && { threeDsCardId: authentication.cardId }),
+        }),
+    });
+
+    if (!response.ok) throw await toApiError(response, "Erro ao tokenizar cartão");
+
+    return response.json();
+}
+
+export { ValidaPayError };

package/src/shared/api.js

@@ -0,0 +1,31 @@
+import { ValidaPayError, toApiError } from "./errors.js";
+
+const API_URLS = {
+    production: "https://api.validapay.com.br",
+    sandbox: "https://sandbox.validapay.com.br",
+    development: "https://dev.validapay.com.br",
+};
+
+export function resolveApiUrl(environment) {
+    const apiUrl = API_URLS[environment];
+    if (!apiUrl) {
+        throw new ValidaPayError(`environment inválido: use ${Object.keys(API_URLS).join(", ")}`, "INVALID_ENVIRONMENT");
+    }
+    return apiUrl;
+}
+
+export async function postJson(url, body, fallbackMessage) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+
+    if (!response.ok) throw await toApiError(response, fallbackMessage);
+
+    return response.json();
+}
+
+export function openPaymentSession(environment, publicId) {
+    return postJson(`${resolveApiUrl(environment)}/v1/payment-sessions`, { publicId }, "Não foi possível iniciar o pagamento");
+}

package/src/shared/errors.js

@@ -0,0 +1,19 @@
+export class ValidaPayError extends Error {
+    constructor(message, code, details = null) {
+        super(message);
+        this.name = "ValidaPayError";
+        this.code = code;
+        this.details = details;
+    }
+}
+
+export async function toApiError(response, fallbackMessage) {
+    const body = await response.json().catch(() => null);
+    const error = body?.error ?? body;
+
+    return new ValidaPayError(
+        error?.message || fallbackMessage,
+        error?.code || `HTTP_${response.status}`,
+        error?.details ?? null
+    );
+}

package/src/shared/runtime.js

@@ -0,0 +1,16 @@
+import { ValidaPayError } from "./errors.js";
+
+export function assertBrowser(packageName) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        throw new ValidaPayError(`${packageName} só roda no navegador`, "BROWSER_ONLY");
+    }
+}
+
+export function assertRequired(fields) {
+    const missing = fields.find(([, value]) => value === undefined || value === null || String(value).trim() === "");
+    if (missing) throw new ValidaPayError(`${missing[0]} é obrigatório`, "MISSING_FIELD");
+}
+
+export const onlyDigits = (value) => String(value ?? "").replace(/\D/g, "");
+
+export const holderNameOf = (card) => card?.holderName ?? card?.cardHolderName;

package/index.js

@@ -1,64 +0,0 @@
-const OAUTH_URL_PRD = "https://oauth2.validapay.com.br/auth/token";
-const OAUTH_URL_DEV = "https://oauth2-dev.validapay.com.br/auth/token";
-const API_URL_PRD = "https://api.validapay.com.br";
-const API_URL_DEV = "https://dev.validapay.com.br";
-
-async function fetchToken({ clientId, clientSecret, dev }) {
-    const oauthUrl = dev ? OAUTH_URL_DEV : OAUTH_URL_PRD;
-
-    const res = await fetch(oauthUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: new URLSearchParams({
-            grant_type: "client_credentials",
-            client_id: clientId,
-            client_secret: clientSecret,
-            scope: "payment.methods/write",
-        }).toString(),
-    });
-
-    if (!res.ok) {
-        const error = await res.json().catch(() => ({ message: res.statusText }));
-        throw new Error(error?.message || "Falha ao obter token");
-    }
-
-    const data = await res.json();
-    return data.access_token;
-}
-
-export async function tokenize({ clientId, clientSecret, dev = false, card, customer }) {
-    if (!clientId) throw new Error("clientId é obrigatório");
-    if (!clientSecret) throw new Error("clientSecret é obrigatório");
-    if (!card?.number) throw new Error("card.number é obrigatório");
-    if (!card?.name) throw new Error("card.name é obrigatório");
-    if (!card?.cvv) throw new Error("card.cvv é obrigatório");
-    if (!card?.expiration) throw new Error("card.expiration é obrigatório");
-    if (!customer?.document) throw new Error("customer.document é obrigatório");
-    if (!customer?.name) throw new Error("customer.name é obrigatório");
-    if (!customer?.email) throw new Error("customer.email é obrigatório");
-
-    const token = await fetchToken({ clientId, clientSecret, dev });
-    const apiUrl = dev ? API_URL_DEV : API_URL_PRD;
-
-    const res = await fetch(`${apiUrl}/v1/payment-methods/tokenize`, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${token}`,
-        },
-        body: JSON.stringify({
-            name: card.name,
-            number: card.number,
-            cvv: card.cvv,
-            expiration: card.expiration,
-            customer,
-        }),
-    });
-
-    if (!res.ok) {
-        const error = await res.json().catch(() => ({ message: res.statusText }));
-        throw new Error(error?.message || "Erro ao tokenizar cartão");
-    }
-
-    return res.json();
-}