Tokenização

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

Feito para:  Estabelecimentos ComerciaisEmissoresAdquirentesFacilitadores

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, como para uso em lojas virtuais.

  • Portadores: aplicativo da própria Elo ou terceiros podem 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 guardarem 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 criação do token (e de todo o processo de tokenização), é necessário ter um usuário criado e tê-lo associado a um Comerciante, a um Emissor ou a um Portador de Cartão, de acordo com a operação que será feita, como descrito abaixo.

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

Estes processos criptográficos têm como objetivo a garantia de integridade e confidencialidade dos dados provenientes de transações capturadas pelo e-commerce, utilizando os serviços de tokenização Elo.

Para melhor segurança, os dados sensíveis, como o PAN, Código de Verificação Elo (CVE2) e data de validade, 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 processo de criptografia de curvas elípticas (ECC) como algoritmo de criptografia.

Para uma maior definição sobre o campo sensitive, acesse a documentação de Cadastro do Portador.

A estrutura dos dados criptografados seguirá a seguinte forma:

JWE.Encrypt(recipient=ELOPublicKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact,
        JSON.Stringify(DeviceSensitiveInput)
    )
)

Ao consultar dados sensíveis deve-se registrar a chave com o servidor e então enviar o identificador da chave, fazendo o processo reverso no valor retornado:

JSON.Parse(payload of
    JWS.Verify(payload of
        JWE.Decrypt(sensitive)
    )
)

Chaves

A chave pública do servidor (ELOPublicKey) está disponível através da API serverPublicKey:

query {
    serverPublicKey {
        key
    }
}

Já as chaves públicas do usuário (i.e: referente à UserKey) deverão ser geradas nos dispositivos dos clientes e associadas ao usuário na plataforma através da API 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
        }
    }
}

Como CardHolder (Portador), será necessária a utilização da API createCardToken.

O token pode ser criado a partir dos dados sensiveis do cartão (PAN, CSC e data de validade) assinados e cifrados conforme a seção anterior ou de um cardId (id de cartão previamente cadastrado).

Utilizando os dados sensíveis do cartão devidamente criptografados, é possível fazer uso da API createCardToken com os dados inseridos no campo sensitive:

# Mutation disponível apenas para usuário do tipo CardHolder
mutation {
  createCardToken(input: {
    sensitive: "dados sensiveis criptografados", 
    tokenRequestorId: "00000000000", # Mais informações desse campo na seção "TokenRequestorId"
    origin: {
      ip: "200.123.1.2", 
      geolocation: {
        lat: 1.2345, 
        lon: -1.2345, 
        source: CELLULAR
      }, 
      device: {
        userAgent: "Xpto", 
        brand: "Apple", 
        model: "iPhone 7", 
        type: SMARTPHONE
      }
    }, 
    usageConstraints: {
      allowedTxAmounts: [
        {
          currency: "BRL", 
          min: 10, 
          max: 1000
        }
      ]
    }
  }) 
  {
    cardToken {
      id
      last4
      expiry {
        month
        year
      }
      cardOrigin { id }
    }
  }
}

Durante o cadastro, será realizado o processo de aprovisionamento, no qual é gerado 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 será a informação chave para geração de um Token que será utilizado no processo de compra.

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

# Mutation disponível apenas para usuário do tipo CardHolder
mutation {
  createCardToken(input: {
    cardId: "fd5c9b0a-5d2d-4b9a-957e-62c2415c0a0c", 
    tokenRequestorId: "00000000000", # Mais informações desse campo na seção "TokenRequestorId"
    origin: {
      ip: "200.123.1.2", 
      geolocation: {
        lat: 1.2345, 
        lon: -1.2345, 
        source: USER 
      }, 
      device: {
        userAgent: "Xpto", 
        brand: "Apple", 
        model: "iPhone 7", 
        type: SMARTPHONE
      }
    }, 
    usageConstraints: {
      allowedTxAmounts: [
        {
          currency: "BRL", 
          min: 10, 
          max: 1000
        }
      ]
    }
  }) 
  {
    cardToken {
      id
      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 6 dígitos identificam o Estabelecimento Comercial (Merchant).

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

O campo usageConstraints auxilia na parametrização e impacta na atuação do Token, consequentemente eliminando ou reduzindo o potencial de fraudes. As restrições podem ser dos tipos:

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

  • allowedTxAmount – 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 – restrição de Categorias de Comerciantes. Ex: allowedMerchantCategories para limitar o uso a apenas alumas categorias de comerciantes e deniedMerchantCategories para proibir categorias.

Para os outros tipos de usuários - como dos tipos Merchant, Acquirer e CardIssuer - será necessária a utilização da API createCardTokenForUser, com o uso do campo user.

Assim como o processo de criação de token pelo CardHolder (Portador), o token pode ser criado a partir dos dados sensiveis do cartão (PAN, CSC e data de validade) assinados e cifrados conforme a seção de Criptografia ou de um cardId (id de cartão previamente cadastrado), mantendo o campo usageConstraints.

Tanto para um novo cadastro, como para uma compra realizada com um cartão previamente cadastrado, o parceiro deverá utilizar a API createCardTokenForUser.

Utilizando os dados sensíveis do cartão devidamente criptografado, é possível fazer uso da API createCardTokenForUser com os dados inseridos no campo sensitive:

# Mutation disponível apenas para usuário do tipo Merchant, Acquirer e CardIssuer
mutation {
  createCardTokenForUser(input: {
    sensitive: "<dados sensiveis criptografados>",
    tokenRequestorId: "000000000000",
    # Mesmo padrão do `createCardToken`
    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"
      }
    },
    origin: { # forneça o máximo de informação possível!
      ip: "200.123.1.2",
      geolocation: { lat: 1.2345, lon: -1.2345, source: CELLULAR },
      device: { userAgent: "Xpto", brand: "Apple", model: "iPhone 7", type: SMARTPHONE }
    },
    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 createCardToken como demonstrado abaixo:

# Mutation disponível apenas para usuário do tipo Merchant, Acquirer e CardIssuer
mutation {
  createCardTokenForUser(input: {
    cardId: "fd5c9b0a-5d2d-4b9a-957e-62c2415c0a0c",
    tokenRequestorId: "00000000000",
    # Mesmo padrão do `createCardToken`
    user: {
      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"
      }
    }, 
    origin: {
      ip: "200.123.1.2", 
      geolocation: {
        lat: 1.2345, 
        lon: -1.2345, 
        source: CELLULAR
      }, 
      device: {
        userAgent: "Xpto", 
        brand: "Apple", 
        model: "iPhone 7", 
        type: SMARTPHONE
      }
    }, 
    usageConstraints: {
      allowedTxAmounts: [
        {
          currency: "BRL", 
          min: 10, 
          max: 1000
        }
      ]
    }
  }) 
  {
    cardToken {
      id
      last4
      expiry {
        month
        year
      }
      cardOrigin { id }
    }
  }
}

Esta mutation se diferem das mutations do CardHolder (Portador do cartão) em apenas um campo:

  • user Objeto com dados cadastrais do usuário do cartão tokenizado (name, address, contacts, legalIds, etc).

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 de um cartão pelo emissor, o parceiro somente será avisado pelo emissor, quando o recebimento de 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 createCardToken!

Existem casos onde é necessário atualizar o cartão original relacioando ao token, pois o mesmo pode ter sido cancelado por algum motivo e trocado por um cartão novo. Logo, para não perder os tokens que já foram criados para o cartão antigo, é necessário atualizar o cartão original dos tokens.

Para isso, deve-se utilizar a mutation updateCardOriginToToken, enviando os dados sensíveis originais do cartão, e os novos dados sensíveis, contendo as informações atualizadas:

mutation {
  updateCardOriginToToken(input: {
    clientMutationId: "123", 
    cardOriginToTokens: {
      updateCardOriginId: "326f7e99-17af-44c8-82ca-848eab4fac89", 
      sensitiveCurrent: "dados sensiveis criptografados", 
      sensitiveNew: "dados sensiveis criptografados"
    }
  }) 
  {
    cardOriginToTokens {
      bin {
        number
      }
      last4
    }
  }
}

Nessa mutation, sensitiveCurrent contém os dados sensíveis do cartão original que foi tokenizado, enquanto sensitiveNew contém as novas informações atualizadas.




Query (consulta) compatível com a identificação de objetos do Relay

IDs são protegidos por permissões de contexto. Um node apenas pode ser buscado por seu identificador caso seja autorizado pelas permissões do usuário.

O retorno especifica a interface Node que contém apenas o campo id, o qual já é designado como parâmetro. Portanto para utilizar essa chamada utilize fragment para especificar quais campos retornar para cada tipo que implementa esta interface.

Fragmentos inline:

node(id: "identificador-global-123") {
  __typename
  ... on Card {
    last4
  }
}

Fragmentos reusáveis:

fragment CardLast4Fragment on Card {
  last4
}

node(id: "identificador-global-123") {
  __typename
  ...CardLast4Fragment
}

Especificação de identificador global de objetos (Relay Global Object Identification Specification).

Argumentos:

id: ID obrigatório

Identificador global único do nó (objeto) a ser consultado.



Argumentos:






Cria um token para um determinado cartão.

Usável por:

  • Portadores de cartão, a partir de suas aplicações de carteiras digitais.

  • Comerciantes que trocam PAN por um token, reduzindo o risco de sua própria base de dados, evitando armazenar PAN.

  • Emissores, por exemplo em seus aplicativos ou internet banking criarem um token à pedido do usuário.

Note que um portador pode criar tokens apenas para cartões em sua posse.

Um comerciante tem que ser credenciado a criar tokens pela plataforma. Ainda não disponível

Esta mutação tem como principais parâmetros (dentro de input):

  • sensitive dados sensíveis que deverão ser cifrados, por exemplo número do cartão (PAN), data de expiração, código de segurança do cartão (CSC). Devem ser utilizados quando o cardId é desconhecido.

  • cardId o identificador global único do cartão a ser utilizado.

Para a primeira operação em um determinado cartão em geral não se tem o cardId, logo utiliza-se sensitive. Em caso de sucesso, o token será retornado e então deve-se consultar o cartão e dele o seu identificador, podendo ser utilizado nas próximas operações:

mutation {
   createCardToken(input: {"sensitive": "...."}) {
      cardToken {
         card { id }  `cardId` para próximas operações createCardToken()
          ... demais campos da consulta ...
      }
}

Não há problemas em passar ambos cardId e sensitive. Neste caso cardId será utilizado preferencialmente e em caso de erro os dados sensíveis (sensitive) serão utilizados.

Argumentos:

input: CreateCardTokenInput obrigatório



Suspende um CardToken

Usável por:

  • Portadores de cartão, a partir de suas aplicações de carteiras digitais, para suspender tokens criados por si mesmos ou comerciantes.

  • Comerciantes para suspender tokens criados por si mesmos.

  • Emissores para suspender tokens associados a cartões que emitiu.

Argumentos:

input: SuspendCardTokenInput obrigatório



Ativa um cartão previamente inativo.

Usável por:

  • Portadores de token, a partir de suas aplicações de carteiras digitais, para ativar seus tokens.

  • Emissores para ativar tokens associados a cartões que emitiu.

Argumentos:

input: ActivateCardTokenInput obrigatório



Mutation que atualiza os dados de cartão do cartão fisico que esta associado ao Token.

Argumentos:

input: UpdateCardOriginToTokenInput obrigatório



Adiciona uma chave pública ao usuário

Em geral cada dispositivo ou servidor associado ao usuário deverá exportar uma chave pública a fim de poder enviar ou receber dados sensíveis, tais como CardInterface { sensitive(keyId: "X") }

As chaves devem possuir um identificador id único para o usuário e será fornecido como keyId para consultas ou mutações que utilizem a chave pública, por exemplo para assinaturas (JSON Web Signature - JWS) ou cifras (JSON Web Encryption - JWE).

As chaves associadas a um usuário estão disponíveis em publicKeys.

Argumentos:

input: AddPublicKeyToUserInput obrigatório



Cria um CardTokenForUser

Argumentos:

input: CreateCardTokenForUserInput obrigatório






Entrada para mutação createCardToken.

Isto resultará em CardTokenOrigin, porém nem todas as propriedades estarão especificadas: merchant: pego da informação de autenticação da requisição. timestamp: pego do sistema do servidor.

Campos:

ip

:

String

Endereços de rede IPv4 ou IPv6 de onde partiu a solicitação de criação.

Se for IPv6, deve estar entre colchetes. Exemplo: [::1] Se for IPv4, deve seguir a notação com pontos: 127.0.0.1


geolocation

:

GeolocationInput

Localização geográfica de onde partiu a solicitação de criação do token. Pode ser null.


device

:

DeviceInput

Dispositivo utilizado para a criação do token. Pode ser aproximado, por exemplo, usando o Agente de Usuário (User-Agent) para identificar sistema operacional, marca e modelo...


merchantUserId

:

String

Identificador de usuário no comércio que solicitou a criação do token.

Se foi criado pelo comerciante em nome do usuário, então é o identificador de usuário dentro do escopo do comerciante, como o ID de usuário, email, UUIDv4 ou URL que identifica o usuário de forma única e imutável no tempo (se o usuário puder mudar o email no sistema do comerciante, este não pode ser usado neste campo).


walletId

:

ID

Se estiver sendo executado pelo portador de cartões, então contém um identificador de carteira virtual.

Se estiver sendo executado como um comerciante, deve ser null e o campo merchantUserId deve ser preenchido.



Entrada de informações sobre como o cartão ou token podem ser usados.

Emissores, cartões e produtos podem impor restrições extras.

Campos:

maxUsage

:

Int

Número de vezes que o cartão pode ser usado.

-1 significa ilimitado null significa uso não definido.

Para o fluxo de tokenização E-Commerce o valor sempre será 1, independentemente se o valor for informado ou não.


expiry

:

DateTime

Uso é permitido até a data e horário de validade


allowedTxAmounts

:

list de CardCurrencyRangeInput obrigatório

Quantias permitidas por transações permitidas (TX) como limites por moedas.

Cada moeda será listada no máximo uma vez.

Nenhuma conversão de moedas é executada. Se uma moeda não é listada, é porque não é autorizada.

Se null, é ilimitada.


allowedIdCodes

:

list de ID obrigatório

Lista de comerciantes autorizados.

Se null, é ilimitada.


allowedMerchantCategories

:

list de MerchantCategoryRangeInput obrigatório

Série de categorias de comerciantes autorizadas, definidas por código ISO.

Se null, é ilimitada.


deniedMerchantCategories

:

list de MerchantCategoryRangeInput obrigatório

Série de categorias de comerciantes proibidas, definidas por código ISO.

Se null, é ilimitada.



Entrada para mutação createCardToken().

Informações sigilosas precisam ser transmitidas de forma criptografada utilizando-se a forma compacta JSON Web Encryption (JWE).

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


cardId

:

ID

O identificador global único do cartão.

Caso tenha acesso ao ID do cartão, utiliza-se preferencialmente este campo de modo a reduzir o tráfego de informações sensíveis.

Caso contrário pode-se utilizar o campo sensitive.

Exemplo: "3417E346-49A3-47A8-8196-37BBA09E27A5"


sensitive

:

String

Conteúdo sensível o qual foi assinado e então cifrado conforme a estrutura a seguir. Deve ser utilizado apenas se não tiver acesso ao identificador global único do cartão, neste caso deverá ser utilizado cardId.

Estrutura de assinatura e criptografia:

JWE.Encrypt(recipient=ServerKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact,
        JSON.Stringify(CardSensitiveInput)
    )
)

Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.

O esquema define as seguintes chaves para o objeto de entrada (CardSensitiveInput):

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

A autorização é feita com os campos csc ou authCode e seus respectivos horários de entrada. Note que apenas um deles deve ser especificado:

  • 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: 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"

  • authCode: Código de autorização. Este código não é o CSC (Código de Segurança do Cartão) pois não está impresso no cartão. Exemplo: "AB123Z1Y"

  • authCodeEntryTime: Data e horário quando o código de autorização (authCode) foi digitado. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"


origin

:

CreateCardTokenOriginInput

Informação extra sobre a origem da criação. Importante o preenchimento do máximo possível.


usageConstraints

:

CardUsageConstraintsInput

Restrições para o novo token.

O emissor, cartão e produto podem impor mais restrições. Sempre use restrições retornadas em CreateCardTokenPayload{ cardToken{ usageConstraints }}


tokenRequestorId

:

String obrigatório

Identificador do Token Requestor.



Entrada para mutação suspendCardToken().

Informações sigilosas precisam ser transmitidas de forma criptografada utilizando-se a forma compacta JSON Web Encryption (JWE).

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


cardTokenId

:

ID obrigatório

O identificador global único do token do cartão.


permanent

:

Boolean

Se true, a suspensão é definitiva. É false por padrão.


reason

:

CardSuspendReason obrigatório

Se não-nulo, define a razão da suspensão do token.

Se for pelo portador, deve ser CARDHOLDER ou null. Se for pelo comerciante, deve ser TOKEN_REQUESTOR ou null.



Entrada para mutação activateCardToken ().

Informações sensíveis precisam ser transmitidas de forma encriptada usando a forma compacta JSON Web Encryption.

Compatível com [Relay] (http://facebook.github.io/relay/docs/en/mutations.html)

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


cardTokenId

:

ID obrigatório

O identificador global único do token do cartão.



Entrada para os dados CardOriginToToken Responsável por atualiza as informações sensiveis do cartão fisico que esta associado ao Token.

Campos:

updateCardOriginId

:

ID obrigatório

Identificador único da atualização, informado pelo solicitante para controle de possíveis erros ao atualizar os cartões originais


sensitiveCurrent

:

String

Conteúdo sensível do cartão atual o qual foi assinado e então cifrado conforme a estrutura a seguir.

Estrutura de assinatura e criptografia:

JWE.Encrypt(recipient=ServerKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact,
        JSON.Stringify(CardSensitiveInput)
    )
)

Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.

O esquema define as seguintes chaves para o objeto de entrada (CardSensitiveInput):

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

  • expiry: (esse campo é obrigatório) 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: "Joao da Silva". (não utilizar caracteres especiais ou acentos)

A autorização é feita com os campos csc ou authCode e seus respectivos horários de entrada. Note que apenas um deles deve ser especificado:

  • 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: 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"

  • authCode: Código de autorização. Este código não é o CSC (Código de Segurança do Cartão) pois não está impresso no cartão. Exemplo: "AB123Z1Y"

  • authCodeEntryTime: Data e horário quando o código de autorização (authCode) foi digitado. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"


sensitiveNew

:

String obrigatório

Conteúdo sensível do novo cartão que irá substituir as informações do atual. Qual foi assinado e então cifrado conforme a estrutura a seguir.

Estrutura de assinatura e criptografia:

JWE.Encrypt(recipient=ServerKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact,
        JSON.Stringify(CardSensitiveInput)
    )
)

Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.

O esquema define as seguintes chaves para o objeto de entrada (CardSensitiveInput):

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

  • expiry: (esse campo é obrigatório) 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: "Joao da Silva". (não utilizar caracteres especiais ou acentos)

A autorização é feita com os campos csc ou authCode e seus respectivos horários de entrada. Note que apenas um deles deve ser especificado:

  • 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: 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"

  • authCode: Código de autorização. Este código não é o CSC (Código de Segurança do Cartão) pois não está impresso no cartão. Exemplo: "AB123Z1Y"

  • authCodeEntryTime: Data e horário quando o código de autorização (authCode) foi digitado. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"



Entrada para a mutação updateCardOriginToToken() Responsável por atualiza as informações sensiveis do cartão fisico que esta associado ao Token.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


cardOriginToTokens

:

lista obrigatória de CardOriginToTokenInput obrigatório


Entrada para mutação addPublicKeyToUser()

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


userId

:

ID obrigatório

Identificador global único do Usuário a adicionar chave pública


key

:

String obrigatório

Conteúdo da chave pública. O formato é especificado em format.

Caso a chave já esteja associada ao usuário ela não será adicionada novamente e a mutação retornará a publicKey já existente, com o mesmo id.


format

:

CryptoKeyFormat

Formato da chave key.

Se null, tenta descobrir à partir do conteúdo de key.



Entrada para mutação createProvisionedUser().

Nota: não existe um campo image a ser enviado, para tal utilize a mutação setImage().

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de ProvisionedUser opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


name

:

String

Nome completo do portador como nos documentos oficiais (RG, CPF)


legalIds

:

LegalIdsInput obrigatório

Todos os documentos legais de identificação do usuário.


birthday

:

Date

Data de nascimento


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncomeInput

Renda anual do usuário (individual e familiar).


occupationId

:

ID

Profissão do usuário.

Utilize valores já conhecidos e retornados na consulta personOccupations, membros id.

Enviar uma ocupação desconhecida irá resultar em erro.


contacts

:

list de PersonContactInput

Contatos do usuário


addresses

:

list de AddressInput

Endereços postais


originId

:

ID

Identificador único da origem da campanha


origin

:

String

Identifica a origem(campanha) do cadastro do usuário.


originUrl

:

String

Url de origem de cadastro do usuário


originChannelRaw

:

String

Parametros de web analytics brutos


originChannel

:

String

Campo tratado com os paramentros de mídia


localEvent

:

String

Cidade que estará recebendo o Show ou Evento


transaction

:

TransactionInput

Dados da transação


event

:

String

Identifica o evento do cadastro do usuário.


ticket

:

String

Identifica o ticket do cadastro do usuário.


motherName

:

String

Nome da mãe do usuário.



Entrada para mutação createCardTokenForUser().

Informações sigilosas precisam ser transmitidas de forma criptografada utilizando-se a forma compacta JSON Web Encryption (JWE).

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


sensitive

:

String

Conteúdo sensível o qual foi assinado e então cifrado conforme a estrutura a seguir. Deve ser utilizado apenas se não tiver acesso ao identificador global único do cartão, neste caso deverá ser utilizado cardId.

Estrutura de assinatura e criptografia:

JWE.Encrypt(recipient=ServerKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact,
        JSON.Stringify(CardSensitiveInput)
    )
)

Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.

O esquema define as seguintes chaves para o objeto de entrada (CardSensitiveInput):

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

A autorização é feita com os campos csc ou authCode e seus respectivos horários de entrada. Note que apenas um deles deve ser especificado:

  • 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: 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"

  • authCode: Código de autorização. Este código não é o CSC (Código de Segurança do Cartão) pois não está impresso no cartão. Exemplo: "AB123Z1Y"

  • authCodeEntryTime: Data e horário quando o código de autorização (authCode) foi digitado. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"


cipheredCardVerificationData

:

String

Conteúdo sensível o qual foi assinado e então cifrado conforme a estrutura a seguir. Pode ser utilizado em conjunto ao identificador global único do cartão, cardId, caso seja necessário validar o portador do cartão.

Estrutura de assinatura e criptografia:

JWE.Encrypt(recipient=ServerKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact, 
        CSC
    )
)

Ou seja, o CSC deve ser assinado utilizando JSON Web Signature (JWS) em formato compacto e então cifrado utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.

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


cardId

:

ID

O identificador global único do cartão.

Caso tenha acesso ao ID do cartão, utiliza-se preferencialmente este campo de modo a reduzir o tráfego de informações sensíveis.

Caso contrário pode-se utilizar o campo sensitive.

Exemplo: "3417E346-49A3-47A8-8196-37BBA09E27A5"


user

:

CreateProvisionedUserInput

Usuário ProvisionedUser. Esse pode no futuro se tormar um usuário na API de Portador.


origin

:

CreateCardTokenOriginInput

Informação extra sobre a origem da criação. Importante o preenchimento do máximo possível.


usageConstraints

:

CardUsageConstraintsInput

Restrições para o novo token.

O emissor, cartão e produto podem impor mais restrições. Sempre use restrições retornadas em CreateCardTokenPayload{ cardToken{ usageConstraints }}


tokenRequestorId

:

String obrigatório

Identificador do Token Requestor.






Campos:

key

:

String obrigatório


Token de Cartão: identificador opaco que substitui o cartão real e suas informações sigilosas.

Tokens podem ser criados pelo portador do cartão utilizando uma carteira digital, ou um comerciante que o utiliza ao invés de um cartão, para reduzir as informações sigilosas armazenadas em seus servidores.

Tokens (CardToken) implementam a mesma interface que o cartão (Card), (CardInterface) e pode ser usado como tal em outras chamadas, porém possui membros extras, como origin, que declara como, quando e porque foi criado.

Campos:

id

:

ID obrigatório

sensitive

(


keyId:

String

)

:

String

last4

:

String

expiry

:

CardExpiry

holder

:

CardHolder

billingAddress

:

Address

status

:

CardStatusInterface obrigatório

usageConstraints

:

CardUsageConstraints

availableServices

:

list de CardHolderService obrigatório

usedServices

:

list de CardHolderService obrigatório

bin

:

BIN

funding

:

CardFunding

product

:

CardProduct

isInternational

:

Boolean

isCompany

:

Boolean

isToken

:

Boolean

brand

:

CardBrand

allowedCaptures

:

list de CardCapture obrigatório

usages

:

list de CardUsage obrigatório

network

:

CardNetwork

issuer

:

CardIssuer

metadata

:

CardMetadata

transactions

(


first:

Int

Limita a lista às primeiras entradas, caso provido. Se for null, a listagem é ilimitada. Utilizado em navegação para frente.

after:

String

Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.

last:

Int

Limita a lista às últimas entradas, caso provido. Se for null, a listagem é ilimitada. Utilizado em navegação para trás.

before:

String

Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.

filter:

CardTransactionFilterInput

Aplica filtro, se provido.

)

:

CardTransactionsConnection

transactionsSummary

(


filter:

CardTransactionSummaryFilterInput

Aplica filtro, se provido.

)

:

list de CardTransactionCategorySummary obrigatório

card

:

Card

O cartão real a que se refere o token.

Se refere as informações do cartão, utilizadas na tokenização realizado por um usuário (cardHolder).

Atenção: estas queries em dados sigilosos do cartão, normalmente retornarão null a não ser que permissões autorizem seu acesso.


cardOrigin

:

CardOrigin

O cartão real a que se refere o token.

Se refere as informações do cartão, utilizadas na tokenização para um usuário (mutation forUser).

Atenção: estas queries em dados sigilosos do cartão, normalmente retornarão null a não ser que permissões autorizem seu acesso.


origin

:

CardTokenOrigin

Informação sobre a origem do token: como, quando e porque foi criado.


tokenRequestorId

:

String

Identificador do Token Requestor.



Retorno da mutação createCardToken().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

O token criado, seu PAN e CSC (Código de Segurança) são retornados usando seu membro sensitive.



Retorno da mutação suspendCardToken().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

O token suspenso ou null caso nenhum tenha sido.



Retorno da mutação activateCardToken().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

O token ativado ou null caso nenhum tenha sido (ver error)



Retorno dos dados de CardOriginToToken()

Campos:

statusUpdate

:

UpdateStatus

Status da atualização


updateCardOriginId

:

ID

Identificador único da atualização, informado pelo solicitante para controle de possíveis erros ao atualizar os cartões originais


bin

:

BIN

O BIN (Bank Identification Number) referente ao cartão


last4

:

String

Últimos 4 dígitos do cartão, para ser mostrado ao usuário


errorDescription

:

String

Caso houver erro na atualização, aqui será retornado uma mensagem contendo o problema de falha da atualização



Retorno da mutação updateCardOriginToToken()

Compatível com Relay.

Campos:

clientMutationId

:

String

cardOriginToTokens

:



Usuário do Sistema

O usuário pode ser associado a um comerciante, emissor de cartões ou pode ser um portador de cartões.

Também são listadas as redes sociais que o usuário relacionou e autorizou, por exemplo via OAuth.

API Privada

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


verified

:

VerifiedStatus

O usuário foi verificado por meio de uma rede social, email, SMS ou outro meio.

É o mesmo que conferir todos os contatos do usuário e constatar que ao menos um deles foi verificado (contacts { verified }).


username

:

String

Nome do usuário para acesso ao sistema


name

:

String

Nome completo do portador como nos documentos oficiais (RG, CPF)


firstName

:

String

Primeiro nome do usuário


lastName

:

String

Último nome do usuário


displayName

:

String

Nome de usuário a ser exibido (exemplo: encurtado, alias...)


legalIds

:

LegalIds

Todos os documentos legais de identificação do usuário.


birthday

:

Date

Data de nascimento


age

:

Int

Idade em anos


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncome

Renda anual do usuário (individual e familiar).


occupation

(


language:

String

Língua a ser utilizada no retorno da consulta.

Por padrão adota-se a língua de quem faz a requisição, porém uma diferente pode ser requisitada e está será utilizada, ou a mais próxima disponível. O formato é: en_US (Inglês dos EUA), en (Inglês genérico), pt_BR (Português do Brasil), pt (Português genérico). O formato é o mesmo de IETF language tag.

)

:

PersonOccupation

Profissão do usuário.

Por padrão adota-se a língua de quem faz a requisição, porém uma diferente pode ser requisitada e está será utilizada, ou a mais próxima disponível. O formato é: en_US (Inglês dos EUA), en (Inglês genérico), pt_BR (Português do Brasil), pt (Português genérico). O formato é o mesmo de IETF language tag.


image

(


width:

Int

Caso fornecido, largura da imagem, em pixels.

height:

Int

Caso fornecido, altura da imagem, em pixels.

mimeType:

String

Caso fornecido, o tipo de arquivo desejado (mime-type).

)

:

ImageUrl

URL para foto de perfil. Caso sejam providos sugestões de altura e largura (opcionais) para o tamanho a ser mostrado, o servidor irá retornar a URL para a imagem com o tamanho mais próximo ao requisitado. Caso seja provido o mimeType, a este será dada preferência, o que é muito útil em dispositivos que lidam com um único formato de imagens. Tanto o tamanho quanto o mimeType da imagem apontada pela URL são retornados.


contacts

:

list de PersonContact obrigatório

Contatos do usuário


addresses

:

list de Address obrigatório

Endereços postais


cardHolders

:

list de CardHolder obrigatório

Portadores de cartões associados ao usuário

Um usuário pode ter mais de um portador associado no caso de pessoas jurídicas diferentes, bem como um portador para sua pessoa física.

Relação: 1:n


merchants

:

list de Merchant obrigatório

Comerciantes associados ao usuário

Um usuário pode ser responsável por vários comerciantes. Um comerciante pode ter vários usuários responsáveis.

Relação: n:n


cardIssuers

:

list de CardIssuer obrigatório

Emissores de cartões associados ao usuário

Um emissor pode ter vários usuários responsáveis. Em geral um usuário vai ser responsável por apenas um emissor. No entanto está modelado como sendo possível que o usuário seja responsável por vários emissores (evita que a API mude caso este caso se torne realidade).

Relação: n:n


socialNetworks

:

list de SocialNetwork obrigatório

Redes sociais relacionadas ao usuário


agreements

:

list de UserAgreement obrigatório

Termos de uso aceitos pelo usuário


accessTokens

:

list de AccessTokenInfo obrigatório

Lista de chaves de acesso ativas para este usuário


publicKeys

:

list de PublicKey obrigatório

Lista de Chaves Públicas conhecidas para este usuário


originId

:

ID

Identificador único da origem da campanha


origin

:

String

Identifica a origem(campanha) do cadastro do usuário.


analyticsId

:

ID obrigatório

Identificador Global Único para este objeto


acquirer

:

Acquirer

validation

:

UserValidation obrigatório

Informações da validação dos dados do usuário


motherName

:

String

Nome da mãe do usuário.


promotions

(


limit:

Int obrigatório

Limita o número de items a serem retornados nesta query.

offset:

Int obrigatório

Retorna os items a partir da posição definida.

filter:

UserPromotionsFilterInput

Aplica filtro, se provido.

)

:

UserPromotionsPage

communicationChannels

:

list de String obrigatório

Canais de comunicação escolhidos pelo usuário.



Campos:

id

:

String obrigatório

Identificador da chave para este usuário.

Em operações que retornem dados cifrados este será o identificador da chave a ser especificado, como na consulta CardInterface { sensitive(keyId: "X") }

Este identificador é gerado no momento que a chave é adicionada, vide addPublicKeyToUser()

NOTA: tem escopo do usuário, não é global do sistema.


key

:

String obrigatório

A chave serializada no formato requerido.

Se nenhum formato for especificado, será retornada como JSON Web Key - JWK



Retorno da mutação addPublicKeyToUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual teve chave adicionada.


publicKey

:

PublicKey

A chave adicionada.

Note que o campo publicKey { id } contém o identificador da chave a ser utilizado em outras operações como removePublicKeyFromUser(keyId: "X") ou CardInterface { sensistive(keyId: "X") }



Retorno da mutação createCardTokenForUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

O token criado, seu PAN e CSC (Código de Segurança) são retornados usando seu membro sensitive.






Node compatível com Relay.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto





A razão da suspensão do cartão.

O cartão pode ser suspenso pelo emissor, portador ou devido a tentativas incorretas de PIN.

Se o cartão é um token, o solicitante (exemplo: comerciante) pode ter suspendido o mesmo.


Valores possíveis:


ISSUER

Emissor solicitou a suspensão


CARDHOLDER

Portador solicitou a suspensão


PIN_LOCKED

Cartão suspenso devido a inúmeras tentativas incorretas de PIN


TOKEN_REQUESTOR

Caso seja um token, o solicitante (i.e.: comerciante) solicitou a suspensão




Formato de Chave criptográfica a ser serializada ou interpretada.


Valores possíveis:


PEM

Privacy Enhanced Mail PEM


X509

Certificado X.509