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.

Orientações gerais

Para otimizar a performance da sua operação, melhorar a taxa de conversão e proporcionar uma experiência mais fluida para o usuário final, é obrigatório que a SDK da Unico seja sempre implementada em modo full screen(tela cheia) na sua aplicação. Confira como deve ser a implementação no exemplo abaixo:

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.

Para iniciar o uso do SDK, devemos iniciar com a instalação da SDK web da Unico:

$ npm install idpay-b2b-sdk

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

import { IDPaySDK } from “idpay-b2b-sdk”;

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // Só irá ser preenchido se for ambiente de testes.
});

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.
*Adaptado com variáveis retornadas pela API da PAYTIME.

const transactionId = antifraud_id // Deve receber o valor de antifraud_id retornado na criação da transação;
const token = session;//Deve ser preenchido com o valor de session retornado na criação da transação

const transaction = {
  id: antifraud_id,// Deve receber o valor de antifraud_id retornado na criação da transação;
  concluded: true,
  captureConcluded: true
};

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

// Você também pode encerrar o SDK explicitamente através do método abaixo
IDPaySDK.close();

Como rodar em ambiente de teste

• Frontend deve rodar em http://localhost ;
• Backend conectado em Sandbox Paytime, com as chaves desse ambiente;

Tempo de validação

A validação deve ser realizada em até 1 hora.

Layout exemplo

Requisitos

Realize os teste de validação em mais de um navegador.

• Chrome
• Firefox
• Safari

De forma geral, o SDK da suporte a WebRTC e versões mais recentes dos browsers listados acima. Por questões de compatibilidade e segurança, o funcionamento em versões muito antigas destes browsers não é garantido.

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​PreviousWeb

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

As instruções completas para implementação do SDK Web estão disponíveis em: https://devcenter.unico.io/unico-idpay/integracao/controlando-a-experiencia/web/sdk