Elo Cloud Wallet

Framework de pagamento Elo no qual utiliza criptografia e tokenização baseadas em EMV, para executar transações seguras.

Feito para:  Adquirentes

Como funciona

É necessário que seja feita a Criação de um usuário no portal do desenvolvedor e o cadastro de uma nova aplicação. Após o cadastro da aplicação, utilize o Dashboard para acessar suas configurações de acesso para obter o Client_Id e o Client_Secret. O Client_Id deverá ser usado nos headers das chamadas de solicitação as APIs e, em seguida, será necessário a geração de uma autorização para obter o Access_Token. A autorização é obtida através de uma combinação Base64 do Client_Id + Client_Secret

Para a realização de todas as transações da Elo Cloud Wallet, é necessário ter um usuário criado, de acordo com a operação que será feita, como descrito nos próximos itens.

O Elo Cloud Wallet foi idealizado para ser usado por um Token Requestor que irá implementar uma carteira digital em um dispositivo que não se utiliza mecanismos de proteção de dados, mas precisa garantir toda segurança desses dados como os mecanismos de Host Card Emulation (HCE) e Trusted Execution Environments (TEE).

Durante a implementação do Elo Cloud Wallet o Token Requestor é separado em duas entidades. uma delas será o Token Requestor Client (TR CLIENT), que será responsável pela execução da aplicação de pagamentos nos dispositivos de seus clientes. A outra entidade será o Token Requestor Server (TR Server) que é baseado nos sistemas back-end do Token Requestor para que se obtenha dados de todos as aplicações de seus clientes. Como dito anteriormente, é necessário que o Token Requestor implemente essas entidades para que o Elo Cloud Wallet opere em sua aplicação.

O TR Client hospeda os componentes do Elo Cloud Wallet que serão utilizados por um dispositivo único e reúne dados únicos de impressões digitais do dispositivo. O TR recebe, gerência e protege chaves e credenciais do dispositivo, além de receber interações e dados do portador do cartão, incluindo dados sensíveis.

TR Server é responsável por armazenar dados do Token e gerenciar ações do ciclo de vida do Elo Payment Token. O TR Server também é encarregado de receber dados relevantes do TR Client, além de assegurar instâncias do TR Client que são exclusivamente identificadas e gerenciadas.

O TR Server irá realizar três interfaces que são elas:

-> Interface com as APIs que estão disponíveis nesta documentação para provisionar dados e credenciais de pagamento.

-> Interface com as APIs Elo para gerenciar o ciclo de vida do Token e dos dispositivos.

-> Interface com as APIs de autorização do Gateway de pagamentos para envio de transações

Para identificar um cartão Elo, realizar o roteamento convergente da autorização e também proporcionar o uso de informações para fins de prevenção de fraudes, é utilizado uma API de Bins para obter dados sobre o cartão. Para mais informações acesse a documentação da Tabela de Bins que esta presente no portal.

O recurso eligibilityCheckCards da permissão para que o Token Requestor possa verificar a elegibilidade do cartão. O passo para verificar a elegibilidade do cartão é extremamente importante para o fluxo de aprovisionamento do cartão, pois dependendo da resposta, o fluxo de aprovisionamento não deverá continuar.

Elo Cloud Wallet | Elegibility card

O campo cipheredEligibilityCheckData será o único campo dessa requisição e nele será informado um Sensitive, que se refere aos dados sensíveis do cartão quando cadastrado.

 {
  "cipheredEligibilityCheckData":"eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway..."
 }


Resposta


Quando for feita a requisição, irá ser retornado um eligibilityCheckCardId e um campo eligible no qual informa se o cartão é elegível ou não.

{
  "eligibilityCheckCardId": "f716427f-5b9a-4ff7-a0e2-57bb6befbcfd",
  "eligible": true
}

A vinculação do dispositivo é um processo para identificar um dispositivo que, deve ser identificado exclusivamente para garantir que os tokens sejam fornecidos e consumidos por dispositivos confiáveis. Informando os dados do dispositivo e a instância da carteira, essas informações irão se vincular com o token. A Elo gera as credenciais que irão ser correlacionadas com o dispositivo e que serão armazenadas seguramente no dispositivo e na instância da carteira.

Elo Cloud Wallet | Fluxo Device Binding

Para realizar a requisição de Device Binding é preciso informar dados do dispositivo.

{
   "cipheredBindInfo":"eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway...",  
   "cipheredProvisionDeviceData":"eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway...",
   "name": "Iphone",
   "brand": "Apple",
   "manufacturer": "Apple",
   "model": "iPhone 7 Plus",
   "type": "SMARTPHONE",
   "networkType": "GSM",
   "board": "device",
   "country": "BRA",
   "serialNumber": "ABCDEFGHIJK",
   "imei": "123456789012345",
   "os": "IOS"
}



Resposta


Após ser realizado a requisição, será retornado algumas informações sobre o Vínculo do Dispositivo.

{
   "deviceId": "d10b038e-4a45-4a6a-94fd-5634497ff6fe",      
   "cipheredWalletSecret":"eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway...",
   "status": "SUCCESS"
}





Para fazer a autenticação de um novo dispositivo, deve ser incluído na requisição o walletId e o tipo do atributo.

{
    "walletId": "0fa2233a-cfa4-4a2c-bb4c-2f44d9595d3c",
    "type": "CARD_PROVISIONING"
}




Resposta


A resposta da requisição retornará os seguintes campos:

{
  "challengeId": "1e63ef67-00b5-4905-ade4-04f5bba36574",
  "dataSet": [
    "challengeId",
    "tokenHolderId",
    "name",
    "pan",
    "exp"
  ]
}


É retornado uma matriz dataSet, no qual é um conjunto de dados que a API irá incluir e assinar posteriormente. O valor retornado no campo challengeId será usado em outras requisições do aprovisionamento.

Com um dispositivo vinculado e autenticado, já é possível provisionar um cartão e conseguir usá-lo no Elo Cloud Wallet. O aprovisionamento de cartão solicita que a Elo gere um token de pagamento que será vinculado com a combinação dos dados do dispositivo e da carteira para um cartão Elo. As informações confidenciais do usuário e do cartão serão criptografadas e assinadas.

Elo Cloud Wallet | Fluxo Provisioning Card


Para realizar o aprovisionamento do cartão é necessário que seja feita a seguinte requisição:

{
  "walletSignature": "ZVLWM0IiwieSI6IlRxMUc1R3FkalRLajdYelpFQ1b3UzUE1vRUNsODM1VFUifX0…",
  "deviceSignature": "’SxmMy4GUyF3E0BP0BOHmfdhItt87KDKcZmHHFTNFGNnJmK5Dtvp8Gsg7x...",
  "riskData": {
    "device": {
      "score": 4,
      "scoringAlgorithm": "10",
      "scoringAlgoVersion": "10",
      "country": "BR",
      "timeZoneManager": "CARRIER"
    },
    "wallet": {
      "cardTenurePeriod": 0,
      "creationPeriod": 0,
      "cardholderNameMatches": true,
      "tokensOnDevice": 0,
      "cardInputMethod": "MANUAL",
      "flowIndication": "GREEN",
      "flowAlgorithm": "10",
      "flowAlgorithmVersion": "10"
    }
  },
  "walletId": "0fa2233a-cfa4-4a2c-bb4c-2f44d9595d3c",
  "cipheredProvisionCardData": "hlUNNEfOgqkfJTlIDF3fhS9y_uFC95IBsDZF1zgkDHJL...",
  "cardInputMethod": "MANUAL",
  "device": {
    "deviceId": "d10b038e-4a45-4a6a-94fd-5634497ff6fe",
    "geolocation": {
      "lon": 0,
      "lat": 0,
      "alt": 0,
      "precision": 0,
      "source": "USER"
    },
     "osVersion": "string",
     "networkOperator": "string",
     "ip": "192.168.5.102"
  }
}

O retorno o será um 202 e não possuirá um corpo de resposta, porém no header irá ser retornado um provisionId.

Para prosseguir com o fluxo de aprovisionamento de cartão é necessário que o portador de cartão aceite os Termos e Condições, caso não for aceito, o aprovisionamento do cartão não poderá ser feito.

Para confirmar o aceite dos Termos e Condições, será obrigatório informar o provisionId no endpoint da requisição. O agreementTermId será enviado no header do retorno da requisição.

Para obter mais informações sobre o aprovisionamento é possivel fazer uma consulta informando o provisionId no endpoint:

{
  "provisionId": "5c27dec1-71cc-4e18-8d87-ef26fd42175b",
  "tokenId": "03910309-8ad0-4d5a-866f-06636ea66ecd",
  "status": "IN_PROGRESS",
  "agreementTermId": "1234567890",
  "createdAt": "2020-01-01T12:26:43.826",
  "idvSkip": true,
  "card": {
    "bin": "123456",
    "last4": "6789",
    "cardArts": [
      {
        "resourceId": "937d62bd-ef38-48ab-8c71-ebdc1b23c699",
        "width": 100,
        "height": 100,
        "mimeType": "image/png",
        "type": "DIGITAL_ART",
        "backgroundColor": "FFFFFF",
        "foregroundColor": "000000",
        "qualifier": "JSPEEDY"
      }
    ]
  },
  "riskData": {
    "device": {
      "score": 4,
      "scoringAlgorithm": "10",
      "scoringAlgoVersion": "10",
      "country": "BR",
      "timeZoneManager": "CARRIER"
    },
    "account": {
      "id": "b6e9d3bb-2f12-44b0-9d8c-339f66cc4349"
    },
   "wallet": {
      "cardTenurePeriod": 0,
      "creationPeriod": 0,
      "cardholderNameMatches": true,
      "tokensOnDevice": 0,
      "cardInputMethod": "MANUAL",
      "flowIndication": "GREEN",
      "flowAlgorithm": "10",
      "flowAlgorithmVersion": "10"
    }
  },
  "device": {
    "deviceId": "d10b038e-4a45-4a6a-94fd-5634497ff6fe",
    "status": "SUCCESS",
    "createdAt": "2020-01-01T12:26:42.798",
    "name": "Iphone",
    "brand": "Apple",
    "manufacturer": "Apple",
    "model": "A1549",
    "type": "SMARTPHONE",
    "networkType": "GSM",
    "os": "Android",
    "country": "BRA",
    "geolocation": {
      "lon": 0,
      "lat": 0,
      "alt": 0,
      "precision": 0,
      "source": "USER"
    },
    "osVersion": "string",
    "networkOperator": "string",
    "ip": "192.168.5.102"
  }
}



A etapa de verificação do titular do cartão será de acordo com os métodos de ID&V, e cada emissor pode escolher o método que irá usar para fazer o aprovisionamento do cartão.


O fluxo vermelho acontece quando o emissor não permite o aprovisionamento do cartão solicitado.


O fluxo verde indica que não será necessário mais nenhum passo de verificação do cartão. Um token será criado em estado de ativo e já poderá ser utilizado para realizar transações.


O fluxo amarelo indica que será necessário algum passo para verificação do portador do cartão. Nesse fluxo será retornado uma lista com os métodos ID&V. A opção escolhida pelo portador será retornado para Elo, informando qual foi o método ID&V escolhido para fazer o passo de identificação. O primeiro passo é o notifyID&V, informando o método ID&V escolhido pelo portador. O segundo passo será o validateID&V, que recebe e valida os dados fornecidos pelo portador.

Para fazer uma consulta sobre os métodos de verificação ID&V disponíveis, será necessário realizar uma chamada informando o provisionId no endpoint da requisição e será retornado um array com os métodos ID&V disponíveis para esse aprovisionamento.

[
    "OTP_EMAIL",
    "OTP_SMS",
    "APP_TO_APP",
    "CALL_TO_CALLCENTER"
]




ID&V para Call Center ou Verificação no App


Caso o portador escolha as opções de Call Center ou Verificação no Aplicativo, o emissor é o responsável por confirmar os dados do portador e criar o token.

Elo Cloud Wallet | Fluxo App e Call Center

Na requisição de notifyID&V poderá ser informado os seguintes valores:

-> CALL_TO_CALLCENTER: Verificação através do Call Center do emissor do cartão.

-> APP_TO_APP: Verificação feita através do Aplicativo do emissor do cartão.

{
  "type": "CALL_TO_CALLCENTER"
}



ID&V One-time password


O portador poderá escolher a opção de verificação One-time password (OTP), no qual um código será retornado e deverá ser confirmado.

Elo Cloud Wallet | Fluxo Sms ou Email

Na requisição de notifyID&V poderá ser informado os seguintes valores:

-> OTP_SMS: Verificação OTP através de mensagem SMS

-> OTP_EMAIL: Verificação OTP através de Email.

{
  "type": "OTP_EMAIL"
}



Validate ID&V


Após ser feito o notifyID&V é necessário validar o código que foi enviado. O Token Requestor deve validar com a requisição validateID&V as informações enviadas pelo ID&V do emissor.

{
   "deviceSignature":"SxmMy4GUyF3E0BP0BOHmfdhItt87KDKcZmHHFTNFGNnJmK5Dtvp8Gsg7x...",
   "walletSignature":"ZVLWM0IiwieSI6IlRxMUc1R3FkalRLajdYelpFQ1b3UzUE1vRUNsODM1VFUifX0...",
   "walletServerSignature": "ZW5JZCI6IjJlMWNjN2VkLTVlODctNGU3ZC05MmEyiOSWEd3…"",
   "challengeId": "1e63ef67-00b5-4905-ade4-04f5bba36574",
   "deviceId": "d10b038e-4a45-4a6a-94fd-5634497ff6fe",
   "walletId": "0fa2233a-cfa4-4a2c-bb4c-2f44d9595d3c",
   "tokenId": "03910309-8ad0-4d5a-866f-06636ea66ecd",
   "type": "OTPEMAIL",
   "cipheredOtpValue": "eyLWM0IiwieSI6IlRxMUc1R3ttreSDF123Q1b3UzUE1vRUNsODM1VFUifX0..."
}



O Elo Cloud Wallet solicita um criptograma de autenticação baseado em EMV. Esse criptograma é usado para autorização de transação, para garantir a segurança e autenticidade. O criptograma de transação será gerado com base em dados únicos e dinâmicos e será válido somente para uma transação.

Elo Cloud Wallet | Fluxo Transaction Cryptogram

Antes de fazer a requisição, é necessário que o Token Requestor busque o criptograma de autenticação para que a Elo possa receber e validar esse criptograma. O campo onde esse criptograma deverá ser informado será o cipheredTransactionCryptogramData.

{
   "deviceSignature":"SxmMy4GUyF3E0BP0BOHmfdhItt87KDKcZmHHFTNFGNnJmK5Dtvp8Gsg7x...",
   "walletSignature":"ZVLWM0IiwieSI6IlRxMUc1R3FkalRLajdYelpFQ1b3UzUE1vRUNsODM1VFUifX0...",
   "walletServerSignature":"ZW5JZCI6IjJlMWNjN2VkLTVlODctNGU3ZC05MmEyiOSWEd3…",
   "deviceId": "d10b038e-4a45-4a6a-94fd-5634497ff6fe",
   "walletId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "cipheredTransactionCryptogramData":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiRUNESC1FUyIsImtpZCI6IA..."
}



Resposta


Após feita a requisição, será retornado o cipheredCryptogram:

{
  "cipheredCryptogram":"eyJhbGciOiJFQ0RIxnZOaKQowS91Bs-  2RdJZR92jneEyVtcJ9IXJEptU..."
}


Para fazer uma consulta das credenciais do token. O Token Requestor receberá um tokenId que deverá ser informado no endpoint da requisição, para recuperar as credenciais do token.

Elo Cloud Wallet | Fluxo Credenciais do Token

{
  "cipheredCredentialsData":"eyJLoufiOiJFQ0RIKQoS91BPEDFcvacR92jneEyVtcJ9IXJEptU..."
}




Resposta


Na resposta será retornado as informações sobre o status do token.

{
  "cipheredToken": "eyPOoufiOiJFQ0RIKQoS55BPYURcvacR21jneEyVtcJ9IXJEptU",
  "deploymentStatus": "NOT_DEPLOYED",
  "suspensionStatus": "NOT_SUSPENDED"
}



O Elo Cloud Wallet possui duas classes de status de vida dos tokens. Uma dessas classes é o Deployment Status. Quando um token é implementado á uma carteira e á um dispositivo específico, indica que este token poderá ser usado neste contexto. O Deployment Status suporta os seguintes valores:

-> DEPLOYED: Token ativado

-> TERMINATED: Token inativado e inutilizável

-> DEPLOY_FAILED: Token não pode ser implementado

A outra classe se chama Suspension Status. Está classe é responsável por indicar a suspensão do token e suporta os seguintes valores:

-> SUSPENDED: Token implementado, mas não está apto para realizar transações.

-> NOT_SUSPENDED: Token implementado e liberado para realizar transações.

O TR pode alterar o Status do Token de acordo com as suas necessidades. Com a requisição a seguir é possível alterar esse Status.

Elo Cloud Wallet | Ciclo de vida do Token

{
  "cipheredCardTokenStatusUpdate":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2NeU14RzdFYkQQ...",
  "timestamp": "2020-01-29T14:47:00.000Z",
  "deploymentStatus": "DEPLOYED",
  "suspensionStatus": "NOT_SUSPENDED",
  "reason": "TESTE"
}




O retorno dessa requisição será um 204 sem conteúdo.