Proteside Docs

API JavaScript

Métodos do objeto window.Proteside para consultar o status e informar pagamentos.

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 esperado 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 carregar

window.Proteside passa a existir assim que o shield.js executa, mas o SDK só termina de iniciar depois de carregar a configuração da loja.

Não há evento de pronto

O SDK não dispara evento, promise ou callback quando fica pronto. Com exceção de getStatus(), os métodos chamados antes de o SDK terminar de iniciar são ignorados sem aviso, inclusive expectPayment().

Para chamar a API com segurança, aguarde getStatus().initialized ficar true:

whenProtesideReady.js
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étodos

getStatus()

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
  version: string                 // ex.: '1.2.0'
  installationOrderValid: boolean // false = há script antes do snippet
}
const { initialized, version, installationOrderValid } = Proteside.getStatus();

pageChanged(path)

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 referência da página e o inventário de scripts valem para o carregamento inteiro.

expectPayment(expectation)

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

Informa o valor 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.
Proteside.expectPayment({ method: 'pix', amount: '19,90' });

Chame antes de inserir o código de pagamento na página. Os recebedores confiáveis são cadastrados só no dashboard. Veja Integridade de pagamento e Pix.

registerPaymentPayload(payload)

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

Registra a referência de um método de pagamento. Use quando o código de pagamento não aparece como texto visível na página. Para servir de comparação, fields precisa trazer o recebedor: pixKey (Pix), address (carteiras cripto), vpa (UPI) ou walletId (carteiras QR).

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

Sempre que possível, exiba o código como texto visível na página, o que dá a validação completa.

Métodos de pagamento

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

O que não faz parte da API

  • 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).
  • Use só os métodos documentados nesta página. Qualquer outra propriedade do SDK é interna e pode mudar sem aviso.

Próximos passos

Nesta página