Tokenização

Permite substituir os dados de 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

O cartão físico que conhecemos, também referido como "cartão real", é composto pelo número (PAN - Primary Account Number), um código de segurança (CSC - Card Security Code) e data de validade. Com apenas estes dados é possível realizar compras e caso estes dados sejam copiados, podem gerar prejuízo ao portador, ao comerciante ou aos emissores.

Com o aumento das fraudes, criou-se o conceito de Token, que se comporta como um cartão virtual, na maioria das vezes tem um número (PAN), código de segurança (CSC) e data de validade que podem ser utilizados em sistemas legados de forma transparente. Com uma grande diferença: o Token pode ser parametrizado e ter um escopo de atuação reduzido, consequentemente eliminando ou reduzindo o potencial de fraudes.

Por exemplo, podemos Tokenizar (criar um Token) para um cartão real e especificar restrições de uso CardUsageConstraints:

  • Número de usos permitido. Por exemplo, maxUsage: 1 para um token que só pode ser utilizado uma única vez.

  • Data de expiração. Por exemplo, expiry: 2017-10-01 limita o uso do token a uma data específica, que pode ser diferente da validade do cartão real.

  • Limites de transação por moeda. Por exemplo, allowedTxAmount: [{currency: "USD", max: 100}] limitaria o token a transacionar no máximo USD$100.

  • Restrição de Comerciantes. Por exemplo, allowedIdCodes:[123, 456] permite o token ser utilizado em apenas dois lojistas, com identificadores 123 e 456.

  • Restrição de Categorias de Comerciantes. Por exemplo, allowedMerchantCategories para limitar o uso a apenas algumas categorias de comerciantes e deniedMerchantCategories para proibir categorias.

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): integram com seus aplicativos e permitem o portador criar um Token, como para uso em lojas virtuais na qual o portador não confia;

  • Portadores: aplicativo da própria Elo ou terceiros poderiam criar Tokens para serem usados em compras. Um exemplo são aplicativos que fazem transações via NFC, Bluetooth ou QRCode, ao invés de divulgarem os dados do cartão real criam um token com escopo reduzido para o propósito da transação;

  • Comerciantes: ao invés de guardarem dados sensíveis do usuário em suas bases de dados, tornando-se alvo de hackers, 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.

Para melhor segurança os dados sensíveis (PAN, CSC 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 da seguinte forma (pseudo código):

JWE.Encrypt(recipient=ChaveDoServidor, format=compact,
    JWS.Sign(issuer=ChaveDoUsuario, format=compact,
        JSON.Stringify(DadosSensiveis)
    )
)

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 (ChaveDoServidor) esta disponível a partir da consulta abaixo:

query {
    serverPublicKey {
        key
    }
}

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

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.

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

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.

NOTA: Se você não possui o cardId do cartão cadastrado, é preciso consultá-lo ou cadastrá-lo utilizando a mutation createCard.

mutation {
    createCardToken(input: {
        cardId: "fd5c9b0a-5d2d-4b9a-957e-62c2415c0a0c", # se foi retornado anteriormente
        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: { maxUsage: 1, 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 }
            # ...
        }
    }
}

Caso queira criar um cardToken a partir do sensitive de um cartão utilize o campo sensitive na mesma mutation createCardToken:

mutation {
    createCardToken(input: {
        sensitive: "<dados sensiveis criptografados>",
        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: { maxUsage: 1, 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 }
            # ...
        }
    }
}

Usuários CardIssuers ou Merchants muitas vezes precisam tokenizar cartões de outros usuários.
Para isto é possível utilizar a mutation CreateCardTokenForUser demonstrada a seguir:

mutation {
    createCardTokenForUser(input: {
        sensitive: "<dados sensiveis criptografados>",
        # Id do usuário CardIssuer ou Merchant querendo tokenizar cartão em nome de outro usuário
        userId: "81aae8ed-4d9f-3677-9957-5beb821e1b1d",         
        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: { maxUsage: 1, 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 }
            # ...
        }
    }
}

Esta mutation se difere das mutations acima em apenas dois campos:

  • userId identificador do usuário card issuer ou merchant que está tokenizando o cartão

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

Caso o Token não seja mais necessário ou tenha sido comprometido, deve-se suspendê-lo:

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

Um Token suspendido com a mutation acima pode ser ativado novamente:

mutation{
  activateCardToken(input:{
    clientMutationId: "123",
    cardTokenId: "c7d555e0-b86e-4994-9ee9-79891d42cb05"
    sensitive: "...dados sensíveis cifrados...", # se não tiver cardTokenId
  })
  {
    cardToken { id }
  }
}

NOTA: para suspendCardToken e activateCardToken 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!

Quando se cria ou atualiza um token, pode ser preciso atualizar o cartão original, quando, por exemplo, se tem uma extensão do período de validade, pois o Emissor valida os dados do cartão original quando se utiliza o token.

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"
    sensitiveCurrent: "<dados sensiveis criptografados>"
    sensitiveNew: "<dados sensiveis criptografados>"
  }) {
    clientMutationId
    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. É preferível, no entanto que se use sempre que possível, o cardId desse cartão, que é um identificador global único que referencia os dados, para evitar o tráfego de dados sensíveis via rede:

mutation {
  updateCardOriginToToken(input: {
    clientMutationId: "123"
    cardId: "78a9e2ed-3249-49bb-b763-4879d7ad9439"
    sensitiveNew: "<dados sensiveis criptografados>"
  }) {
    clientMutationId
    bin {
      number
    }
    last4
  }
}



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.


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



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


origin

:

String

Identifica a origem(campanhã) do cadastro 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 obrigatório

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"


user

:

CreateProvisionedUserInput obrigatório

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






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.

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.



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


origin

:

String

Identifica a origem(campanhã) do cadastro do usuário.


analyticsId

:

ID obrigatório

Identificador Global Único para este objeto


acquirer

:

Acquirer


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