Integridad de pagos y Pix
Cómo valida el SDK Pix, boleto, cripto y tarjeta en el checkout y cómo registrar destinatarios confiables.
Además de vigilar scripts, el SDK comprueba que los datos de pago que se muestran al cliente sean los de tu tienda: el código Pix copia y pega, la línea digitable del boleto, la dirección cripto y el monto. Esta página explica qué se valida y cómo fijar los destinatarios confiables.
El sitio describe el ataque que combate cada validación: Pix, boleto, criptomonedas y tarjeta de crédito.
Cómo encuentra el SDK el pago
No hace falta ningún marcado especial. Después de iniciar, el SDK busca códigos de pago en la página, incluso cuando el código se inserta después de que el cliente elige el medio de pago.
El código se reconoce por su formato: BRCode de Pix (estándar EMV), línea digitable de boleto, direcciones cripto, VPA de UPI y códigos QR EMV de otros países (PayNow, PromptPay, DuitNow, QR Ph, HK FPS, Transferencias 3.0, CoDi y billeteras QR).
Muestra el código como texto
Para una cobertura completa, muestra el código de pago como texto visible o infórmalo con
registerPaymentPayload().
<div class="pix">
<img src="/qrcode/pedido-1234.png" alt="Código QR Pix" />
<div id="pix-code">00020126580014br.gov.bcb.pix0136…6304ABCD</div>
<button type="button">Copiar código</button>
</div>Validación del pago
El SDK compara el código mostrado con la referencia de esa carga y con los destinatarios confiables:
- si el texto mostrado cambia a otro código que no coincide con la referencia, el SDK emite el evento de manipulación
del método (
PIX_TAMPERED,BOLETO_TAMPERED,CRYPTO_ADDRESS_SWAP,UPI_TAMPEREDoQR_TAMPERED); - si el contenido copiado al portapapeles es un código distinto de la referencia, el SDK emite
CLIPBOARD_HIJACK; - cuando la lectura es válida, el SDK emite
PAYMENT_VALIDATED, que alimenta la página Integridad de Pagos del dashboard.
El evento PAYMENT_VALIDATED nunca lleva el código ni la clave: solo el método, si el destinatario se verificó y la
cantidad de campos.
Tarjeta
El SDK no lee datos de tarjeta. Considera validado un pago con tarjeta cuando encuentra en la página el iframe de un proveedor de pagos conocido (Stripe, Adyen, Braintree, Mercado Pago, Pagar.me, PagBank, Iugu, Cielo y otros) y confirma el pago por la respuesta del proveedor o por la página de confirmación del pedido.
Instala el snippet también en la página de confirmación del pedido.
Destinatarios confiables (Pix Key Pinning)
La lista de destinatarios confiables garantiza que el código mostrado pague a tu tienda: el SDK compara el destinatario de cada código con los destinatarios registrados. Sin registro, el SDK anota quién aparece en el checkout, pero no alerta sobre destinatarios desconocidos.
Abre Protección del pago
En el dashboard, ve a Ajustes → Protección del pago, paso Quién puede recibir tu dinero. Solo los propietarios y administradores pueden registrar destinatarios.
Confirma los destinatarios vistos
En Destinatarios vistos en tu checkout, haz clic en Es de mi tienda en los destinatarios que pertenecen a la tienda. Si no reconoces un destinatario, haz clic en No lo reconozco: eso abre una alerta crítica.
Si el Pix de la tienda lo genera un proveedor de pagos, prefiere este camino: la clave que usa el proveedor suele no ser la que conoces.
O regístralos manualmente
En Registrar manualmente, elige el medio de pago, completa la Clave y, si quieres, una Etiqueta, y haz clic
en Agregar. Para Pix, usa CPF, CNPJ, correo electrónico, teléfono (+55…) o clave aleatoria. Para boleto, pega la
línea digitable de un boleto emitido por la tienda.
El destinatario llega al SDK mediante la configuración remota. Proteside no guarda la clave en texto claro.
| Situación | Resultado |
|---|---|
| El destinatario del código está en la lista | PAYMENT_VALIDATED sale con el destinatario verificado. El dashboard muestra El destinatario coincide con la lista confiable. |
| El destinatario no está en la lista | El SDK emite el evento de manipulación del método con el motivo "destinatario no confiable" y no acepta el código como referencia. En modo Bloquear, el texto del código se reemplaza por ⚠︎. |
| Ningún destinatario registrado para el método | Sin alerta de destinatario desconocido. Registra los destinatarios para activar la verificación. |
La verificación de destinatario se aplica a los códigos que traen el destinatario.
Trata la alerta como un incidente
Una alerta de destinatario no confiable es un incidente, incluso con el modo Bloquear activado. Abre la alerta en Alertas e investiga el origen de la manipulación.
Monto esperado
Si tu checkout conoce el monto del pedido, infórmalo al SDK con
Proteside.expectPayment():
// Antes de mostrar el código Pix del pedido
Proteside.expectPayment({ method: 'pix', amount: '19,90' })amount habilita AMOUNT_TAMPERED: si el monto del código es distinto del esperado, el SDK alerta. Acepta 19.9,
'19,90' o 'R$ 19,90', comparados con dos decimales.
Llama a expectPayment antes de que el código aparezca en la página y solo después de que el SDK termine de
iniciar. Consulta cómo esperar al SDK.
Medios de pago detectados
No hay métodos que marcar. El SDK reconoce por sí solo los medios de pago de la página, y el paso Medios de pago detectados, en Protección del pago, muestra lo que ya vio en el checkout.
Páginas de pago
Las páginas de pago (patrones de URL, con modo y métodos por página) se registran mediante la API, no desde el dashboard. Sirven para contar los pageviews de páginas de pago en el uso del plan y para los reportes de cumplimiento.
El modo y los métodos definidos por página no llegan al SDK. El SDK funciona igual en todas las páginas en las que esté el snippet, con el modo de la tienda.
En el dashboard
La página Integridad de Pagos muestra una tarjeta por método con el estado SIN CONFIGURAR, ESPERANDO (todavía no se observó ningún pago), INTACTO o MANIPULADO, y la situación del destinatario. Consulta Integridad de pagos.