JavaScript API

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 and recipient, or for diagnostics.

All methods are guarded against errors and never throw: if something fails, the call is ignored.

Wait for the SDK to loadCopy Anchor Link

window.Proteside exists as soon as shield.js runs, but the SDK only finishes starting up after fetching the remote configuration, which can take up to about 2 seconds.

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 as usual, without the SDK
  sdk.expectPayment({ method: 'pix', amount: '19,90' });
});

Never make your checkout depend on the SDK being present: an ad blocker or a network failure can prevent it from loading.

MethodsCopy Anchor Link

getStatus()Copy Anchor Link

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
  mode: 'monitor' | 'block'
  paused: boolean                 // local pause, developer mode or inactive subscription
  channel: 'stable' | 'latest'
  calibrating: boolean            // true during calibration
  activeThreats: number           // tampering detected on this page
  paymentMethodsMonitored: PaymentMethod[]
  version: string                 // e.g. '1.1.1'
  installationOrderValid: boolean // false = there's a script before the bootstrapper
  overlayCheckIntervalMs: number
  rulesApplied: boolean
  recipientsPinned: number        // number of trusted recipients received from the dashboard
  cardCheckoutOpen: boolean
  cardCheckoutProvider: string | null
}

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

pageChanged(path)Copy Anchor Link

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');

Calibration and the script inventory are not redone: they apply to the whole page load.

expectPayment(expectation)Copy Anchor Link

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

Tells the SDK what 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.
• key: a trusted recipient valid on this page only, added to the ones registered in the dashboard. Only the hash is kept in memory. If the SDK had already accepted a code with a different recipient, that code is then treated as untrusted.

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

Call it before inserting the payment code into the page.

registerPaymentPayload(payload)Copy Anchor Link

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

Manually registers a method's reference, for when the SDK can't read the code on the page (for example, a Pix code shown only in <input value>). To be useful for comparison, fields must include the recipient: pixKey (Pix), address (Bitcoin and Ethereum), vpa (UPI) or walletId (QR wallets).

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

This method does not send PAYMENT_VALIDATED and does not go through trusted recipient verification. Prefer showing the code as text, which gives you full validation.

pause()Copy Anchor Link

Proteside.pause(): void

Pauses the SDK on this page: all events are discarded and the overlay check stops. The observation points stay in place, but report nothing. The pause lasts until resume() or until the page reloads.

resume()Copy Anchor Link

Proteside.resume(): void

Resumes the SDK after pause(). Has no effect when the pause comes from the dashboard (developer mode or inactive subscription).

configure(options)Copy Anchor Link

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

Overrides the configuration after initialization, on this page only. In practice, only a few fields have any effect, because the modules read the rest only once at startup: mode, sensitiveFields, recipients and, partly, expectedIframeOrigins.

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

Payment methodsCopy Anchor Link

The PaymentMethod type accepts: pix, boleto, card, bitcoin, ethereum, upi, paynow, promptpay, duitnow, qrph, hkfps, transferencias3, codi and qr_wallet.

What isn't part of the APICopy Anchor Link

• 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).
• The bundle also creates internal global variables, such as window.ProteSDK and window.__PROTE_*. They may change without notice: don't depend on them.

Next stepsCopy Anchor Link

• Payment integrity and Pix
• Events and detections