Proteside Docs

Payment integrity and Pix

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

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, boleto, crypto and 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().

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.

SituationResult
The code's recipient is on the listPAYMENT_VALIDATED is sent with the recipient verified. The dashboard shows Recipient matches the trusted list.
The recipient is not on the listThe 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 methodNo 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():

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

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, not the dashboard. They're used to count payment page pageviews in your plan usage and for compliance reports.

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.

Next steps

On this page