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:
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(): SDKStatusRetorna 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): voidPara 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
}): voidInforma 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). Aceita19.9,'19,90'ou'R$ 19,90', comparados com duas casas decimais. Se o código exibido tiver outro valor, o SDK emiteAMOUNT_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>
}): voidRegistra 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.