Proteside Docs

Integration

Learn how the Proteside SDK works on your checkout before you install it.

Proteside is a client-side SDK that runs on your store's payment pages. It keeps an inventory of the scripts that run in your customer's browser, detects tampering (skimming, Pix key swaps, form hijacking, data exfiltration) and sends the evidence to the dashboard. This evidence supports the PCI DSS 4.0 controls, requirements 6.4.3 and 11.6.1.

This section covers installing the SDK on your checkout and how it behaves in the browser. To use the dashboard day to day, see the User guide. If you're still evaluating the product, start with How Proteside works.

How it works

You install it as a single block of code pasted into the checkout's <head>. Inside, it has two parts with different roles:

  1. Bootstrapper (inline and synchronous). A small <script>, pasted directly into the HTML, that must be the first script in the <head>. It makes no network requests. The bootstrapper starts observing the page right away, before any other script, and stops scripts your rules forbid before they enter the page.
  2. The shield.js SDK (asynchronous, served from the CDN). Loaded from https://cdn.proteside.com/v1/shield.js with async, without blocking rendering. It reads the key from the data-key attribute, fetches the store's configuration and starts the detection modules.
  3. Remote configuration. On startup, the SDK fetches what you set in the dashboard from app.proteside.com: protection mode, rules, trusted recipients, expected iframe origins and fine-tuning settings. Changes reach the checkout within a few minutes.
  4. Event delivery. Detections and telemetry are sent in small batches to app.proteside.com. The dashboard turns relevant events into alerts and updates the Scripts inventory and SDK Health.

Why two parts?

A script loaded with async runs after other scripts on the page. Only an inline, synchronous snippet placed before all of them guarantees full coverage from the start of the page load. That's why you should never replace the bootstrapper with an external <script src>.

What Proteside detects

  • New or modified scripts after the page has loaded, classified as first-party, known third-party or unknown.
  • Blocked scripts that match your rules, and Google Tag Manager containers that aren't on the allowed list.
  • Keyloggers: a script starts capturing what is typed into a sensitive field.
  • Exfiltration: sensitive customer data is sent to an untrusted destination.
  • Payment tampering: swapping the Pix copy-and-paste code, a crypto address, a UPI VPA, the boleto bank or the amount; swapping content copied to the clipboard.
  • Form and iframe hijacking: a change to a form's action, a swapped payment provider iframe, unexpected iframes and elements overlaid on payment fields.
  • Unauthorized service workers.
  • Security headers on the payment page (CSP, HSTS and others), to detect changes.

The full list, with severities, is in Events and detections.

What Proteside doesn't collect

The SDK is designed not to carry payment data:

  • it never reads values typed into form fields and never records keystrokes;
  • it never sends card numbers, CVVs, Pix keys, copy-and-paste codes, crypto addresses or boleto digit lines;
  • it never sends clipboard content, request bodies or script source code (only hashes, sizes and the names of patterns it found);
  • it doesn't set cookies or write to localStorage.

There are a few points you should know about, such as the full page URL being sent. See Privacy and LGPD.

From the first pageview to the dashboard

Here's what happens when a customer opens a checkout with the snippet installed:

  1. The browser runs the bootstrapper (under 1 ms) and keeps loading the page as usual.
  2. shield.js arrives from the CDN and fetches the store's configuration.
  3. The SDK sends a PAGEVIEW. Right after the page loads, the SDK establishes the page baseline. Scripts present at that moment go into the inventory and need your review in Scripts.
  4. Scripts the dashboard doesn't know yet show up in Scripts with the Needs review status.
  5. From then on, any new script or suspicious behavior becomes a detection.
  6. Events are sent in small batches and when the customer leaves the page. The Proteside active indicator at the top of the dashboard and the SDK Health page start reflecting real traffic.

The decision on each script in the inventory (authorize or block) is yours, on the Scripts page.

Next steps

On this page