Produção e segurança
Configurações de CSP, conformidade PCI DSS e compatibilidade de navegadores para usar o SDK em produção.
Content Security Policy (CSP)
O SDK carrega scripts externos para 3DS e análise de fraude. Se o seu site usa headers Content-Security-Policy, você precisa permitir esses domínios — caso contrário, os scripts serão bloqueados silenciosamente e o 3DS / antifraude não funcionarão.
Domínios necessários
| Funcionalidade | Domínio | Uso |
|---|---|---|
| 3DS | mpi.braspag.com.br | Script BP.Mpi para autenticação 3DS |
| Antifraude | *.online-metrix.net | ThreatMetrix device fingerprinting |
| IP público | api.ipify.org | Detecção do IP público do comprador |
| API | api.soarlabz.com | Endpoints do SDK |
Exemplo de CSP header
Content-Security-Policy:
script-src 'self' https://mpi.braspag.com.br https://*.online-metrix.net;
connect-src 'self' https://api.payhubrasil.com.br https://api.ipify.org https://*.online-metrix.net;
frame-src https://mpi.braspag.com.br https://*.online-metrix.net;
img-src 'self' https://*.online-metrix.net;Sem essas regras de CSP, o 3DS e o antifraude falharão silenciosamente em produção. O SDK não emite erros de CSP — o navegador bloqueia os scripts antes que o SDK tenha controle.
Diretivas por funcionalidade
Se você usa apenas tokenização (sem 3DS e sem antifraude), basta permitir a API:
Content-Security-Policy:
connect-src 'self' https://api.payhubrasil.com.br;Content-Security-Policy:
script-src 'self' https://mpi.braspag.com.br;
connect-src 'self' https://api.payhubrasil.com.br https://api.ipify.org;
frame-src https://mpi.braspag.com.br;
Conformidade PCI DSS
O SDK de Segurança existe para reduzir o escopo PCI do seu negócio. Com ele, dados sensíveis do cartão nunca passam pelo seu servidor.
Como funciona
- Os dados do cartão (PAN, CVV, validade) são coletados no navegador e enviados diretamente para a API da SoarLabz via HTTPS
- O CVV é usado apenas para validação e nunca é armazenado
- Seu servidor recebe apenas o token opaco — nunca os dados reais do cartão
- Os dados criptografados são armazenados com AES-256-GCM nos servidores da SoarLabz
Escopo PCI para o merchant
| Abordagem | Escopo PCI | Descrição |
|---|---|---|
| Sem SDK (dados no seu servidor) | SAQ D | Escopo completo — 300+ controles |
| Com SDK (tokenização no frontend) | SAQ A-EP | Escopo reduzido — dados transitam pelo frontend mas não pelo backend |
| Hosted fields / iframe (futuro) | SAQ A | Escopo mínimo — dados nunca tocam seu domínio |
Com o SDK, seu negócio se enquadra no SAQ A-EP (Self-Assessment Questionnaire A-EP). Isso significa que os dados do cartão passam pelo seu frontend (DOM do navegador), mas são enviados diretamente para a SoarLabz sem tocar no seu servidor.
Boas práticas PCI com o SDK
Nunca armazene dados do cartão
O token substitui completamente os dados sensíveis. Nunca armazene PAN, CVV, nome do portador ou validade no seu frontend ou backend.
Use HTTPS em todas as páginas
Todas as páginas que carregam o SDK devem ser servidas via HTTPS. Nunca use o SDK em páginas HTTP.
Não logue dados sensíveis
Mesmo com debug: true, o SDK não loga dados do cartão. Garanta que seu código também não logue esses dados.
Valide o token no backend
Ao receber o token no seu backend, use-o diretamente na criação da cobrança. Não tente decodificar ou inspecionar o token.
Use a chave pública apenas no frontend
A chave pública (pk_...) é segura para expor no frontend. A chave secreta (sk_...) deve existir apenas no backend.
Compatibilidade de navegadores
O SDK usa APIs modernas do navegador. Versões mínimas suportadas:
| Navegador | Versão mínima | API limitante |
|---|---|---|
| Chrome | 66+ | AbortController |
| Firefox | 57+ | AbortController |
| Safari | 12.1+ | AbortController |
| Edge | 79+ (Chromium) | — |
| Opera | 53+ | AbortController |
| Samsung Internet | 9.0+ | AbortController |
APIs utilizadas
| API | Uso | Fallback |
|---|---|---|
fetch | Requisições HTTP | Nenhum (obrigatório) |
AbortController | Timeout de requisições | Nenhum (obrigatório) |
btoa | Codificação Base64 para autenticação | Nenhum (obrigatório) |
crypto.randomUUID | Geração de IDs (server-side) | — |
navigator.language | Detecção de idioma para 3DS | Valor padrão |
screen.width/height | Dados do dispositivo para 3DS | Valor 0 |
O SDK não suporta Internet Explorer. Se precisar suportar navegadores legados, utilize a API REST diretamente no seu backend ao invés do SDK client-side.
Ambientes não-browser
O SDK foi projetado exclusivamente para execução em navegadores. Ele não funciona em:
- Node.js / Bun / Deno (server-side)
- React Native
- Web Workers
Para operações server-side, use a API REST da SoarLabz diretamente.
Checklist de produção
Antes de ir para produção, verifique:
Use a chave pública de produção
Gere uma chave de produção no dashboard em Configuração > Chaves de API.
Configure CSP headers
Adicione os domínios da SoarLabz, Braspag e ThreatMetrix às suas regras de Content Security Policy.
Desative o modo debug
Remova debug: true ou deixe o padrão (false).
Sirva via HTTPS
O SDK requer HTTPS. Requisições HTTP serão bloqueadas por mixed-content policies.
Teste o fluxo completo
Execute preparePayment() ou os controladores individuais com cartões de teste antes de ir para produção.
Implemente tratamento de erros
Capture e trate todos os tipos de erro do SDK. Nunca deixe exceções não tratadas chegarem ao usuário final.