API JavaScript

O SDK expõe o objeto global window.Proteside. Para a maioria das lojas, ele não é necessário: o snippet sozinho já protege o checkout. Use a API quando o checkout é uma aplicação de página única, quando você quer informar o valor e o recebedor esperados de um pagamento, ou para diagnóstico.

Todos os métodos são protegidos contra erros e nunca lançam exceção: se algo falhar, a chamada é ignorada.

Esperar o SDK carregarCopiar link da seção

window.Proteside passa a existir assim que o shield.js executa, mas o SDK só termina de iniciar depois de buscar a configuração remota, o que pode levar até cerca de 2 segundos.

Para chamar a API com segurança, aguarde getStatus().initialized ficar 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 ou bloqueado
      setTimeout(check, 100);
    })();
  });
}

// Uso
whenProtesideReady().then((sdk) => {
  if (!sdk) return; // siga o checkout normalmente sem o SDK
  sdk.expectPayment({ method: 'pix', amount: '19,90' });
});

Nunca condicione o funcionamento do checkout à presença do SDK: um bloqueador de anúncios ou uma falha de rede pode impedir o carregamento.

MétodosCopiar link da seção

getStatus()Copiar link da seção

Proteside.getStatus(): SDKStatus

Retorna o estado atual do SDK. Pode ser chamado a qualquer momento: antes de o SDK iniciar, retorna initialized: false.

interface SDKStatus {
  initialized: boolean            // o SDK terminou de iniciar
  mode: 'monitor' | 'block'
  paused: boolean                 // pausa local, modo desenvolvedor ou assinatura inativa
  channel: 'stable' | 'latest'
  calibrating: boolean            // true durante a calibração
  activeThreats: number           // adulterações detectadas nesta página
  paymentMethodsMonitored: PaymentMethod[]
  version: string                 // ex.: '1.1.1'
  installationOrderValid: boolean // false = há script antes do bootstrapper
  overlayCheckIntervalMs: number
  rulesApplied: boolean
  recipientsPinned: number        // nº de recebedores confiáveis recebidos do dashboard
  cardCheckoutOpen: boolean
  cardCheckoutProvider: string | null
}

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

pageChanged(path)Copiar link da seção

Proteside.pageChanged(path: string): void

Para aplicações de página única (React, Vue, Next.js, Nuxt). Avise o SDK quando a rota mudar sem recarregar a página. O SDK limpa as referências de pagamento e os valores esperados da rota anterior, relê os headers de segurança e envia um PAGEVIEW da nova rota.

// Ex.: no listener de mudança de rota do seu framework
Proteside.pageChanged('/checkout/pagamento');

A calibração e o inventário de scripts não são refeitos: eles valem para o carregamento inteiro.

expectPayment(expectation)Copiar link da seção

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

Informa o que o checkout espera do pagamento desta página.

• amount: valor esperado, na mesma unidade do código (reais, para Pix e boleto). Aceita 19.9, '19,90' ou 'R$ 19,90', comparados com duas casas decimais. Se o código exibido tiver outro valor, o SDK emite AMOUNT_TAMPERED.
• key: recebedor confiável válido só nesta página, somado aos cadastrados no dashboard. Só o hash fica em memória. Se o SDK já tinha aceitado um código com outro recebedor, esse código passa a ser tratado como não confiável.

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

Chame antes de inserir o código de pagamento na página.

registerPaymentPayload(payload)Copiar link da seção

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

Registra manualmente a referência de um método, para quando o SDK não consegue ler o código na página (por exemplo, um Pix exibido só em <input value>). Para servir de comparação, fields precisa trazer o recebedor: pixKey (Pix), address (Bitcoin e Ethereum), vpa (UPI) ou walletId (carteiras QR).

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

Este método não envia PAYMENT_VALIDATED e não passa pela verificação de recebedores confiáveis. Prefira exibir o código como texto, o que dá a validação completa.

pause()Copiar link da seção

Proteside.pause(): void

Pausa o SDK nesta página: todos os eventos passam a ser descartados e a verificação de sobreposição para. As observações continuam instaladas, mas não reportam nada. A pausa vale até resume() ou até a página recarregar.

resume()Copiar link da seção

Proteside.resume(): void

Retoma o SDK depois de pause(). Não tem efeito quando a pausa vem do dashboard (modo desenvolvedor ou assinatura inativa).

configure(options)Copiar link da seção

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

Sobrescreve a configuração depois da inicialização, só nesta página. Na prática, só alguns campos têm efeito, porque os módulos leem o restante uma única vez ao iniciar: mode, sensitiveFields, recipients e, em parte, expectedIframeOrigins.

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

Métodos de pagamentoCopiar link da seção

O tipo PaymentMethod aceita: pix, boleto, card, bitcoin, ethereum, upi, paynow, promptpay, duitnow, qrph, hkfps, transferencias3, codi e qr_wallet.

O que não faz parte da APICopiar link da seção

• Não há inicialização manual: o SDK se inicializa sozinho a partir da tag <script> do snippet.
• Não há callbacks de ameaça (como onThreat) nem modo de depuração. A única mensagem de console é [Proteside] Initialization failed silently, quando a inicialização falha (por exemplo, chave com formato inválido).
• O bundle também cria variáveis globais internas, como window.ProteSDK e window.__PROTE_*. Elas podem mudar sem aviso: não dependa delas.

Próximos passosCopiar link da seção

• Integridade de pagamento e Pix
• Eventos e detecções