Integridade de pagamento e Pix

Além de vigiar scripts, o SDK confere se os dados de pagamento exibidos ao cliente são os da sua loja: o código Pix copia e cola, a linha digitável do boleto, o endereço cripto e o valor. Esta página explica como ele encontra esses dados, o que é validado e como fixar os recebedores confiáveis.

Como o SDK encontra o pagamentoCopiar link da seção

Não é preciso marcação especial. Depois de iniciar, o SDK procura códigos de pagamento na página:

1. em seletores conhecidos, como [data-pix-code], #pix-code, .pix-copia-cola, [data-pix-qr], [data-crypto-address], #crypto-address, .wallet-address, [data-payment-value] e [data-qr-value];
2. em todo texto visível do <body> com 20 a 1.000 caracteres;
3. em mudanças na página (por exemplo, quando o código Pix é inserido depois de o cliente escolher Pix);
4. a cada 2 segundos, durante o primeiro minuto, como garantia.

O código é reconhecido pelo formato: BRCode do Pix (padrão EMV), linha digitável de boleto (47 ou 48 dígitos), endereços Bitcoin e Ethereum, VPA UPI e QR codes EMV de outros países (PayNow, PromptPay, DuitNow, QR Ph, HK FPS, Transferencias 3.0, CoDi e carteiras QR).

<div class="pix">
  <img src="/qrcode/pedido-1234.png" alt="QR code Pix" />
  <div id="pix-code">00020126580014br.gov.bcb.pix0136…6304ABCD</div>
  <button type="button">Copiar código</button>
</div>

Validação do pagamentoCopiar link da seção

A primeira leitura válida de cada método na página vira a referência daquele carregamento. A partir daí:

• se o texto exibido mudar para outro código que não bate com a referência, o SDK emite o evento de adulteração do método (PIX_TAMPERED, BOLETO_TAMPERED, CRYPTO_ADDRESS_SWAP, UPI_TAMPERED ou QR_TAMPERED);
• se o conteúdo copiado para a área de transferência for um código diferente da referência, o SDK emite CLIPBOARD_HIJACK;
• quando a leitura é válida, o SDK emite PAYMENT_VALIDATED, que alimenta a página Integridade de Pagamento do dashboard.

PAYMENT_VALIDATED é enviado na primeira detecção, quando o código muda para o mesmo recebedor (por exemplo, um QR regerado) e, no máximo, a cada 60 segundos enquanto o cliente está na página. O evento nunca leva o código nem a chave: só o método, se o recebedor foi verificado e a quantidade de campos.

CartãoCopiar link da seção

O SDK não lê dados de cartão. Ele considera um pagamento com cartão validado quando:

• encontra na página o iframe de um provedor de pagamento conhecido (Stripe, Adyen, Braintree, Mercado Pago, Pagar.me, PagBank, Iugu, Cielo e outros) e observa uma resposta de sucesso a uma requisição de cobrança; ou
• encontrou o iframe e, em até 10 minutos, o cliente chega a uma página de confirmação com obrigado, sucesso, thank-you, success, confirmacao ou order-complete no caminho.

Para o segundo caso funcionar, o snippet precisa estar também na página de confirmação.

Recebedores confiáveis (Pix Key Pinning)Copiar link da seção

Sem uma lista de recebedores, um código de pagamento adulterado desde a primeira exibição viraria a referência, e nada pareceria errado. A lista de recebedores confiáveis resolve isso: o SDK confere o recebedor de cada código com as chaves que pertencem à sua loja.

O SDK recebe apenas os hashes. Para comparar, ele normaliza o recebedor lido no checkout (e-mail em minúsculas, telefone só com dígitos, boleto pelos 3 primeiros dígitos) e calcula o mesmo hash.

LimitaçõesCopiar link da seção

• Pix dinâmico. Um BRCode dinâmico traz uma URL de cobrança em vez da chave do recebedor. Sem chave no código, não há verificação de recebedor; continua valendo a comparação com a primeira leitura.
• Boleto de arrecadação (linha de 48 dígitos, de concessionárias e tributos) não tem código de banco e fica sem verificação de recebedor.
• Pix em campo de formulário não é lido (veja o aviso no início desta página).
• Carteiras QR e pagamentos instantâneos de outros países são reconhecidos e validados, mas não aceitam recebedor cadastrado.

Valor esperado e recebedor da sessãoCopiar link da seção

Se o seu checkout sabe o valor e a chave do pedido, informe ao SDK com Proteside.expectPayment():

// Antes de exibir o código Pix do pedido
Proteside.expectPayment({ method: 'pix', amount: '19,90', key: 'pix@minhaloja.com.br' })

• amount habilita AMOUNT_TAMPERED: se o valor do código for diferente do esperado, o SDK alerta. Aceita 19.9, '19,90' ou 'R$ 19,90', comparados com duas casas decimais.
• key adiciona um recebedor confiável só para esta página. Só o hash fica em memória.

Chame expectPayment antes de o código aparecer na página e só depois que o SDK terminar de iniciar. Veja como esperar o SDK.

Métodos de pagamentoCopiar link da seção

Em Proteção do pagamento → Métodos de pagamento você marca os métodos que a loja oferece. No navegador, essa lista só define o que aparece em getStatus().paymentMethodsMonitored e quando o SDK para de procurar códigos.

Páginas de pagamentoCopiar link da seção

As páginas de pagamento (padrões de URL, com modo e métodos por página) são cadastradas pela API, não pelo dashboard. Elas servem para contar as pageviews de páginas de pagamento no uso do plano e para os relatórios de conformidade.

No dashboardCopiar link da seção

A página Integridade de Pagamento mostra um cartão por método com o status NÃO CONFIGURADO, AGUARDANDO (nenhum pagamento observado ainda), ÍNTEGRO ou ADULTERADO, e a situação do recebedor. Veja Integridade de pagamento.

Próximos passosCopiar link da seção

• API JavaScript
• Eventos e detecções