Proteside Docs

Integridade de pagamento e Pix

Como o SDK valida Pix, boleto, cripto e cartão no checkout e como cadastrar recebedores confiáveis.

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 o que é validado e como fixar os recebedores confiáveis.

O site descreve o ataque que cada validação combate: Pix, boleto, criptomoedas e cartão de crédito.

Como o SDK encontra o pagamento

Não é preciso marcação especial. Depois de iniciar, o SDK procura códigos de pagamento na página, inclusive quando o código é inserido depois de o cliente escolher o meio de pagamento.

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

Exiba o código como texto

Para cobertura completa, exiba o código de pagamento como texto visível ou informe-o com registerPaymentPayload().

Recomendado: código Pix como texto
<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 pagamento

O SDK compara o código exibido com a referência daquele carregamento e com os recebedores confiáveis:

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

O evento PAYMENT_VALIDATED nunca leva o código nem a chave: só o método, se o recebedor foi verificado e a quantidade de campos.

Cartã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 confirma o pagamento pela resposta do provedor ou pela página de confirmação do pedido.

Instale o snippet também na página de confirmação do pedido.

Recebedores confiáveis (Pix Key Pinning)

A lista de recebedores confiáveis garante que o código exibido pague a sua loja: o SDK confere o recebedor de cada código com os recebedores cadastrados. Sem cadastro, o SDK registra quem aparece no checkout, mas não alerta sobre recebedores desconhecidos.

Abra Proteção do pagamento

No dashboard, vá em Configurações → Proteção do pagamento, passo Quem pode receber o seu dinheiro. Só proprietários e administradores podem cadastrar.

Confirme os recebedores vistos

Em Recebedores vistos no seu checkout, clique em É da minha loja nos recebedores que pertencem à loja. Se não reconhecer um recebedor, clique em Não reconheço: isso abre um alerta crítico.

Se o Pix da loja é gerado por um provedor de pagamento, prefira este caminho: a chave usada pelo provedor costuma não ser a que você conhece.

Ou cadastre manualmente

Em Cadastrar manualmente, escolha o meio de pagamento, preencha a Chave e, se quiser, um Rótulo, e clique em Adicionar. Para Pix, use CPF, CNPJ, e-mail, telefone (+55…) ou chave aleatória. Para boleto, cole a linha digitável de um boleto emitido pela loja.

O recebedor chega ao SDK pela configuração remota. O Proteside não guarda a chave em claro.

SituaçãoResultado
Recebedor do código está na listaPAYMENT_VALIDATED sai com o recebedor verificado. O dashboard mostra Recebedor confere com a lista confiável.
Recebedor não está na listaO SDK emite o evento de adulteração do método com o motivo "recebedor não confiável" e não aceita o código como referência. No modo Bloquear, o texto do código é trocado por ⚠︎.
Nenhum recebedor cadastrado para o métodoSem alerta de recebedor desconhecido. Cadastre os recebedores para ativar a verificação.

A verificação de recebedor se aplica aos códigos que trazem o recebedor.

Trate o alerta como incidente

Um alerta de recebedor não confiável é um incidente, mesmo com o modo Bloquear ligado. Abra o alerta em Alertas e investigue a origem da adulteração.

Valor esperado

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

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

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.

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.

Meios de pagamento detectados

Não há métodos para marcar. O SDK reconhece sozinho os meios de pagamento da página, e o passo Meios de pagamento detectados, em Proteção do pagamento, mostra o que ele já viu no checkout.

Páginas de pagamento

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.

O modo e os métodos definidos por página não chegam ao SDK. O SDK roda igual em todas as páginas em que o snippet estiver, com o modo da loja.

No dashboard

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 passos

Nesta página