Integridad de pagos y Pix

Además de vigilar los scripts, el SDK comprueba que los datos de pago que ve el 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 cómo encuentra esos datos, qué se valida y cómo fijar los destinatarios confiables.

Cómo encuentra el SDK el pagoCopiar enlace de la sección

No hace falta ningún marcado especial. Después de iniciar, el SDK busca códigos de pago en la página:

1. en selectores conocidos, como [data-pix-code], #pix-code, .pix-copia-cola, [data-pix-qr], [data-crypto-address], #crypto-address, .wallet-address, [data-payment-value] y [data-qr-value];
2. en todo el texto visible del <body> que tenga entre 20 y 1.000 caracteres;
3. en los cambios de la página (por ejemplo, cuando el código Pix se inserta después de que el cliente elige Pix);
4. cada 2 segundos, durante el primer minuto, como respaldo.

El código se reconoce por su formato: BRCode de Pix (estándar EMV), línea digitable de boleto (47 o 48 dígitos), direcciones Bitcoin y Ethereum, 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).

<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 pagoCopiar enlace de la sección

La primera lectura válida de cada método en la página se convierte en la referencia de esa carga. A partir de ahí:

• 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_TAMPERED o QR_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.

PAYMENT_VALIDATED se envía en la primera detección, cuando el código cambia para el mismo destinatario (por ejemplo, un QR regenerado) y, como máximo, cada 60 segundos mientras el cliente está en la página. El evento nunca lleva el código ni la clave: solo el método, si el destinatario se verificó y la cantidad de campos.

TarjetaCopiar enlace de la sección

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 observa una respuesta exitosa a una solicitud de cobro; o
• encontró el iframe y, en un plazo de 10 minutos, el cliente llega a una página de confirmación con obrigado, sucesso, thank-you, success, confirmacao u order-complete en la ruta.

Para que el segundo caso funcione, el snippet también debe estar en la página de confirmación.

Destinatarios confiables (Pix Key Pinning)Copiar enlace de la sección

Sin una lista de destinatarios, un código de pago manipulado desde la primera vez que se muestra se convertiría en la referencia, y nada parecería estar mal. La lista de destinatarios confiables resuelve esto: el SDK compara el destinatario de cada código con las claves que pertenecen a tu tienda.

El SDK recibe solo los hashes. Para comparar, normaliza el destinatario leído en el checkout (correo en minúsculas, teléfono solo con dígitos, boleto por los 3 primeros dígitos) y calcula el mismo hash.

LimitacionesCopiar enlace de la sección

• Pix dinámico. Un BRCode dinámico trae una URL de cobro en lugar de la clave del destinatario. Sin clave en el código, no hay verificación de destinatario; sigue aplicando la comparación con la primera lectura.
• Boleto de recaudación (línea de 48 dígitos, de concesionarias y tributos) no tiene código de banco y queda sin verificación de destinatario.
• Pix en un campo de formulario no se lee (consulta el aviso al principio de esta página).
• Billeteras QR y pagos instantáneos de otros países se reconocen y se validan, pero no admiten destinatarios registrados.

Monto esperado y destinatario de la sesiónCopiar enlace de la sección

Si tu checkout conoce el monto y la clave del pedido, infórmalos al SDK con Proteside.expectPayment():

// Antes de mostrar el código Pix del pedido
Proteside.expectPayment({ method: 'pix', amount: '19,90', key: 'pix@mitienda.com' })

• 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.
• key agrega un destinatario confiable solo para esta página. Solo el hash queda en memoria.

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.

Métodos de pagoCopiar enlace de la sección

En Protección del pago → Métodos de pago marcas los métodos que ofrece la tienda. En el navegador, esa lista solo define lo que aparece en getStatus().paymentMethodsMonitored y cuándo el SDK deja de buscar códigos.

Páginas de pagoCopiar enlace de la sección

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.

En el dashboardCopiar enlace de la sección

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.

Próximos pasosCopiar enlace de la sección

• API de JavaScript
• Eventos y detecciones