# Payment integrity and Pix

> How the SDK validates Pix, boleto, crypto and card payments on your checkout, and how to register trusted recipients.

URL: https://docs.proteside.com/en/docs/integration/payment-integrity

Besides watching scripts, the SDK checks that the payment details shown to the customer are your store's: the Pix
copy-and-paste code, the boleto digit line, the crypto address and the amount. This page explains what it validates
and how to pin your trusted recipients.

The website describes the attack each validation addresses: [Pix](https://proteside.com/en/protection/pix),
[boleto](https://proteside.com/en/protection/boleto), [crypto](https://proteside.com/en/protection/crypto) and
[credit card](https://proteside.com/en/protection/credit-card).

## How the SDK finds the payment
No special markup is needed. Once it starts, the SDK looks for payment codes on the page, including when the code is
inserted after the customer picks a payment method.

It recognizes codes by their format: Pix BRCode (EMV standard), boleto digit lines, crypto addresses, UPI VPAs and EMV
QR codes from other countries (PayNow, PromptPay, DuitNow, QR Ph, HK FPS, Transferencias 3.0, CoDi and QR wallets).

> **Show the code as text**
>
> For full coverage, show the payment code as visible text or provide it with
> [`registerPaymentPayload()`](https://docs.proteside.com/en/docs/integration/javascript-api#registerpaymentpayloadpayload).

```html title="Recommended: Pix code as text"
<div class="pix">
  <img src="/qrcode/order-1234.png" alt="Pix QR code" />
  <div id="pix-code">00020126580014br.gov.bcb.pix0136…6304ABCD</div>
  <button type="button">Copy code</button>
</div>
```

## Payment validation
The SDK compares the displayed code with that page load's reference and with the trusted recipients:

* if the displayed text changes to another code that doesn't match the reference, the SDK emits the method's
  tampering event (`PIX_TAMPERED`, `BOLETO_TAMPERED`, `CRYPTO_ADDRESS_SWAP`, `UPI_TAMPERED` or `QR_TAMPERED`);
* if the content copied to the clipboard is a code different from the reference, the SDK emits `CLIPBOARD_HIJACK`;
* when the reading is valid, the SDK emits `PAYMENT_VALIDATED`, which feeds the dashboard's **Payment Integrity**
  page.

The `PAYMENT_VALIDATED` event never carries the code or the key: only the method, whether the recipient was verified
and the number of fields.

### Card
The SDK doesn't read card data. It considers a card payment validated when it finds a known payment provider's iframe
on the page (Stripe, Adyen, Braintree, Mercado Pago, Pagar.me, PagBank, Iugu, Cielo and others) and confirms the
payment through the provider's response or the order confirmation page.

Install the snippet on the order confirmation page too.

## Trusted recipients (Pix Key Pinning)
The trusted recipients list makes sure the displayed code pays your store: the SDK checks each code's recipient
against the registered recipients. Without any registered, the SDK records who shows up at the checkout, but doesn't
alert on unknown recipients.

### Open Payment protection
In the dashboard, go to **Settings → Payment protection**, step **Who can receive your money**. Only owners and
admins can register recipients.

### Confirm the recipients seen
In **Recipients seen at your checkout**, click **It is my store** on the recipients that belong to the store. If you
don't recognize a recipient, click **I don't recognize it**: this opens a critical alert.

If your store's Pix is generated by a payment provider, prefer this path: the key the provider uses is often not the
one you know.

### Or add them manually
In **Add manually**, choose the payment method, fill in the **Key** and, optionally, a **Label**, and click **Add**.
For Pix, use a CPF, CNPJ, email, phone number (`+55…`) or random key. For boleto, paste the digit line of a boleto
issued by the store.

The recipient reaches the SDK through the remote configuration. Proteside doesn't store the key in clear text.

| Situation                              | Result                                                                                                                                                                                   |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The code's recipient is on the list    | `PAYMENT_VALIDATED` is sent with the recipient verified. The dashboard shows **Recipient matches the trusted list**.                                                                     |
| The recipient is **not** on the list   | The SDK emits the method's tampering event with the reason "untrusted recipient" and doesn't accept the code as the reference. In **Block** mode, the code's text is replaced with `⚠︎`. |
| No recipient registered for the method | No alert for unknown recipients. Register your recipients to turn verification on.                                                                                                       |

Recipient verification applies to codes that carry the recipient.

> **Treat the alert as an incident**
>
> An untrusted recipient alert is an incident, even with **Block** mode on. Open the alert in **Alerts** and
> investigate where the tampering came from.

## Expected amount
If your checkout knows the order amount, tell the SDK with
[`Proteside.expectPayment()`](https://docs.proteside.com/en/docs/integration/javascript-api#expectpaymentexpectation):

```js
// Before showing the order's Pix code
Proteside.expectPayment({ method: 'pix', amount: '19,90' })
```

`amount` enables `AMOUNT_TAMPERED`: if the code's amount differs from the expected one, the SDK raises an alert. It
accepts `19.9`, `'19,90'` or `'R$ 19,90'`, compared to two decimal places.

Call `expectPayment` **before** the code appears on the page and only after the SDK finishes starting up. See
[how to wait for the SDK](https://docs.proteside.com/en/docs/integration/javascript-api#esperar-o-sdk-carregar).

## Detected payment methods
There are no methods to select. The SDK recognizes the page's payment methods on its own, and the
**Detected payment methods** step in **Payment protection** shows what it has already seen at the checkout.

## Payment pages
Payment pages (URL patterns, with mode and methods per page) are registered through the [API](https://docs.proteside.com/en/docs/api), not
the dashboard. They're used to count payment page pageviews in your plan usage and for compliance reports.

> **Warning**
>
> The mode and methods set per page **don't reach the SDK**. The SDK behaves the same on every page where the snippet
> is installed, using the store's mode.

## In the dashboard
The **Payment Integrity** page shows one card per method with the status **NOT CONFIGURED**, **WAITING** (no payment
observed yet), **INTACT** or **TAMPERED**, plus the recipient status. See
[Payment integrity](https://docs.proteside.com/en/docs/guide/payment-integrity).

## Next steps
* [JavaScript API](https://docs.proteside.com/en/docs/integration/javascript-api)
* [Events and detections](https://docs.proteside.com/en/docs/integration/events)
