Proteside Docs

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:

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 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(): SDKStatus

Returns 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): void

For 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
}): void

Tells 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 accepts 19.9, '19,90' or 'R$ 19,90', compared to two decimal places. If the displayed code has a different amount, the SDK emits AMOUNT_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>
}): void

Registers 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.

Next steps

On this page