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().
<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_TAMPEREDorQR_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():
// 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.