# JavaScript API

> Methods on the window.Proteside object to check status and report payments.

URL: https://docs.proteside.com/en/docs/integration/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, 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`:

```js title="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()````ts
Proteside.getStatus(): SDKStatus
```

Returns the SDK's current state. You can call it at any time: before the SDK starts, it returns
`initialized: false`.

```ts
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
}
```

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

### `pageChanged(path)````ts
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.

```js
// 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)````ts
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`.

```js
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](https://docs.proteside.com/en/docs/integration/payment-integrity).

### `registerPaymentPayload(payload)````ts
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).

```js
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
* [Payment integrity and Pix](https://docs.proteside.com/en/docs/integration/payment-integrity)
* [Events and detections](https://docs.proteside.com/en/docs/integration/events)
