01
Primeiros passos
02
CardToken - Token de Cartão, ou Cartão Virtual
03
Trafegando dados sensíveis
04
criação de um usuário
05
Criando um Token
06
Criando um Token para um usuário
07
Suspendendo Tokens
08
Ativando Tokens
09
Atualizando Cartões
10
Referências
- Queries
- Mutations
- Tipos de Entrada
- Tipos
- Interfaces
- Enumerações

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

Leia Introdução ao GraphQL, com exemplos reais da nossa API.
Crie um usuário no portal do desenvolvedor.
Cadastre sua primeira aplicação.
Utilize o dashboard para acessar suas configurações de acesso.
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



CardToken - Token de Cartão, ou Cartão Virtual

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.



Trafegando dados sensíveis

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



Primeiro passo: criação de um usuário

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.



Criando um Token

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



Criando um Token para um usuário

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



Suspendendo Tokens

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



Ativando Tokens

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!



Atualizando Cartões

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



Referências



Queries



node

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.



serverPublicKey

Argumentos:



Mutations



createCardToken

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



suspendCardToken

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



activateCardToken

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



updateCardOriginToToken

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

Argumentos:

input: UpdateCardOriginToTokenInput obrigatório



addPublicKeyToUser

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



createCardTokenForUser

Cria um CardTokenForUser

Argumentos:

input: CreateCardTokenForUserInput obrigatório



Tipos de Entrada



CreateCardTokenOriginInput

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:

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.



CardUsageConstraintsInput

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.



CreateCardTokenInput

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



SuspendCardTokenInput

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.



ActivateCardTokenInput

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.



CardOriginToTokenInput

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

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

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"



UpdateCardOriginToTokenInput

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



AddPublicKeyToUserInput

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.



CreateProvisionedUserInput

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.



CreateCardTokenForUserInput

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

Estrutura de assinatura e criptografia:

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

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



Tipos



ServerPublicKey

Campos:

key

String obrigatório



CardToken

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



CreateCardTokenPayload

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.



SuspendCardTokenPayload

Retorno da mutação suspendCardToken().

Compatível com Relay.

Campos:

clientMutationId

String

cardToken

CardToken

O token suspenso ou null caso nenhum tenha sido.



ActivateCardTokenPayload

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)



CardOriginToToken

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



UpdateCardOriginToTokenPayload

Retorno da mutação updateCardOriginToToken()

Compatível com Relay.

Campos:

clientMutationId

String

cardOriginToTokens

list de CardOriginToToken



User

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

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



PublicKey

Campos:

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



AddPublicKeyToUserPayload

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

