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().
<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_TAMPEREDouQR_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ção | Resultado |
|---|---|
| Recebedor do código está na lista | PAYMENT_VALIDATED sai com o recebedor verificado. O dashboard mostra Recebedor confere com a lista confiável. |
| Recebedor não está na lista | O 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étodo | Sem 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.