API de JavaScript
Métodos del objeto window.Proteside para consultar el estado e informar pagos.
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 esperado 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 SDK
window.Proteside existe en cuanto se ejecuta el shield.js, pero el SDK solo termina de iniciar después de cargar la
configuración de la tienda.
No hay evento de listo
El SDK no dispara ningún evento, promise ni callback cuando está listo. Con excepción de getStatus(), los métodos
llamados antes de que el SDK termine de iniciar se ignoran sin aviso, incluido expectPayment().
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étodos
getStatus()
Proteside.getStatus(): SDKStatusDevuelve 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
version: string // p. ej.: '1.2.0'
installationOrderValid: boolean // false = hay un script antes del snippet
}const { initialized, version, installationOrderValid } = Proteside.getStatus();pageChanged(path)
Proteside.pageChanged(path: string): voidPara 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 referencia de la página y el inventario de scripts valen para toda la carga.
expectPayment(expectation)
Proteside.expectPayment(expectation: {
method: PaymentMethod
amount?: string | number
}): voidInforma el monto 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). Acepta19.9,'19,90'o'R$ 19,90', comparados con dos decimales. Si el código mostrado tiene otro monto, el SDK emiteAMOUNT_TAMPERED.
Proteside.expectPayment({ method: 'pix', amount: '19,90' });Llámalo antes de insertar el código de pago en la página. Los destinatarios confiables se registran solo en el dashboard. Consulta Integridad de pagos y Pix.
registerPaymentPayload(payload)
Proteside.registerPaymentPayload(payload: {
method: PaymentMethod
fields: Record<string, string>
}): voidRegistra la referencia de un método de pago. Úsalo cuando el código de pago no aparece como texto visible en la
página. Para que sirva de comparación, fields debe incluir el destinatario: pixKey (Pix), address (billeteras
cripto), vpa (UPI) o walletId (billeteras QR).
Proteside.registerPaymentPayload({ method: 'pix', fields: { pixKey: 'pix@mitienda.com' } });Siempre que sea posible, muestra el código como texto visible en la página, lo que da la validación completa.
Métodos de pago
El tipo PaymentMethod acepta: pix, boleto, card, bitcoin, ethereum, tron, solana, upi, paynow,
promptpay, duitnow, qrph, hkfps, transferencias3, codi y qr_wallet.
Qué no forma parte de la API
- 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). - Usa solo los métodos documentados en esta página. Cualquier otra propiedad del SDK es interna y puede cambiar sin aviso.