JavaScript API
Methods on the window.Proteside object to check status and report payments.
The SDK exposes the global window.Proteside object. Most stores don't need it: the snippet alone already protects
the checkout. Use the API when your checkout is a single-page application, when you want to provide a payment's
expected amount, or for diagnostics.
All methods are guarded against errors and never throw: if something fails, the call is ignored.
Wait for the SDK to load
window.Proteside exists as soon as shield.js runs, but the SDK only finishes starting up after loading the store's
configuration.
There's no ready event
The SDK doesn't fire an event, promise or callback when it's ready. Except for getStatus(), methods called
before the SDK finishes starting up are silently ignored, including expectPayment().
To call the API safely, wait for getStatus().initialized to become 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 missing or blocked
setTimeout(check, 100);
})();
});
}
// Usage
whenProtesideReady().then((sdk) => {
if (!sdk) return; // carry on with the checkout without the SDK
sdk.expectPayment({ method: 'pix', amount: '19,90' });
});Never make the checkout depend on the SDK being present: an ad blocker or a network failure can prevent it from loading.
Methods
getStatus()
Proteside.getStatus(): SDKStatusReturns the SDK's current state. You can call it at any time: before the SDK starts, it returns
initialized: false.
interface SDKStatus {
initialized: boolean // the SDK finished starting up
version: string // e.g. '1.2.0'
installationOrderValid: boolean // false = there's a script before the snippet
}const { initialized, version, installationOrderValid } = Proteside.getStatus();pageChanged(path)
Proteside.pageChanged(path: string): voidFor single-page applications (React, Vue, Next.js, Nuxt). Notify the SDK when the route changes without a page
reload. The SDK clears the previous route's payment references and expected values, re-reads the security headers
and sends a PAGEVIEW for the new route.
// E.g. in your framework's route change listener
Proteside.pageChanged('/checkout/payment');The page baseline and the script inventory apply to the whole page load.
expectPayment(expectation)
Proteside.expectPayment(expectation: {
method: PaymentMethod
amount?: string | number
}): voidTells the SDK the amount the checkout expects from this page's payment.
amount: expected amount, in the same unit as the code (reais, for Pix and boleto). It accepts19.9,'19,90'or'R$ 19,90', compared to two decimal places. If the displayed code has a different amount, the SDK emitsAMOUNT_TAMPERED.
Proteside.expectPayment({ method: 'pix', amount: '19,90' });Call it before inserting the payment code into the page. Trusted recipients are registered in the dashboard only. See Payment integrity and Pix.
registerPaymentPayload(payload)
Proteside.registerPaymentPayload(payload: {
method: PaymentMethod
fields: Record<string, string>
}): voidRegisters a payment method's reference. Use it when the payment code doesn't appear as visible text on the page. To
be useful for comparison, fields must include the recipient: pixKey (Pix), address (crypto wallets), vpa
(UPI) or walletId (QR wallets).
Proteside.registerPaymentPayload({ method: 'pix', fields: { pixKey: 'pix@mystore.com' } });Whenever possible, show the code as visible text on the page, which gives you full validation.
Payment methods
The PaymentMethod type accepts: pix, boleto, card, bitcoin, ethereum, tron, solana, upi, paynow,
promptpay, duitnow, qrph, hkfps, transferencias3, codi and qr_wallet.
What isn't part of the API
- There's no manual initialization: the SDK initializes itself from the snippet's
<script>tag. - There are no threat callbacks (such as
onThreat) and no debug mode. The only console message is[Proteside] Initialization failed silently, when initialization fails (for example, a key with an invalid format). - Only use the methods documented on this page. Any other SDK property is internal and may change without notice.