Pular para o conteúdo principal

SDK

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

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 pela Verificação de Cartão Não Presente.

Ex: Implementar o iFrame do by Unico dentro de uma webview, implementar o iFrame através de uma tag de HTML, etc.

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.

Como começar​

Para utilizar a Verificação de Cartão Não Presente por meio do SDK da Verificação de Cartão Não Presente, o primeiro passo é cadastrar os domínios que serão utilizados como host para exibir a experiência da jornada do usuário.

perigo

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:

npm install idpay-b2b-sdk
dica

Quando instalar o pacote do SDK da Unico, implemente sem especificar a versão que está utilizando e de modo que seu gerenciador de dependências atualize sempre os minors e patches para a versão mais recente.

Para verificar versões anteriores, acesse npmjs.com/package/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á terá 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 o tipo 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 da Verificação de Cartão Não Presente 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 da Verificação de Cartão Não Presente. 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 da Verificação de Cartão Não Presente.

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).
    • onFinish(transaction, type) (opcional) — recebe uma função de callback que será executada no término do fluxo de captura da Verificação de Cartão Não Presente, passando dois argumentos: o objeto da transação ({ captureConcluded, concluded, id }), e o tipo da resposta — FINISH para casos onde o fluxo foi finalizado com sucesso, ou ERROR para casos onde o fluxo foi interrompido por um erro. 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.
const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const transaction = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  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();

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.
Última atualização em