API de JavaScript

El SDK expone el objeto global window.Proteside. Para la mayoría de las tiendas no es necesario: el snippet por sí solo ya protege el checkout. Usa la API cuando el checkout es una aplicación de página única, cuando quieres informar el monto y el destinatario esperados de un pago, o para diagnóstico.

Todos los métodos están protegidos contra errores y nunca lanzan excepciones: si algo falla, la llamada se ignora.

Esperar a que cargue el SDKCopiar enlace de la sección

window.Proteside existe en cuanto se ejecuta el shield.js, pero el SDK solo termina de iniciar después de obtener la configuración remota, lo que puede tardar hasta unos 2 segundos.

Para llamar a la API de forma segura, espera a que getStatus().initialized sea true:

function whenProtesideReady(timeoutMs = 5000) {
  return new Promise((resolve) => {
    const start = Date.now();
    (function check() {
      const sdk = window.Proteside;
      if (sdk && sdk.getStatus().initialized) return resolve(sdk);
      if (Date.now() - start > timeoutMs) return resolve(null); // SDK ausente o bloqueado
      setTimeout(check, 100);
    })();
  });
}

// Uso
whenProtesideReady().then((sdk) => {
  if (!sdk) return; // continúa el checkout con normalidad sin el SDK
  sdk.expectPayment({ method: 'pix', amount: '19,90' });
});

Nunca condiciones el funcionamiento del checkout a la presencia del SDK: un bloqueador de anuncios o una falla de red puede impedir que cargue.

MétodosCopiar enlace de la sección

getStatus()Copiar enlace de la sección

Proteside.getStatus(): SDKStatus

Devuelve el estado actual del SDK. Se puede llamar en cualquier momento: antes de que el SDK inicie, devuelve initialized: false.

interface SDKStatus {
  initialized: boolean            // el SDK terminó de iniciar
  mode: 'monitor' | 'block'
  paused: boolean                 // pausa local, modo desarrollador o suscripción inactiva
  channel: 'stable' | 'latest'
  calibrating: boolean            // true durante la calibración
  activeThreats: number           // manipulaciones detectadas en esta página
  paymentMethodsMonitored: PaymentMethod[]
  version: string                 // p. ej.: '1.1.1'
  installationOrderValid: boolean // false = hay un script antes del bootstrapper
  overlayCheckIntervalMs: number
  rulesApplied: boolean
  recipientsPinned: number        // n.º de destinatarios confiables recibidos del dashboard
  cardCheckoutOpen: boolean
  cardCheckoutProvider: string | null
}

const { initialized, version, installationOrderValid } = Proteside.getStatus();

pageChanged(path)Copiar enlace de la sección

Proteside.pageChanged(path: string): void

Para aplicaciones de página única (React, Vue, Next.js, Nuxt). Avisa al SDK cuando la ruta cambia sin recargar la página. El SDK limpia las referencias de pago y los valores esperados de la ruta anterior, vuelve a leer los headers de seguridad y envía un PAGEVIEW de la nueva ruta.

// P. ej.: en el listener de cambio de ruta de tu framework
Proteside.pageChanged('/checkout/pagamento');

La calibración y el inventario de scripts no se rehacen: valen para toda la carga.

expectPayment(expectation)Copiar enlace de la sección

Proteside.expectPayment(expectation: {
  method: PaymentMethod
  amount?: string | number
  key?: string
}): void

Informa lo que el checkout espera del pago de esta página.

• amount: monto esperado, en la misma unidad del código (reales, para Pix y boleto). Acepta 19.9, '19,90' o 'R$ 19,90', comparados con dos decimales. Si el código mostrado tiene otro monto, el SDK emite AMOUNT_TAMPERED.
• key: destinatario confiable válido solo en esta página, sumado a los registrados en el dashboard. Solo el hash queda en memoria. Si el SDK ya había aceptado un código con otro destinatario, ese código pasa a tratarse como no confiable.

Proteside.expectPayment({ method: 'pix', amount: '19,90', key: 'pix@mitienda.com' });

Llámalo antes de insertar el código de pago en la página.

registerPaymentPayload(payload)Copiar enlace de la sección

Proteside.registerPaymentPayload(payload: {
  method: PaymentMethod
  fields: Record<string, string>
}): void

Registra manualmente la referencia de un método, para cuando el SDK no logra leer el código en la página (por ejemplo, un Pix que solo se muestra en <input value>). Para que sirva de comparación, fields debe incluir el destinatario: pixKey (Pix), address (Bitcoin y Ethereum), vpa (UPI) o walletId (billeteras QR).

Proteside.registerPaymentPayload({ method: 'pix', fields: { pixKey: 'pix@mitienda.com' } });

Este método no envía PAYMENT_VALIDATED y no pasa por la verificación de destinatarios confiables. Es preferible mostrar el código como texto, lo que da la validación completa.

pause()Copiar enlace de la sección

Proteside.pause(): void

Pausa el SDK en esta página: todos los eventos pasan a descartarse y la verificación de superposiciones se detiene. Las observaciones siguen instaladas, pero no reportan nada. La pausa dura hasta resume() o hasta que la página se recargue.

resume()Copiar enlace de la sección

Proteside.resume(): void

Reanuda el SDK después de pause(). No tiene efecto cuando la pausa viene del dashboard (modo desarrollador o suscripción inactiva).

configure(options)Copiar enlace de la sección

Proteside.configure(options: Partial<ProteConfig>): void

Sobrescribe la configuración después de la inicialización, solo en esta página. En la práctica, solo algunos campos tienen efecto, porque los módulos leen el resto una sola vez al iniciar: mode, sensitiveFields, recipients y, en parte, expectedIframeOrigins.

Proteside.configure({ sensitiveFields: ['#cpf', 'input[name="cvv"]'] });

Métodos de pagoCopiar enlace de la sección

El tipo PaymentMethod acepta: pix, boleto, card, bitcoin, ethereum, upi, paynow, promptpay, duitnow, qrph, hkfps, transferencias3, codi y qr_wallet.

Qué no forma parte de la APICopiar enlace de la sección

• No hay inicialización manual: el SDK se inicializa solo a partir de la etiqueta <script> del snippet.
• No hay callbacks de amenaza (como onThreat) ni modo de depuración. El único mensaje en la consola es [Proteside] Initialization failed silently, cuando la inicialización falla (por ejemplo, una clave con formato inválido).
• El bundle también crea variables globales internas, como window.ProteSDK y window.__PROTE_*. Pueden cambiar sin aviso: no dependas de ellas.

Próximos pasosCopiar enlace de la sección

• Integridad de pagos y Pix
• Eventos y detecciones