Tokenização Estabelecimento Comercial

Permite substituir os dados de um cartão de forma segura por um cartão virtual de uso controlado.

Feito para:  Estabelecimentos ComerciaisMerchantsFacilitadoresAcquirersAdquirentes

Como funciona

Primeiros passos

  1. Leia Introdução ao GraphQL, com exemplos reais da nossa API.

  2. Crie um usuário no portal do desenvolvedor.

  3. Cadastre sua primeira aplicação.

  4. Utilize o dashboard para acessar suas configurações de acesso.

  5. Para explorar rapidamente as APIs aqui na página de documentação, use o console de GraphQL, na seção de referências. Nele, você pode ver as consultas de exemplo, executá-las e alterá-las.

Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista

Utilizado para transações online, em lojas que operam com as modalidades de CoF (Card on File) e recorrência.

O E-commerce Token é um produto destinado a lojistas, gateways, credenciadores ou qualquer entidade prestadora de serviço para o comércio eletrônico que operam em uma destas modalidades.

O Token se comporta como um cartão virtual, entretanto, pode ser parametrizado e ter um escopo de atuação reduzido, consequentemente eliminando ou reduzindo o potencial de fraudes, como especificado pelas restrições de uso em CardUsageConstraits.

No caso de vazamento de dados, seja por perder um telefone celular ou hackers invadirem o servidor do comerciante, apenas o Token seria exposto e então limitado ao seu escopo de atuação.

O processo de Tokenização é util a diversas entidades:

  • Emissores (Bancos): através de seu aplicativo, permite que o portador crie um Token, para usar, por exemplo, em lojas virtuais.

  • Portadores: aplicativo da própria Elo ou de terceiros pode criar Tokens para serem usados em compras. Um exemplo são aplicativos que fazem transações via NFC ou QRCode. O portador do cartão precisa estar logado e autorizar o acesso a operação desse tipo. Ao invés de divulgarem os dados do cartão real criam um token com escopo reduzido para o propósito da transação. Durante o processo de tokenização, o Emissor é notificado a cada geração de token.

  • Comerciantes, Adquirentes e Facilitadores: ao invés de guardar dados sensíveis do cartão em suas bases, o comerciante troca os dados sensíveis por um Token de uso exclusivo para si próprio (usageConstraints { allowedIdCodes: [1234] }), e se possível com mais restrições. Uma vez que seu servidor seja comprometido, os tokens não terão utilidade a terceiros e também poderão ser cancelados sem impactar o portador do cartão. Durante o processo de tokenização, o Emissor é notificado a cada geração de Token.

Para a realização do processo de Tokenização, é necessário ter um usuário criado, ter um access_token gerado através da API de Login e ter associado um usuário ao tipo Merchant, Acquirer ou Facilitador.

Sensitive são os dados sensíveis de um cartão (número do cartão, nome do portador, código de verificação e validade) devidamente assinados e criptografados de forma a garantir a segurança.

A implementação da estrutura de segurança desse serviço usa chaves e credenciais para autenticar cada componente individualmente, como os sistemas de E-commerce dos lojistas, gateways e credenciadores. Essa autenticação é esperada pela Elo.

Para melhor segurança, os dados sensíveis nunca são trafegados de forma aberta, mesmo que o transporte (HTTPS) seja seguro. Utilizamos JSON Web Encryption - JWE e JSON Web Signature - JWS, e o processo de criptografia de curvas elípticas (ECC) como algoritmo de criptografia.

Esses processos criptográficos têm como objetivo a garantia da integridade e confidencialidade dos dados provenientes de transações. Para iniciar o processo de criptografia, é preciso ter os dados em formato JSON como descrito abaixo:

  • pan: O número da conta primária (Primary Account Number), também conhecido como "número do cartão" físico. Exemplo: "1234567890123456".

  • expiry: Data de validade do cartão, ou seja, quando ele expira. É um objeto composto pelas chaves month e year descritas a seguir. Exemplo: {"month": 2, "year": 2020}.

    "month": Mês da validade do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).
    "year": Ano da validade do cartão. Número inteiro com 4 dígitos (2017, não 17).

  • name: Nome do portador do cartão. Exemplo: "João da Silva".

  • csc: Código de segurança do cartão (Card Security Code), usualmente impresso na parte de trás do cartão físico.

  • cscEntryTime: (opcional) Data e horário quando o CSC (Código de Segurança do Cartão) foi digitado. É necessário quando o CSC é gerado por um chaveiro/token baseado em tempo. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00".

NOTA: a autorização é feita com os campos csc e seu respectivo horário de entrada. Apenas um deles deve ser especificado.

Exemplo completo do JSON de sensitive:

{
  "pan": "1234567890123456",
  "expiry": {
    "month": 2,
    "year": 2020
  },
  "name": "João da Silva",
  "csc": "222"
}

Tendo os dados sensíveis do cartão em um objeto, podemos começar a gerar o sensitive.

O primeiro passo é gerar um par de chaves EC do tipo P-256. Exemplo de par gerado localmente:

{
    "pair": {
        "kty": "EC",
        "kid": "example",
        "crv": "P-256",
        "x": "",
        "y": "",
        "d": ""
    },
    "public": {
        "kty": "EC",
        "kid": "example",
        "crv": "P-256",
        "x": "",
        "y": ""
    }
}

NOTA: a chave "pair" deve ser armazenada e secreta, não podendo ser compartilhada.

O segundo passo é cadastrar chave pública em formato JSON com a mutation addPublicKeyToUser.

mutation {
    addPublicKeyToUser(input:{
        clientMutationId:"012", 
        userId:"bdc89491-f1f4-32f7-bad2-f44ae3b88aa6", 
        key:"{\"kty\":\"EC\", \"kid\":\"my-public-key-id-1\", \"x\":\"g_Sr4WwVDt5Qy3KonZyXqFwWykTR9KVMCt8Sx-dXSB8\",\"y\":\"ydSE-mUMtuhBTI_txDpd2ivb7e6FNzxq4e_18iHFZ2U\",\"crv\":\"P-256\"}",
        format:JWK
  }) {
        clientMutationId, 
        user{
            id,
            firstName,
            lastName
        }, 
        publicKey{
            key
        }
    }
}

O terceiro passo é assinar os dados sensíveis do cartão com essa chave privada (formato JWS).

A estrutura de assinatura segue a seguinte ideia:

JWS.Sign(issuer=UserPrivatePairKey, format=compact,
    JSON.Stringify({"pan":"5067580000000000", "expiry": {"month": 12, "year": 2021}, "csc": 123})
)

O quarto passo é consultar a chave pública da Elo com a query serverPublicKey.

query {
    serverPublicKey {
        key
    }
}

O quinto passo é, com a chave pública retornada, criptografar o dado assinado no terceiro passo.

A estrutura de criptografia segue a seguinte ideia:

JWE.Encrypt(recipient=ELOPublicKey, format=compact,
    SignedData
)

Pronto! Agora, você possui os dados sensíveis do cartão criptografados.

Para descriptografar o sensitive, basicamente, fazemos o inverso do Processo de Criptografia.

O primeiro passo é decriptografar o sensitive no formato JWE utilizando a chave privada.

JWE.Decrypt(recipient=ELOPublicKey, format=compact,
    SignedData
)

O segundo passo é consultar a chave pública da Elo com a query serverPublicKey.

query {
    serverPublicKey {
        key
    }
}

O terceiro passo é validar a assinatura dos dados descriptografados no passo um com a chave pública retornada da Elo;

JWS.Verify(issuer=mrN7B1XNsvH__XjuFmiLUKAQs-R4YgqVuMh69OTTnO0, format=compact,
        JSON.Parse(StringfiedData)
)

Pronto! Agora, você possui os dados sensíveis (Token)

O primeiro passo para a realização de um aprovisionamento, será realizando o cadastro do cartão do portador na plataforma da Elo.

Durante o cadastro, será realizado o processo de aprovisionamento, resultando na geração de um Card ID.

O Card ID fará referência à um específico cartão de um portador, para aquele parceiro específico no qual o cadastro está sendo realizado. O Card ID é a informação chave para geração de um Token a ser utilizado no processo de compra.

Utilizando os dados sensíveis do cartão devidamente criptografados, é necessário realizar o aprovisionamento do cartão através da mutation createCardTokenForUser com os dados sensíveis do cartão inseridos no campo sensitive:

mutation {
  createCardTokenForUser(input: {
    sensitive: "dados sensiveis criptografados",
    tokenRequestorId: "000000000000", # Mais informações desse campo na seção "TokenRequestorId"
    user: { # Dados do usuário do cartão a ser tokenizado
      name: "name",
      legalIds: {
        cpf: "123456789",
        rg: {
          number: "0978654322", 
          issuerOrganization: "SSP",
          issuerState: "SP",
          issueDate: "2018-04-24"
        }
      }, 
      birthday: "1993-08-09", 
      gender: MALE,
      maritalStatus: SINGLE,
      contacts: {
        type: PHONE, 
        context: "context",
        value: "+5527999365103"
      }
    },
    usageConstraints: { allowedIdCodes: ["123"] }
  })
  {
    cardToken { # Token retornado, deve ser salvo pois não pode ser consultado!
      id # informação utilizada para suspender o cardToken
      last4
      expiry { 
        month
        year 
       }
      cardOrigin { id }
    }
  }
}

Para criar um Token a partir das informações de um cartão previamente cadastrado utilize o campo cardId na mutation createCardTokenForUser como demonstrado abaixo:

mutation {
  createCardTokenForUser(input: {
    cardId: "fd5c9b0a-5d2d-4b9a-957e-62c2415c0a0c",
    tokenRequestorId: "00000000000", # Mais informações desse campo na seção "TokenRequestorId"
    user: { # Dados do usuário do cartão a ser tokenizado
      name: "name", 
      legalIds: {
        cpf: "123456789", 
        rg: {
          number: "0978654322", 
          issuerOrganization: "SSP", 
          issuerState: "SP", 
          issueDate: "2018-04-24"
        }
      }, 
      birthday: "1993-08-09", 
      gender: MALE,
      maritalStatus: SINGLE, 
      contacts: {
        type: PHONE, 
        context: "context", 
        value: "+5527999365103"
      }
    },
    usageConstraints: {
      allowedTxAmounts: [
        {
          currency: "BRL", 
          min: 10, 
          max: 1000
        }
      ]
    }
  }) 
  {
    cardToken { # Token retornado, deve ser salvo pois não pode ser consultado!
      id # informação utilizada para suspender o cardToken
      last4
      expiry {
        month
        year
      }
      cardOrigin { id }
    }
  }
}

O campo tokenRequestorId é obrigatório e identifica a bandeira de cartão, gateway de pagamento e Estabelecimento Comercial. Os 3 primeiros dígitos identificam a bandeira, os próximos 3 dígitos identificam o gateway, e por fim, os últimos 5 dígitos identificam o Estabelecimento Comercial.

  • Ex: Elo - 578. Código do Gateway - 001-199. Código do EC - 00000-999999. Ao se estruturar, ficará da seguinte maneira: 57819900000.

O campo usageConstraints permite ao requisitante do Token limitar a utilização do mesmo, restringindo conforme parâmetros estabelecidos, como por exemplo, qual o estabelecimento comercial que irá utilizá-lo, o valor da transação e o tempo máximo de duração do Token. Este é um campo opcional para a geração do Token, no entanto, uma camada de segurança adicional limitando o uso do token para um fim especifico; abaixo exemplo dos campos trafegados:

  • expiry - data de expiração do token. Ex: expiry: "2020-05-29T12:08:56Z", limita o uso do token a uma data específica, que pode ser diferente da validade do cartão real;

  • allowedTxAmounts - limite de transação por moeda. Ex: allowedTxAmount: [{currency: “USD”, max: 100}] limita o token transacionar até USD$100;

  • allowedIdCodes - restrição de Comerciantes por identificadores. Ex: allowedIdCodes:[123, 456], permite o token ser utilizado em apenas dois logistas com identificadores 123 e 456;

  • allowedMerchantCategories e deniedMerchantCategories - restrição de Categorias de Comerciantes. Ex: allowedMerchantCategories para limitar o uso a apenas alumas categorias de comerciantes e deniedMerchantCategories para proibir categorias.

Os processos de exclusão ou suspensão de um Token podem ser inicializados tanto pelo banco emissor de um cartão (por exemplo, em um caso que o cartão físico do portador seja cancelado), ou pelo parceiro conectado na plataforma de API Elo para o E-commerce Token (por exemplo, usuário decide por não utilizar mais determinado cartão em uma loja virtual).

Para o caso de exclusão ou suspensão de um cartão pelo Emissor, o parceiro somente será avisado pelo Emissor, quando o recebimento das notificações de exclusão ou suspensão de um Token.

O parceiro poderá realizar o processo de suspensão de um Token utilizado no E-commerce Token através da API SuspendCardToken:

Exemplo do uso da API:

mutation {
    suspendCardToken(input: {
        cardTokenId: "67F47F96-3D36-4199-8C7E-67ADC6DEC58C", # preferencialmente
        sensitive: "...dados sensíveis cifrados...", # se não tiver cardTokenId
        permanent: true,
        reason: ISSUER # Veja o enum CardSuspendReason para ter as opções
    }) 
    {
        cardToken { id }
    }
}

NOTA: para suspendCardToken os dados sensíveis e o identificador global único são referências ao Token e não ao cartão real o qual foi utilizado em createCardTokenForUser!

O processo de atualização de um Cartão pode ser iniciado apenas pelo banco emissor do cartão. Para esse cenário, o parceiro será avisado pela API dessa atualização.