SDK
Nesta seção, você encontrará como implementar o SDK da Unico na sua aplicação web para uso do produto Unico IDPay
Para o cenário de uso em Web, o uso do SDK da Unico é o recomendado, pelos seguintes motivos:
Maior segurança;
Experiência integrada ao seu fluxo;
Taxa maior de conversão quando usado o SDK;
Facilidade na implementação.
O uso de integrações que não estejam em conformidade com os padrões estabelecidos nesta documentação pode resultar em interrupções inesperadas no funcionamento do sistema, as quais não serão cobertas ou suportadas pelo IDPay.
Ex: Implementar o iFrame do by Unico dentro de uma webview, implementar o iFrame através de uma tag de HTML, etc.
Como começar
Para utilizar o IDPay por meio do SDK do Unico IDPay, o primeiro passo é cadastrar os domínios que serão utilizados como host para exibir a experiência da jornada do usuário.
Sinalize o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração.
Para iniciar o uso do SDK, devemos iniciar com a instalação da SDK web da Unico:
Métodos disponíveis
init(options)
Esse método permite que o SDK seja inicializado, independentemente de um ID de transação, fazendo com que a experiência do usuário final seja mais fluida. Uma vez que quando o ID da transação e o token estiverem disponíveis, a aplicação já tenha sido pré-carregada através desse método. Se esse método não for chamado diretamente pela aplicação, o usuário final terá um carregamento longo na primeira abertura do SDK.
Parâmetros:
options
Recebe um objeto com propriedades de configuração:
type
O tipo de fluxo que será inicializado. Hoje, disponibilizamos dois tipos de fluxos (REDIRECT e IFRAME). Para novas aplicações, recomendamos o uso do tipo IFRAME, tornando a experiência para o usuário final muito mais fluida e com menos fricção, já que não será necessário sair da tela de checkout, e o carregamento da experiência poderá ser realizado previamente.
open({ transactionId, token, onFinish? })
Esse método realiza a abertura da experiência do IDPay de acordo com o fluxo escolhido previamente, na função de inicialização. Para o fluxo do tipo REDIRECT, essa função faz um simples redirecionamento para a rota do fluxo de captura do IDPay. Para o fluxo do tipo IFRAME, essa função exibe o iframe já pré-carregado, e inicia o fluxo de mensageria entre a página do cliente e a experiência do IDPay.
Parâmetros:
options
Recebe um objeto com propriedades de configuração:
transactionId
Recebe o ID da transação criada. Esse ID é importante para conseguirmos obter os detalhes da transação e realizarmos todo o fluxo da maneira correta (pode ser obtido na criação da transação via API).
token
Recebe o token da transação criada. Esse token é importante para conseguirmos autenticar a transação e garantir que somente domínios autorizados utilizem-na (pode ser obtido na criação da transação via API).
opcional onFinish(transaction, type)
Recebe uma função de callback que será executada no término do fluxo de captura do IDPay, passando dois argumentos:
O objeto da transação com os seguintes dados: { captureConcluded, concluded, id }
O tipo da resposta que pode ser FINISH, para casos onde o fluxo foi finalizado com sucesso, ou ERROR, para casos onde o fluxo foi interrompido por um erro¹.
[1] em casos de erro no fluxo, a transação não terá seu status alterado e um callback via webhook, caso configurado, não será realizado.
Segurança
Após uma análise cuidadosa das necessidades e desafios que enfrentamos, decidimos adotar uma solução baseada em iFrames com tokens de autenticação ao invés de implementar uma política de Content Security Policy (CSP). Essa escolha foi motivada por diversas considerações relacionadas à segurança e à flexibilidade necessárias para atender às demandas dos nossos clientes.
Contexto e Desafios com CSP
O Content Security Policy (CSP) é uma ferramenta poderosa para proteger aplicações web contra diversos tipos de ataques, como Cross-Site Scripting (XSS) e injeção de código. No entanto, ao configurar uma política CSP, é necessário definir uma lista rígida de domínios confiáveis. Essa abordagem é eficaz quando os domínios são fixos e previsíveis. No entanto, para nossos clientes, que frequentemente utilizam domínios dinâmicos e variáveis, essa configuração rígida apresenta desafios significativos.
Vulnerabilidade com Domínios Dinâmicos
Os domínios dinâmicos representam um risco substancial para a segurança ao usar CSP. Quando um cliente possui domínios que mudam com frequência ou são criados dinamicamente, seria necessário atualizar constantemente a política CSP para incluir esses novos domínios. Isso não só aumenta o esforço de manutenção, mas também expõe os domínios aos quais a política CSP se aplica. Cada domínio adicionado à política CSP é potencialmente um ponto de vulnerabilidade se não for adequadamente gerenciado.
Solução com IFrame e Auth Token
Para mitigar esses riscos e atender à flexibilidade exigida pelos nossos clientes, optamos por utilizar iframes combinados com tokens de autenticação. Esta solução oferece uma camada adicional de segurança e evita a necessidade de expor ou gerenciar uma lista extensa e dinâmica de domínios.
Como funciona
Autenticação Segura: Cada iframe é carregado com um token de autenticação exclusivo para cada transação, garantindo que apenas usuários autorizados possam acessar o conteúdo. Esse token é verificado em tempo real, proporcionando uma camada adicional de segurança e controle.
Isolamento de Conteúdo: O uso de iframes permite isolar o conteúdo em um contexto separado, reduzindo o risco de interferência entre diferentes origens e mitigando potenciais ataques.
Flexibilidade para Domínios Dinâmicos: Ao não depender de uma política CSP estática, nossa solução se adapta facilmente aos domínios dinâmicos dos clientes, sem a necessidade de atualização constante das políticas de segurança.
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
Last updated