O Unico IDPay é uma solução inovadora da Unico que combina, em uma única verificação, a identificação do shopper e a validação da titularidade do cartão de crédito. Essa abordagem assegura transações mais seguras em compras não-presenciais e ajuda a recuperar vendas que poderiam ser perdidas devido a inconsistências em pagamentos.

Com o IDPay, você garante que:

• O usuário está ao vivo no momento que realiza a transação;

• A identidade é do titular do cartão de crédito;

• O cartão de crédito pertence a pessoa que está realizando a transação no seu estabelecimento;

  • Com a possibilidade de habilitar o uso autorizado e validado de cartões de terceiros.

O funcionamento é simples e eficiente: uma transação é criada a partir do número do cartão de crédito e do CPF do titular, e o IDPay se encarrega de realizar a autenticação dessa transação, seja através da biometria facial ou de uma autenticação com os metadados do device.

Além disso, o IDPay é altamente flexível, podendo ser ajustado para atender a diferentes cenários e necessidades. Sua plataforma oferece uma ampla gama de funcionalidades que suportam os mais variados casos de uso, tornando-o ideal para operações que exigem precisão e segurança.

Para o maior entendimento sobre o IDPay, siga a sequência sugerida no menu abaixo e explore todas as possibilidades que o produto oferece:

Introdução

O Unico IDPay oferece uma ampla variedade de endpoints, módulos e funcionalidades, projetados para se adaptar a diferentes cenários e casos de uso. Abaixo, apresentamos as principais definições e aplicações de cada funcionalidade.

Transações de pagamento

A primeira grande funcionalidade do IDPay é validar cada transação feita dentro do estabelecimento, a fim de garantir que a venda pode ser realizada para aquele usuário.

As transações são organizadas em diferentes módulos, cada um projetado para atender a cenários específicos e necessidades variadas. Explore os módulos disponíveis e veja como cada um pode ser aplicado ao seu caso de uso:

Onboarding de Cartão de Crédito

Com esta funcionalidade, você pode realizar o onboarding do cartão de crédito dos seus usuários em sua carteira digital, garantindo que o cartão pertence ao titular correto.

O que diferencia esta funcionalidade das Transações de Pagamento são os endpoints e os parâmetros específicos da REST API, que foram desenvolvidos para atender de forma otimizada às necessidades de validação e registro de cartões na sua solução.

É possível realizar o Onboarding do Cartão de Crédito dos seus usuários de duas maneiras distintas:

• Pode-se realizar o processo solicitando a captura biométrica dos seus usuários;

• Pode-se reutilizar a biometria coletada em processos de Verificação de Identidade realizados por outros produtos da plataforma Unico IDCloud.

Continue a leitura com o link sugerido abaixo:

Introdução​

Como destacado nas seções anteriores, o Unico IDPay oferece a garantia de liability, assegurando a máxima acurácia nas validações realizadas. O Chargeback da Unico protege você contra possíveis prejuízos em transações onde a identidade do titular do cartão de crédito foi validada incorretamente pelo IDPay.

Caso uma transação validada pelo IDPay resulte em um processo de chargeback oficial, devidamente formalizado junto ao adquirente ou à bandeira, o cliente do IDPay poderá ser ressarcido pela Unico no valor equivalente à transação. Essa garantia é aplicável mediante comprovação, após as devidas apurações, de que houve um erro na validação realizada pelo IDPay e que a Unico foi responsável pela decisão incorreta.

Essa segurança adicional demonstra o compromisso do Unico IDPay em oferecer confiabilidade e proteção nas operações realizadas com sua solução.

Quando usar essa opção?​

Quando você tiver recebido uma solicitação de chargeback por fraude e acredita que houve erro por parte do IDPay ao validar a identidade do titular do cartão de crédito.

O que é chargeback?​

Chargeback é o processo de apuração de uma contestação de uma compra/transação realizada com cartões de crédito/débito em plataformas online, e que poderá resultar no estorno/cancelamento desta compra/transação. O chargeback pode ser classificado em dois grandes grupos:

• Chargeback por Desacordo Comercial: Quando a transação precisa ser cancelada por algum problema na relação consumidor x estabelecimento. Exemplos: Mercadoria não entregue, mercadoria com defeito, desistência da compra, compra em duplicidade, serviço não prestado, etc.

• Chargeback por Fraude: Quando o titular do cartão alega não ter realizado uma compra em seu nome, se inicia então o processo de disputa entre as partes (quem fica com o prejuízo).

A análise de chargeback somente poderá ser solicitada em casos de chargeback por fraude.

Pré-requisitos para solicitar análise de chargeback​

A análise de chargeback somente poderá ser solicitada para transações que seguem todas as regras abaixo:

• A transação deve ter sido aprovada (status approved);

• A transação deve ter sido criada há menos de 180 dias;

• A transação não ter sido submetida a outra análise de chargeback;

Para utilizar interações server-to-server, é preciso solicitar a criação da conta de serviço com o gerente de projetos responsável pela sua empresa enviando os seguintes dados: nome da empresa, nome da aplicação, nome, e-mail e celular do responsável pela aplicação na empresa. É preciso criar contas diferentes para os ambientes de Homologação e Produção.

Após o recebimento desses dados, será criada uma conta de serviço responsável por autenticar a sua aplicação e enviaremos um e-mail para que seja gerado o par de chaves para a conta.

Uma credencial de conta de serviço inclui um nome único de conta, um identificador da empresa (Tenant ID) e ao menos um par de chaves (pública e privada). Ao final da geração das chaves, você recebe apenas a chave privada (arquivo .key.pem), bem como o payload que deve ser utilizado para montar o JWT. Este payload terá o seguinte formato:

Caso precise da chave pública para configurar em seu sistema, contate o gerente de projetos responsável por sua conta. Também é possível gerar uma chave pública através do comando openssl a seguir:

Os erros retornados na requisição podem ser identificados através dos códigos abaixo e possuem a seguinte estrutura:

{
  "error": "server_error",
  "error_description": "Falha na autenticação x.x.x"
}

Visão geral da integração

Para utilizar o IDPay é necessário se autenticar via token de acesso, utilizando o sistema de autenticação conhecido como OAuth2.

O sistema de autenticação OAuth2 da unico suporta a interação server-to-server entre uma aplicação web e os serviços da unico.

Para este cenário, você precisará de uma conta de serviço, que é uma conta impessoal que pertence à sua aplicação e não a um usuário individual. Sua aplicação chama as APIs da unico em nome da conta de serviço, portanto usuários não estão diretamente envolvidos. Este cenário é chamado “two-legged OAuth”, ou “2LO”. Tipicamente, uma aplicação utiliza uma conta de serviço quando a aplicação chama as APIs da unico para trabalhar com seus próprios dados ao invés dos dados do usuário.

Faça download do arquivo abaixo, importe no Postman e substitua o valor dos parâmetros "service_account", "tenant_id" e "secret_key" para testar a chamada.

Personalização da logotipo

É possível personalizar a logo que é apresentada para o usuário final, conforma imagem abaixo:

Para solicitar a inclusão desta logo, é necessário enviar ao time Unico uma imagem no formato .PNG no tamanho de 56x56px.

Para utilizar o produto Unico IDPay existem alguns pré-requisitos, sendo eles:

• iOS: A partir da versão 11.0 (caso aberto em webview iOS 13);

• Android: A partir da versão 5.1 (caso aberto em webview Android 8);

O campo link é usado para direcionar o usuário. Esse campo é recebido na resposta de sucesso da criação da transação.

Aqui você encontrará a melhor forma de gerenciar a experiência do usuário em sua aplicação Android:

Passo 1: Usando CustomTabs para integração

1 - Insira no app/build.gradle a dependência necessária para o uso de CustomTabs:

Resultado da Transação​

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Os artigos GetProcess desta documentação descrevem uma maneira de obter o status de um processo através de uma chamada a um endpoint. Dessa forma, é realizado um polling para receber informações sobre os processos criados. Isso significa que o endpoint pode ser chamado diversas vezes para um mesmo processo para se obter o status mais recente.

Com o uso de webhooks é possível notificar um endpoint específico toda vez que o status de um processo for alterado.

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token .

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:

Métodos disponíveis

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.

Após a criação e configuração de uma conta de serviço, sua aplicação precisa completar as seguintes etapas:

1. Criar um JSON Web Token (JWT), que inclui cabeçalho, payload e assinatura;

2. Requisitar um token de acesso (AccessToken) da plataforma de autenticação OAuth2;

3. Tratar a resposta JSON que a plataforma de autenticação retornará.

Se na resposta estiver incluso um token de acesso, você poderá usá-lo para fazer requisições às APIs dos produtos da unico para os quais a conta de serviço possui permissão de acesso. (Se na resposta não estiver incluso um token de acesso, seu JWT e requisição de obtenção do token podem estar incorretos ou a conta de serviço pode não ter as permissões necessárias para acessar os recursos solicitados.)

O token de acesso gerado na requisição mencionada acima tem validade padrão de 3600 segundos, podendo variar de acordo com a configuração de segurança estabelecida para sua empresa. Quando o token de acesso expirar, sua aplicação deverá gerar um novo JWT, fazer a assinatura e requisitar um novo token de acesso na plataforma de autenticação.

1 - Criando o JWT

Um JWT é composto por três partes: um cabeçalho, um payload e uma assinatura. O cabeçalho e o payload são objetos JSON. Esses objetos JSON são serializados em UTF-8 e então codificados usando codificação Base64url¹. Esta codificação provê resliência contra alterações de codificação em casos de repetidas operações de codificação. O cabeçalho, o payload e a assinatura são concatenadas com um caractere de ponto final ..

Um JWT é composto da seguinte forma:

O texto base para a assinatura é composto pela seguinte forma:

1.1 - Formando o cabeçalho JWT

O cabeçalho consiste em dois campos que indicam o algorítimo de assinatura e o formato do token. Ambos os campos são obrigatórios e cada campo possui apenas um valor. Contas de serviço dependem do algorítimo RSA SHA-256 e do formato de token JWT. Como resultado, a representação JSON do cabeçalho se dá da seguinte forma:

A representação em Base64url se dá da seguinte forma:

1.2 - Formando o payload JWT

O payload JWT contém informações sobre o JWT, incluindo as permissões sendo requisitadas (scopes), a conta solicitando acesso, o emissor, o momento em que o token foi emitido e o tempo de vida do token. A maioria dos campos são obrigatórios. Assim como o cabeçalho JWT, o payload é um objeto JSON e é usado na composição da assinatura.

1.3 - Campos Obrigatórios

Os campos obrigatórios no JWT são mostrados na tabela abaixo. Eles podem aparecer em qualquer ordem dentro do payload.

Entenda como funciona a conversão para os campos de emissão (iat) e expiração (exp) do jwt, e veja também exemplos de utilização dos valores dos campos aqui. Além disso, o campo “iat” deve ser o horário atual no formato exigido e o “exp” deve respeitar a conta abaixo:

A representação dos campos JSON obrigatórios no payload do JWT se dá da seguinte forma:

1.4 - Calculando a assinatura

A especificação JSON Web Signature (JWS)² é a mecânica que guia o cálculo da assinatura para um JWT. O conteúdo de entrada para o cálculo da assinatura é o byte array do seguinte conteúdo:

O mesmo algoritmo sinalizado no cabeçalho do JWT precisa ser utilizado para o cálculo da assinatura. O único algorítimo de assinatura suportado pela plataforma de autenticação OAuth2 é o RSA usando SHA-256. Ele é expressado como RS256 no campo alg do cabeçaho do JWT.

Assine a representação UTF-8 do conteúdo de entrada utilizando SHA256withRSA (também conhecido como RSASSA-PKCS1-V1_5-SIGN com o hash SHA-256) com a chave privada que foi criada e associada à conta de serviço (arquivo .key.pem gerado pela solicitação recebida por e-mail). O conteúdo de saída será um byte array.

A assinatura precisará ser então codificada em Base64url. O cabeçalho, o payload e a assinatura deverão ser concatenadas com o caractere de ponto final .. O resultado é o JWT. Ele deve ser da seguinte forma:

A seguir está um exemplo de token JWT antes da codificação em Base64url:

Abaixo está um exemplo do JWT que foi assinado e está pronto para transmissão:

Também é possível utilizar bibliotecas previamente estabelecidas para realizar a criação do JWT. Como referência, é possível encontrar uma lista de bibliotecas no site .

2 - Fazendo a requisição de um token de acesso

Após a geração do JWT assinado, uma aplicação pode utilizá-lo para requisitar um token de acesso (Access Token). A requisição do token de acesso é uma requisição POST HTTPS e o corpo deve ser URL encoded. A URL é a mostrada abaixo:

Os parâmetros abaixo são obrigatórios na requisição POST HTTPS:

3 - Tratando a resposta da plataforma de autenticação

Se o JWT e a requisição do token de acesso foram formados apropriadamente e a conta de serviço tem as permissões necessárias, então a resposta da plataforma de autenticação retorna um objeto JSON contendo um token de acesso. Segue um exemplo de resposta da plataforma:

O token de acesso retornado no campo “acess_token” do objeto JSON também é um token JWT que deverá ser utilizado nas APIs dos Produtos da unico. Caso retorne um erro na requisição, é possível consultar o tipo do erro na tabela de erros clicando .

4 - Duração do token de acesso

A duração do token de acesso é variável. Sua duração é especificada no campo “expires_in”, retornado juntamente com o token de acesso. Deve-se utilizar o mesmo token de acesso durante a sua validade para todas as chamdas às APIs dos produtos.

Não solicite um novo token de acesso até que a validade do token atual esteja chegando ao fim. Sugerimos uma margem de 600 segundos (10 minutos). Para isso execute o cálculo:

Sendo que token.exp é o timestamp da expiração do token.

Exemplos:

Um novo token de acesso pode ser solicitado quando faltar 10 minutos pra expirar.

• ¹ De acordo com o RFC 4648 de codificação BaseN, o formato Base64url é similar ao formato Base64, com exceção do caracter = que deve ser omitido, e dos caracteres + e / que devem ser substituídospor - e _, respectivamente.

• ² JSON Web Signature: .

Introdução

O Unico IDPay utiliza códigos de resposta HTTP convencionais para indicar o sucesso ou falha de uma solicitação de API.

Como regra geral:

• Códigos no intervalo 2xx indicam sucesso na requisição;

• Códigos no intervalo 4xx indicam parâmetros incorretos ou incompletos (por exemplo, um parâmetro obrigatório foi omitido ou uma operação falhou com terceiros, etc.);

• Códigos no intervalo 5xx indicam que houve um erro nos servidores do produto Unico IDPay.

O Unico IDPay também gera uma mensagem de erro e um código de erro formatado em JSON:

Erros possíveis

Neste tópico, você encontrará os possíveis erros dos endpoints, separados por seu HTTP response.

Criação da transação

Consulta do status da transação

Recuperação do conjunto probatório da transação

Reenvio da notificação da transação

Onboarding de cartão de crédito

Visão Geral

Bem-vindo à documentação das APIs REST do produto Unico IDPay! Nesta página, você encontrará tudo o que precisa saber para melhorar a segurança e a qualidade dos seus aplicativos usando nossa REST API.

Leia mais

Dúvidas frequentes sobre o Unico IDPay:

• Clique para acessar a FAQ do IDPay;

Como comunicar a validação de identidade via IDPay para o consumidor?

Sabemos que uma validação biométrica feita por um fornecedor pode gerar dúvidas e fricção no seu usuário final, portanto é importante trazer a transparência deste processo e dar o suporte adequado para você tenha bons números na sua operação. Abaixo você encontrará uma série de dicas que pode auxiliá-lo nesta comunicação:

• Comunicar que uma empresa parceira (preferencialmente citar a Unico) poderá entrar em contato através de SMS, E-mail ou Whatsapp solicitando uma foto do rosto para validação de biometria facial;

• Informar que, em alguns casos, ela deverá confirmar o número de CPF, que é utilizado para identificação da identidade digital do titular do cartão de crédito;

• Explicar que a validação de identidade é específica do titular do cartão de crédito, para garantir o consentimento do uso do cartão;

• Alertar ao consumidor, que ele não deve passar nenhum dado ou foto, via e-mail, sms ou WhatsApp. Todo o fluxo de validação é feito dentro do link enviado;

• Avisar/Treinar time de atendimento ao consumidor, em caso de questionamento do consumidor;

• Disponibilizar dentro da FAQ da empresa um tópico informando os detalhes dessa validação;

• Disponibilizar link da nossa central de ajuda: .

Casos de uso

O IDPay pode ser utilizado em diversos casos de uso e nas mais variadas formas de utilização. Confira abaixo os possíveis casos de uso e suas correlações.

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Validação do cartão de crédito