Instalar o snippet
O snippet é a forma mais curta de capturar evidência: duas tags no seu checkout e uma chamada por evento. Ele conversa com o canal navegador por você.
Se o seu checkout é renderizado no servidor, ou se você prefere não carregar script de terceiro, pule esta página e chame o endpoint direto.
Onde pegar o token
Seção intitulada “Onde pegar o token”No painel, em Configurações › Integrações, na linha do Rapid Capture. Ative e o painel mostra o snippet pronto na aba Instalação, já com o token da loja escolhida no topo. Dá para ativar quem tem Prevenção ou Disputa ativa.
O token é publicável: ele fica no HTML da sua loja e não precisa de proteção. Com ele só é possível enviar evento, nunca ler dado. Evento que não corresponde a um pedido seu é descartado.
Em qual site o token vale
Seção intitulada “Em qual site o token vale”O token passa a valer só no primeiro site em que for usado, nos subdomínios dele e no domínio acima (loja.com.br vale também para www.loja.com.br e checkout.loja.com.br; travado em checkout.loja.com.br, vale também para loja.com.br). Evento vindo de outro site é recusado. Assim, se alguém copiar o snippet para outra página, os eventos de lá não se misturam com os seus.
Testes em localhost, por IP ou em domínio interno (.local, .test) não contam como primeiro site. Os sites em que o token vale aparecem no detalhe do Rapid Capture (Gerenciar, aba Visão geral). Se outro site tentar usar o código, ele aparece ali com o botão Autorizar: é o caminho para lojas com mais de um domínio (checkout num, área de membros em outro). Remover tira um site; sem nenhum, o token volta a travar no próximo site que usar o código.
Se o token vazar, Gerar novo código troca o token na hora. O anterior para de funcionar e você cola o código novo no seu site. O painel volta a mostrar que aguarda o primeiro evento até chegar um evento depois da troca.
Instalação
Seção intitulada “Instalação”<script>window.rapid=window.rapid||function(){(window.rapid.q=window.rapid.q||[]).push(arguments)};rapid('init',{token:'seu_token_publicavel'})</script><script async src="https://api.rapidchargeback.com/sdk/v1/rapid.js"></script>A primeira tag cria uma fila: as chamadas a rapid(...) feitas antes de o script terminar de carregar ficam guardadas e são enviadas quando ele chega. Por isso o script pode ser async, e se ele não carregar (bloqueador, rede instável, navegador antigo) as chamadas da sua página só ficam paradas, nunca viram erro no seu checkout.
Coloque o snippet o quanto antes na página, de preferência no <head>: o init já prepara a identificação do aparelho, e quanto antes ele começa, mais rápido a identificação sai no checkout. A identificação em si só acontece no checkout: as outras páginas com o snippet não identificam o aparelho.
O snippet antigo (o script sem async e o init logo depois) continua funcionando.
O script tem cerca de 8 KB, não tem dependência e não bloqueia a página.
Chamadas
Seção intitulada “Chamadas”// Compra finalizada. Captura também os dados do aparelho.rapid('checkout', { order_ref: 'TXN-2026-001' })
// Cliente aceitou os termos.rapid('terms', { order_ref: 'TXN-2026-001' })
// Cliente acessou o produto.rapid('track', 'access_log', { order_ref: 'TXN-2026-001' })
// Cliente usou o produto ou serviço.rapid('track', 'usage_log', { order_ref: 'TXN-2026-001' })| Chamada | Evento gerado | Payload que o snippet monta |
|---|---|---|
rapid('checkout', …) | checkout | identificação do aparelho |
rapid('terms', …) | terms_acceptance | a URL da página |
rapid('track', 'access_log', …) | access_log | a URL da página |
rapid('track', 'usage_log', …) | usage_log | a URL da página |
O order_ref é obrigatório em todas, como texto ou número. É o identificador do pedido no seu sistema, o mesmo que você manda em external_id ao criar a transação. Ver Tipos e payload.
Chamada sem order_ref é ignorada, não gera evento nem erro visível.
Fire and forget
Seção intitulada “Fire and forget”O snippet nunca quebra o checkout, e isso tem um custo que vale conhecer:
- toda chamada é silenciosa. Ele não lança exceção, não devolve promessa e não lê a resposta
- erro de validação (tipo errado,
order_reflongo demais) não aparece no console - falha de rede não é retentada no navegador
Para testar a integração, chame o endpoint do navegador direto com curl, onde você vê o status e a mensagem. Depois de validado, o snippet faz o mesmo em produção.
O envio usa navigator.sendBeacon quando disponível, com fetch em modo keepalive como alternativa. Os dois sobrevivem à navegação para a página seguinte, então o evento de checkout não se perde no redirecionamento do pagamento. Se a página sair antes de a identificação do aparelho terminar, o evento vai na saída com a identificação própria do snippet. Por isso, se a página redireciona logo depois do checkout, prefira chamá-lo numa página em que o comprador fica alguns instantes, como a de confirmação do pedido.
Identificação do aparelho
Seção intitulada “Identificação do aparelho”No checkout, o snippet identifica o aparelho antes de enviar o evento. Ele tenta o Fingerprint, com teto de 2 segundos, e cai numa identificação própria se não conseguir (identificador em localStorage mais um hash de atributos do navegador).
O resultado vai no campo fp do payload:
fp | Significa |
|---|---|
pro | identificação do Fingerprint, validada do lado servidor |
fallback | identificação própria do snippet |
A diferença é prática: só a identificação validada preenche aparelho e IP da transação e gera o registro de verificação. Ver O evento checkout.
Se o seu site tem CSP restritiva, libere https://api.rapidchargeback.com em script-src e connect-src, e dê ao <script> inline do snippet o mesmo nonce dos seus outros scripts. Para o Fingerprint, libere também https://fpjscdn.net em script-src, https://api.fpjs.io e https://*.api.fpjs.io em connect-src, e blob: em worker-src. Acrescente esses itens às diretivas que o seu site já usa, sem tirar o que já está nelas:
script-src 'self' 'nonce-SEU_NONCE' https://api.rapidchargeback.com https://fpjscdn.net;connect-src 'self' https://api.rapidchargeback.com https://api.fpjs.io https://*.api.fpjs.io;worker-src 'self' blob:;Com tudo liberado, a identificação melhora. Se algum desses itens ficar bloqueado, a captura continua funcionando: os eventos chegam, mas o checkout pode não preencher aparelho nem IP.
Como saber se está funcionando
Seção intitulada “Como saber se está funcionando”O mesmo detalhe do Rapid Capture no painel mostra se a loja já recebeu evento e quando foi o último. Conta o evento de um pedido cuja transação já está na Rapid. Depois de instalar, faça uma compra de teste e confira ali depois que a transação dela chegar à Rapid.