Visão geral da integração

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.

const fs = require('fs')
const path = require('path')
const jwt = require('jsonwebtoken')
const request = require('request')

// settings
const basePath = 'https://identityhomolog.acesso.io'

// entry point
let options = {
    serviceAccount: 'svcapp1',
    tenant: "9ea3c3bd-4447-4c3b-ae2e-504b795d3733"
}

requestAnAccessToken(createServiceAccountToken(options), (err, accessToken) => {
    let payload = jwt.decode(accessToken.access_token)
    console.log('Response:')
    console.log(' Access Token: ', accessToken.access_token)
    console.log(' ID: ', payload.jti)
    console.log(' Issuer: ', payload.iss)
    console.log(' Subject: ', payload.sub)
    console.log(' expires_in: ', accessToken.expires_in)
    console.log(' Expiration Date: ', new Date(payload.exp))
    console.log(' Creation Date: ', new Date(payload.iat))
})

// functions
function createServiceAccountToken({tenant, serviceAccount, account = ''}) {
    // Reads the service account private key
    let privateKey = fs.readFileSync(path.resolve(`${serviceAccount}.key.pem`))

    // Prepare the request
    let payload = {
        iss: `${serviceAccount}@${tenant}.iam.acesso.io`,
        aud: basePath,
        scope: '*',
        exp: Math.floor(Date.now() / 1000) + 3600,
        iat: Math.floor(Date.now() / 1000)
    }
    // Service account is requesting an access token for another user?
    if (account) {
        payload.sub = account
    }

    // Create JWS
    return jwt.sign(payload, privateKey, { algorithm: 'RS256' })
}

function requestAnAccessToken(serviceToken, callback) {
    // Prepare the request
    let options = {
        method: 'POST',
        url: `${basePath}/oauth2/token`,
        headers: {'content-type': 'application/x-www-form-urlencoded'},
        form: {
            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer' ,
            assertion: serviceToken
        }
    }
    console.log('Requesting Access Token with self created token:' )
    console.log('', serviceToken)

    // Ask identity and authorization server for an access token
    request(options, (error, response, body) => {
        if (error) {
            callback(new Error(error))
        }

        body = JSON.parse(body)

        if (body.error) {
            callback(new Error(`${body.error}: ${body.error_description}`))
        }

        callback(null, body)
    })
}

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.

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"
}

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.

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.

Checkout

Pré mesa de análise

Ferramenta da mesa de análise

Recuperação de vendas

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.

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 90 dias;

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

• A transação deve ser do tipo "crédito".

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.

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.

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.

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

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

Consulta do status da validação

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.

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

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.

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:

openssl req -x509 -new -nodes -sha256 -days 720 \
-key fileName.key.pem -out fileName.cert.pem

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.

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:

Módulos

Com subconjunto das validações na criação da transação (Pré)

Este módulo realiza algumas pré-validações com os dados informados. O status retornado será: waiting ou fast-inconclusive. O link para captura biométrica só será disponibilizado caso consigamos validar o CPF/número do cartão de crédito do usuário.

Esta opção pode ser utilizada em diversos cenários, entre eles:

• Quando a identificação informada (CPF, por exemplo) for do titular do cartão. Esse fluxo não permite que o usuário informe um novo CPF durante a validação e portanto caso a identificação informada não seja consistente com o titular do cartão implicará em queda na taxa de aprovação;

• Quando se deseja minimizar a fricção (abertura da experiência de captura do IDPay) porém sem perder aprovação, maximizando a taxa de aprovação das transações retornadas como waiting;

• Quando o IDPay estiver no topo do seu funil antifraude;

• Em uma solução 100% integrada com captura via Webview ou iFrame;

• Entre outros.

Este módulo realiza todas pré-validações com os dados informados. O status retornado será: waiting ou fast-inconclusive. O link para captura biométrica só será disponibilizado caso consigamos validar o CPF/número do cartão de crédito do usuário.

Esta opção pode ser utilizada em diversos cenários, entre eles:

• Quando a identificação informada (CPF por exemplo) for do titular do cartão. Esse fluxo não permite que o usuário informe um novo CPF durante a validação e portanto caso a identificação informada não seja consistente com o titular do cartão implicará em queda na taxa de aprovação;

• Quando se deseja minimizar a fricção (abertura da experiência de captura do IDPay) com uma pequena perda de aprovação, maximizando a taxa de aprovação das transações retornadas como waiting

• Quando o IDPay estiver no topo do seu funil antifraude;

• Em uma solução 100% integrada com captura via Webview ou iFrame;

• Entre outros.

Este módulo não realiza nenhuma pré-validação na criação de uma transação. O status retornado sempre será waiting (aguardando) e o link sempre será disponibilizado para que o usuário faça a captura da biometria.

Esta opção pode ser utilizada em diversos cenários, entre eles:

• Quando a identificação informada (CPF por exemplo) não é necessariamente do titular do cartão (esse fluxo permite que o usuário informe um novo CPF durante a experiência de captura);

• Quando você deseja utilizar a experiência de captura do IDPay em todas transações;

• Preferencialmente para recuperação de venda;

• Entre outros.

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.

Continue a leitura com o link sugerido abaixo:

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:

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.

Resultado da Transação

Resultado do Chargeback

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.

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.

Criação da transação

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

Reaproveitamento de Transações

É possível configurar a empresa para reaproveitar transações que possuam os mesmos dados, evitando erros de replicated transaction. O reaproveitamento acontecerá nas seguintes condições:

• Uma transação está sendo criada com o mesmo orderNumber, identity.key, identity.value, company, card.binDigits, card.lastDigits e value de uma transação já anteriormente criada;

• A transação anterior ainda não ultrapassou o tempo de expiração configurado na empresa.

Se a transação a ser criada e a transação anterior NÃO respeitem estas condições, uma nova transação será criada. Caso contrário, estas serão as respostas possíveis:

Caso a transação anterior esteja em um status final, como approved ou inconclusive:

{
    // informações da transação anterior
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

Caso a transação anterior ainda esteja em um status inicial, como waiting ou shared:

{
    // informações da transação anterior
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "eyJhbGciOiJIUzI1NiIsIn[...]dQssw5c"
}

Neste último caso, a transação ainda em um status inicial terá sua data de expiração recalculada, tendo como base a data desta requisição.

Consulta de status da transação

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

Reenvio da notificação da transação

Cancelamento da transação

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.

Para o cenário de uso em iOS, o uso da ASWebAuthenticationSession é uma das maneiras recomendadas.

Após criar a transação e obter o link da transação, a seguinte implementação é recomendada:

• Em seu fluxo comum (que está inserido o IDPay), você irá abrir a ASWebAuthenticationSession com o link gerado via API;

• Você poderá customizar essa abertura da maneira que for o ideal para seu aplicativo;

• Irá monitorar se houve alteração de URL (para a redirectUrl) e então feche a página;

Para fazer o fluxo funcionar é necessário seguir os seguintes passos:

Passo 1: Criar o controlador de autenticação de pagamento

O primeiro passo que você deve realizar é criar o controlador de autenticação de pagamentos, para isso crie uma classe chamada IDPayAuthenticationController (ou como preferir chamar).

Na sequência, importe o framework AuthenticationServices no topo da classe.

Declare a classe como NSObject e implemente o protocolo ASWebAuthenticationPresentationContextProviding.

O resultado deve ser:

import AuthenticationServices

class IDPayAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Passo 2: Implementar a autenticação​

Abra o arquivo onde você irá realizar a autenticação e adicione as importações necessárias (em nosso exemplo estamos fazendo no ContentView.swift).

import SwiftUI
import AuthenticationServices

Para controlar o estado da autenticação criaremos uma propriedade @State.

@State private var isAuthenticated = false

Crie uma instância da classe IDPayAuthenticationController fora do corpo da estrutura ContentView.

let idPayController = IDPayAuthenticationController()

Para realizar a validação do pagamento crie uma função chamada authenticatePayment.

func authenticatePayment() {
    guard let url = URL(string: "URL_AUTHENTICATION") else { return }

    var session: ASWebAuthenticationSession?
    session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
        guard callbackURL != nil else {
            if let error = error {
                return print("Erro durante a autenticação: \(error.localizedDescription)")
            }
            return
        }

        // Processa o URL de callback para verificar se a autenticação foi bem-sucedida
        session?.cancel()
        isAuthenticated = true
    }

    session?.presentationContextProvider = idPayController
    session?.prefersEphemeralWebBrowserSession = true
    session?.start()
}

Exemplo de como deverá ficar no app:​

Para saber mais sobre, recomendamos uma leitura nos seguintes artigos e documentações:

• Para acessar a documentação oficial, clique aqui.

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.

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:

{
    "error": {
        "code": "40004",
        "description": "transaction id is invalid"
    }
}

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

Cancelamento da transação

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.

Introdução

O Unico IDPay oferece uma integração simples e rápida. Atualmente trabalhamos utilizando como padrão de integração em aplicativos (mobiles ou web) através do uso de Webview, SDK e Redirect. Esse padrão potencializa a segurança do seu negócio e dos seus clientes, assim abstraindo a complexidade de manipulação da câmera do dispositivo dos usuários e a captura da selfie.

Em nossa REST API, oferemos os métodos para geração de link de integração que podem ser abertos e controlados pelos aplicativos.

Gerando Dados na API

Antes de avançar para os detalhes de integração no seu aplicativo ou website, é fundamental iniciar pela integração com a nossa API. Nesse processo, dois pontos principais serão utilizados:

1. Criar Transação (CreateTransaction)

   • Certifique-se de preencher o campo redirectUrl, que será essencial para o fluxo da integração.

Após essa etapa inicial, você estará pronto para prosseguir com a integração no aplicativo ou website.

É importante lembrar que, ao finalizar todo o fluxo, será necessário obter o resultado da transação por meio da nossa API para garantir o encerramento correto do processo.

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.

O que é um webhook?

Webhook é um serviço de notificação sistêmica que permite a integração assíncrona entre sistemas, onde um sistema notifica o outro através de um gatilho. Assim, os webhooks podem manter sistemas atualizados com informações mais recentes sem ser necessária a verificação constante por atualizações através de polling.

Como configurar o Webhook

Para configurar o webhook, são necessárias as seguintes informações:

• URL de notificação: É o endpoint usado pelo By Unico para as notificações sobre as atualizações de status.

• Tipo de autenticação: É o método de autenticação usado para invocar o endpoint. As seguintes opções estão disponíveis:

  • Basic Authorization;

  • API Key;

  • Sem autenticação.

• Secret: Indica um segredo usado para a autenticação. O secret só é necessário quando o tipo de autenticação for Basic Authorization e API Key:

  • Para o Basic Authentication é preciso enviar no formato user:pass.

  • Para API Key, é possível enviar em dois formatos:

    • header:value, quando é desejado que o header tenha um nome específico;

    • value: quando o header desejado é o Authorization

• Configurações de retentativas: Indica o número de tentativas para o caso de falha na chamada ao endpoint:

  • Número máximo de tentativas;

  • Intervalo entre tentativas (em segundos);

  • Rate limit: Limite máximo de envios simultâneos (máximo: 500);

  • Timeout: Tempo máximo de espera para a resposta do endpoint (em segundos).

• Status a serem notificados: É possível se inscrever em status específicos para receber as notificações. São eles:

  • approved: Transação aprovada;

  • processing: Transação em processamento;

  • inconclusive: Não conseguimos realizar uma validação conclusiva;

  • shared: Transação compartilhada, aguardando envio;

  • skiped: A pessoa pulou a captura biométrica no fluxo;

  • unknown-share: A pessoa marcou que não reconhece aquela compra;

  • absent-holder: O titular do cartão não está presente para realizar a captura;

  • expired: A pessoa não realizou a captura dentro do tempo estabelecido e a transação foi expirada.

Ao configurar um webhook na plataforma, você pode obter informações sobre os processos através de notificações enviadas para um endpoint da API desenvolvida por você para receber essas atualizações.

As informações enviadas pela plataforma para a API são:

• ID: ID da transação;

• status: Status da transação;

A requisição deve ser um método POST em uma API REST tornando mais fácil e seguro o envio das informações. Todos os campos devem ser obrigatórios. O corpo da requisição deve aceitar o ID da transação e o estado, como mostrado no exemplo a seguir:

Resposta

A resposta deve vir de forma síncrona. O status para requisições bem sucedidas deverá estar no intervalo de 200 a 299. Qualquer outro status será considerado como falha e o IDPay irá realizar novas tentativas de notificações (com exponential backoff entre elas), até receber uma resposta 2xx ou até atingir o número máximo de tentativas.

Atualmente temos um conjunto de status, porém esse conjunto pode variar no futuro. Então é recomendado deixar configurável os status que o cliente tem interesse para tomar alguma ação. Por exemplo, se há o desejo de tomar uma ação toda vez que uma captura é realizada com sucesso, atualmente isso ocorre com o status processing, porém como isso pode ser modificado no futuro, é recomendado que o status que indica que a captura foi realizada com sucesso seja uma configuração no sistema, de modo que uma alteração no futuro para o status de captured seja facilmente realizada.

Além disso, recomendamos ter ações específicas para status específicos, e uma ação geral caso o status não seja reconhecido (por exemplo assumir que tudo que for diferente de processing e approved é inconclusivo). isso é importante, pois novos status podem surgir no futuro e não é esperado que o webhook quebre em função disso.

Atente-se aos seguintes aspectos ao desenvolver API que o IDPay irá utilizar para notificar as mudanças de status:

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:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

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

{Cabeçalho em Base64url}.{Payload em Base64url}

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:

{"alg":"RS256","typ":"JWT"}

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

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:

exp = iat + 3600

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

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
  "iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}

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:

{Cabeçalho em Base64url}.{Payload em Base64url}

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:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

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

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
  "iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}.
[byte array da assinatura]

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

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 jwt.io.

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:

https://identityhomolog.acesso.io/oauth2/token

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

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

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:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

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

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:

token decodificado:
new Date(token.exp - 600)

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

Exemplos:

Cenário padrão:
expires_in: 3600 (1h) - Geração do token as 14h42

Solicitar um novo token somente as 15h32 ou seja, 14:42 + (3600 - 600)

Cenário com a duração alterada:
expires_in: 7200 (2h) - Geração do token as 14h42

Solicitar um novo token somente as 16h32 ou seja, 14:42 + (7200 - 600)

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: https://tools.ietf.org/html/rfc7515.

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.

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);

• Desktop: Sem requisitos de versão ou SO.

O frame de captura disponibilizado por meio do SDK, é compatível com as seguintes combinações de browsers e sistemas operacionais:

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.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .

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.

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

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

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.

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.

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

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 .

Solicitação de análise de chargeback

Consulta status da análise de chargeback

A versão web existe a opção de usar o modelo de redirect, porém o modelo de iFrame é o mais recomendado.

1) Utilizando window.open()

Ao criar a transação foi passado por parâmetro o campo redirectUrl que será utilizado posteriormente, você poderá utilizar essa opção.

A opção do window.open() consiste em abrir uma nova aba do navegador do usuário para que o mesmo faça o fluxo de captura, e ao final essa aba seja fechada e redirecionada para o site que estava anteriormente. Para isso recomendamos:

• Seguir a documentação publica sobre isso, que se encontra aqui;

• Que monitore se houve alteração de URL (para a redirectUrl) e então feche a aba utilizando window.close().

2) Utilizando redirect

Ao criar a transação foi passado por parâmetro o campo redirectUrl que será utilizado posteriormente, você precisará seguir os passos:

• Em seu fluxo comum (que está inserido o IDPay) você irá redirecionar o cliente para o link gerado via API;

• Após isso o cliente de dentro da webpage do IDPay irá realizar os procedimentos necessários para continuar o fluxo;

• Quando concluído, ele será redirecionado novamente para a sua página (utilizando o redirectUrl passado na criação da transação).

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.

Para o cenário de uso em Android, o uso de Webview é recomendado.

Após criar a transação e obter o link da transação, a seguinte implementação é recomendada:

• Em seu fluxo comum (que está inserido o IDPay), você irá abrir a Webview com o link gerado via API;

• Você poderá customizar essa abertura da maneira que for o ideal para seu aplicativo;

• Irá monitorar se houve alteração de URL (para a redirectUrl) e então feche a Webview;

Para abrir uma Webview é bem simples:

import android.webkit.PermissionRequest
import android.webkit.WebChromeClient
import android.webkit.WebView
import android.webkit.WebViewClient

@SuppressLint("SetJavaScriptEnabled")
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_camera)

    findViewById<WebView>(R.id.webView).apply {
        settings.javaScriptEnabled = true
        settings.domStorageEnabled = true
        settings.mediaPlaybackRequiresUserGesture = false
        clearCache(true)
        webViewClient = myWebViewClient
        webChromeClient = object : WebChromeClient() {
            override fun onPermissionRequest(request: PermissionRequest?) {
                request?.grant(request.resources)
            }
        }
        loadUrl("<URL_TO_LOAD>")
    }
}

Para controlar quando é necessário fechar o Webview pode ser feito da seguinte maneira:

private val myWebViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?
    ): Boolean {
        if (request?.url.toString() == "<URL_TO_OBSERVER>") {
            // close here your webview
        }
        return super.shouldOverrideUrlLoading(view, request)
    }
}

Para isso é necessário habilitar permissões na Android Manifest:

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/>

Exemplo de como deverá ficar no app:

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.

Para o cenário de uso utilizando Flutter, o uso da inappwebview é recomendado.

Após criar a transação e obter o link da transação, a seguinte implementação é recomendada:

• Em seu fluxo comum (que está inserido o IDPay), você irá abrir a inappwebview com o link gerado via API;

• Você poderá customizar essa abertura da maneira que for o ideal para seu aplicativo;

• Irá monitorar se houve alteração de URL (para a redirectUrl) e então feche a inappwebview;

Para abrir uma inappwebview e controlar a alteração de URL pode ser feito da seguinte forma:

  import 'package:flutter_inappwebview/flutter_inappwebview.dart';  
  import 'package:unico_poc_id_pay_inappwebview/RedirectScreen.dart';
  import 'package:unico_poc_id_pay_inappwebview/service.dart';

  Widget setWebView(String URL_TO_LOAD) {
    InAppWebViewGroupOptions options = InAppWebViewGroupOptions(
        crossPlatform: InAppWebViewOptions(
          useShouldOverrideUrlLoading: true,
          mediaPlaybackRequiresUserGesture: false,
        ),
        android: AndroidInAppWebViewOptions(
          useHybridComposition: true,
        ),
        ios: IOSInAppWebViewOptions(
          allowsInlineMediaPlayback: true,
        ));

    return Expanded(
      child: InAppWebView(
        initialUrlRequest: URLRequest(
          url: Uri.parse(URL_TO_LOAD),
        ),
        initialOptions: options,
        androidOnPermissionRequest: (controller, origin, resources) async {
          return PermissionRequestResponse(
              resources: resources,
              action: PermissionRequestResponseAction.GRANT);
        },
        onWebViewCreated: (controller) {
          setState(() {
            _inAppWebViewController = controller;
          });
        },
        onLoadStart: (controller, url) {
          print('CARREGANDO');
          setState(() {
            _link = url.toString();
          });
        },
        onProgressChanged: (controller, progress) {
          setState(() {
            progress == 100 ? _isLoading = false : _isLoading = true;
          });
        },
        onLoadStop: (controller, url) {
          print('CARREGADO');
          setState(() {
            _link = url.toString();
          });
        },
        shouldOverrideUrlLoading: (controller, navigationAction) async {
          var uri = navigationAction.request.url;
          if (uri == Uri.parse("<URL_TO_OBSERVER>")) {
            setState(() {
              _link = "";
            });

            Navigator.push(
              context,
              MaterialPageRoute(
                builder: (context) => const RedirectSreen(),
              ),
            );
            return NavigationActionPolicy.CANCEL;
          }
          return NavigationActionPolicy.ALLOW;
        },
      ),
    );
  }

Para obter permissão de câmera é possível fazer da seguinte forma:

  import 'package:permission_handler/permission_handler.dart';

  void requestPermission() async {
    var status = await Permission.camera.status;
    if (status.isDenied) {
      if (await Permission.camera.request().isGranted) {
        print("ok");
      }
    }
  }

Exemplo de como deverá ficar no app:

Para saber mais sobre, recomendamos uma leitura nos seguintes artigos e documentações:

• Para acessar a documentação oficial, clique aqui.

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.

Para o cenário de uso em iOS, o uso do WKWebView é uma das maneiras recomendadas.

Após criar a transação e obter o link da transação, a seguinte implementação é recomendada:

• Em seu fluxo comum (que está inserido o IDPay), você irá abrir a WKWebView com o link gerado via API;

• Você poderá customizar essa abertura da maneira que for o ideal para seu aplicativo;

• Irá monitorar se houve alteração de URL (para a redirectUrl) e então feche a WKWebView;

Para abrir uma WKWebView é bem simples:

Para controlar quando é necessário fechar o WKWebView pode ser feito da seguinte maneira:

Exemplo de como deverá ficar no app:

Para saber mais sobre, recomendamos uma leitura nos seguintes artigos e documentações:

Dúvidas frequentes sobre o Unico IDPay:

• Clique para acessar a FAQ do IDPay;

• Clique para acessar a FAQ geral da unico.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .