Tokenização

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

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

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 somente estes dados é possível realizar compra e caso estes dados sejam copiados, podem gerar prejuízo ao portador, comerciante ou 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 allowedMerchants:[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, por exemplo 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 { allowedMerchants: [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) estará disponível no sistema para consulta.

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. (API ainda privada addPublicKeyToUser() ).

Criando um Token

Para criar um token você precisa de um identificador global único de cartão (cardId, obtido de Card { id }) ou dos dados sensíveis do cartão (PAN, CSC e data de validade) assinados e cifrados conforme a seção anterior. Então executa-se a mutação createCardToken():

mutation {
 createCardToken(input: {
  "sensitive": "...dados sensíveis cifrados...", # ou null, se não tiver
  "cardId": "9903BD7E-186F-4C56-BC75-FBEAF155FED7", # 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, "allowedMerchants": ["123"] }
 })
 {
  cardToken { # Token retornado, deve ser salvo pois não pode ser consultado!
     id # para poder suspender
     sensitive(keyId: "id-minha-chave-pgp") # para obter PAN, CSC e validade
  }
 }

NOTA: keyId deve ser o campo id de uma chave previamente cadastrada para o usuário.

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
 }) { id }
}

NOTA: para suspendCardToken() os dados sensíveis e o identificador global único são references ao Token e não ao cartão real o qual foi utilizado em createCardToken()!

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

Parâmetros de entrada

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

Parâmetros de saída

id (ID!) Identificador Global Único para este objeto

activateCardToken(ActivateCardTokenPayload!)

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.

Parâmetros de entrada

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 (String) O identificador global único do token do cartão.

Caso tenha acesso ao ID do token 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 token do cartão, neste caso deverá ser utilizado cardTokenId.

Estrutura de assinatura e criptografia:

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

Ou seja, os dados conforme o esquema JSON CardTokenSensitiveInput 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 (CardTokenSensitiveInput):

  • pan: O número da conta primária (Primary Account Number), também conhecido como \"número do cartão\" virtual (Virtual Card Number - VCN). Exemplo: "1234567890123456"
  • expiry: Data de validade do token 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 token do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).
    • year: Ano da validade do token 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 token do cartão (Card Security Code), usualmente retornado na mutação createCardToken() no campo sensitive.

  • 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 e não é retornado em createCardToken(). 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"

    JSON Schema: CardTokenSensitiveInput.json

Parâmetros de saída

clientMutationId (String)

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

createCardToken(CreateCardTokenPayload!)

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.

Parâmetros de entrada

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 (String) 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"

    JSON Schema: CardSensitiveInput.json

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

Parâmetros de saída

clientMutationId (String)

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

suspendCardToken(SuspendCardTokenPayload!)

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.

Parâmetros de entrada

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 (String) O identificador global único do token do cartão.

Caso tenha acesso ao ID do token 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 token do cartão, neste caso deverá ser utilizado cardTokenId.

Estrutura de assinatura e criptografia:

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

Ou seja, os dados conforme o esquema JSON CardTokenSensitiveInput 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 (CardTokenSensitiveInput):

  • pan: O número da conta primária (Primary Account Number), também conhecido como \"número do cartão\" virtual (Virtual Card Number - VCN). Exemplo: "1234567890123456"
  • expiry: Data de validade do token 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 token do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).
    • year: Ano da validade do token 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 token do cartão (Card Security Code), usualmente retornado na mutação createCardToken() no campo sensitive.

  • 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 e não é retornado em createCardToken(). 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"

    JSON Schema: CardTokenSensitiveInput.json

permanent (Boolean) Se true, a suspensão é definitiva. É false por padrão.

reason (CardSuspendReason) 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.

Parâmetros de saída

clientMutationId (String)

cardToken (CardToken) O token suspenso ou null caso nenhum tenha sido.

ActivateCardTokenPayload

Retorno da mutação activateCardToken().

Compatível com Relay.

Parâmetros de entrada

clientMutationId (String)

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

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.

Parâmetros de entrada

id (ID!)

sensitive (String)

last4 (String)

expiry (CardExpiry)

holder (CardHolder)

billingAddress (Address)

status (CardStatusInterface!)

usageConstraints (CardUsageConstraints)

availableServices ([CardHolderService])

usedServices ([CardHolderService])

bin (BIN)

funding (CardFunding)

product (CardProduct)

isInternational (Boolean)

isCompany (Boolean)

isToken (Boolean)

brand (CardBrand)

allowedCaptures ([CardCapture])

usages ([CardUsage])

network (CardNetwork)

issuer (CardIssuer)

metadata (CardMetadata)

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.

CardExpiry

Validade do cartão: Mês e Ano

Parâmetros de entrada

month (Int!) Mês - Janeiro é 1, Dezembro é 12

year (Int!) Ano - 4 dígitos, exemplo: 2017, não 17.

CardHolder

Portador de cartão

Usualmente uma pessoa

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

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

firstName (String) Primeiro nome do portador

lastName (String) Último nome do portador

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

companyName (String) Nome da empresa.

Para cartões corporativos (pessoa jurídica), este campo informa o nome fantasia da empresa. Para a razão social, veja companyLegalName.

Para cartões de pessoa física será sempre null.

companyLegalName (String) Nome legal da empresa, como escrito em documentos.

Para cartões corporativos (pessoa jurídica), este campo informa a razão social da empresa. Para nome fantasia, veja companyName

Para cartões de pessoa física será sempre null.

legalIds (LegalIds) Todos os documentos legais de identificação de empresas ou pessoas.

birthday (Date) Data de nascimento

age (Int) Idade em anos

gender (Gender) Masculino ou Feminino, conforme documentos oficiais

maritalStatus (MaritalStatus) Estado civil

image (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 ([PersonContact]) Contatos do portador de cartão

addresses ([Address]) Endereço postal

wallets ([Wallet]) Carteiras em posse deste portador de cartão.

cards (CardsConnection) Cartões em posse.

Lista todos os cartões de um portador utilizando paginação e um filtro opcional.

Note que nem todos os campos de um cartão serão retornados pois estes têm privacidade restrita ao portador, emissor ou demais entidades autorizadas pela plataforma.

Opcionalmente pode-se utilizar o filter para selecionar apenas cartões de um certo emissor, produto, que oferece algum serviço ou que tenha alguma restrição de uso.

LegalIds

Toda a possível identificação legal de uma pessoa ou empresa

Parâmetros de entrada

cnpj (CNPJ)

cpf (CPF)

rg (RG)

CNPJ

CNPJ: Cadastro Nacional Pessoas Jurídicas

Parâmetros de entrada

number (String!) número do CNPJ (dígitos) sem hífen ou pontos.

CPF

CPF: Cadastro Pessoa Física

Parâmetros de entrada

number (String!) número do CPF (dígitos) sem hífen ou pontos.

RG

RG: documento de Registro Geral

Parâmetros de entrada

number (String!) número do RG (dígitos) sem hífen ou pontos.

issuerOrganization (String) organização emissora do documento (exemplo: SSP)

issuerState (String) estado de emissão do documento (exemplo: SP)

issueDate (Date) data de emissão do documento

ImageUrl

URL de imagem com tamanho e mimeType.

Parâmetros de entrada

url (String!) URL para acessar a imagem

width (Int!) largura em pixels

height (Int!) altura em pixels

mimeType (String!) Tipo do arquivo na convenção (MIME - Multipurpose Internet Mail Extensions), como image/png, image/jpeg

PersonContact

Ítem de contato com pessoa física, como email ou telefone...

Com o intuito de manter a privacidade, o campo value pode ser mascarado.

Parâmetros de entrada

type (PersonContactType!) Tipo designa como interpretar o valor, podendo ser telefone, email, ou aplicativo de mensagens instantâneas.

context (String) Contexto do contato, que varia com o tipo:

  • Se o tipo for PHONE ou EMAIL, este poderia ser: vendas, suporte ...
  • Se o tipo for IM, pode ser: skype, whatsapp, facebook messenger...
  • Se for OTHER, pode ser qualquer texto

value (String!) Valor do contato. Exemplos: +12345678 para telefone, user@server.com para email, etc.

Este campo pode ser transformado dependendo de regras de acesso e permissões. Um comerciante pode receber valores mascarados com o intuito de manter a privacidade da pessoa física. Um exemplo seria receber apenas os últimos 4 dígitos do telefone, ou apenas as primeiras letras do email seguida do domínio.

verified (VerifiedStatus) O processo de verificação é feito por nosso sistema enviando uma mensagem ao contato e então pedindo que a chave enviada seja reenviada ao sistema.

NOTA: apenas os tipos de contatos PHONE e EMAIL são verificáveis. Os demais retornarão sempre NOT_APPLICABLE.

Address

Endereço Físico Mundial, que pode ser usado para envios ou contas

Parâmetros de entrada

context (String) Contexto do endereço, por exemplo: Casa, Trabalho, Matriz, Filial

Análogo a campo de mesmo nome em PersonContact e CompanyContact.

country (String!) Código do país com 3 letras (ISO3166-alpha3). Exemplos: USA, BRA...

city (String!) Nome da cidade em UTF-8

state (String!) Nome do estado por completo ou abreviado (opcional).

Abreviações de estados podem não estar disponíveis para alguns países, casos em que o nome por completo é retornado.

zip (String!) Código postal obrigatório

district (String) Distrito opcional

kind (String) O tipo deve ser Av. (Avenida), R. (Rua), Rd. (Rodovia)...

number (Int) Número da construção

place (String!) Nome da via, para ser usado em conjunto com kind e number, compondo a primeira linha de endereço.

complement (String) Complemento opcional, como número de apartamento.

reference (String) Ponto de referência (exemplo: próximo ao posto)

instructions (String) Instruções (exemplo: autorização do receptor)

lon (Float) Longitude, opcional: em graus.

Contém a longitude caso seja manualmente provido ou automaticamente descoberto à partir do endereço. Caso não seja possível prover, será null.

lat (Float) Latitude, opcional: em graus.

Contém a latitude caso seja manualmente provido ou automaticamente descoberto à partir do endereço. Caso não seja possível prover, será null.

Wallet

Carteira digital (Digital Wallet)

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome da carteira

holder (CardHolder!) Nome e contato do portador

cards (CardsConnection) Consulta todos os cartões disponíveis no contexto.

Se executado por um portador de cartão, então retorna todos os cartões contidos na carteira.

Caso contrário, se requisitado por emissores ou comerciantes, produz um erro.

CardsConnection

Conexão de Card em conformidade com o Relay.

Parâmetros de entrada

pageInfo (PageInfo!) Cursor opaco para ser usado com queries (consultas) after ou before.

edges ([CardsEdge]) Lista de arestas que compõem esta conexão.

totalCount (Int) Contagem total de objetos nesta conexão.

Arestas são limitadas a cursores before e after, assim como primeiras e últimas contagens. Assim o tamanho de arestas é possivelmente menor que a conexão como um todo.

totalCount, se não for null, indica o número total de itens na conexão considerando-se o filtro.

PageInfo

PageInfo compatível com Relay.

Parâmetros de entrada

hasPreviousPage (Boolean!)

hasNextPage (Boolean!)

startCursor (String)

endCursor (String)

CardsEdge

Aresta de conexão contendo um Card em conformidade com o Relay.

Parâmetros de entrada

cursor (String!) Cursor opaco para ser usado com queries (consultas) after ou before.

node (Card) O objeto Card que compõe essa aresta conexão.

Card

Um cartão de crédito ou débito.

Ver CardToken com relação a tokens.

Parâmetros de entrada

id (ID!)

sensitive (String)

last4 (String)

expiry (CardExpiry)

holder (CardHolder)

billingAddress (Address)

status (CardStatusInterface!)

usageConstraints (CardUsageConstraints)

availableServices ([CardHolderService])

usedServices ([CardHolderService])

bin (BIN)

funding (CardFunding)

product (CardProduct)

isInternational (Boolean)

isCompany (Boolean)

isToken (Boolean)

brand (CardBrand)

allowedCaptures ([CardCapture])

usages ([CardUsage])

network (CardNetwork)

issuer (CardIssuer)

metadata (CardMetadata)

CardUsageConstraints

Informações sobre como o cartão ou token podem ser usados.

Observe que as restrições do cartão ou token podem ser especificadas no momento de criação usando CardUsageConstraintsInput. Emissores, cartões e produtos podem impor restrições extras.

Parâmetros de entrada

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 ([CardCurrencyRange]) 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.

allowedMerchants ([Merchant]) Lista de comerciantes autorizados.

Se null, é ilimitada.

allowedMerchantCategories ([MerchantCategory]) Categorias de comerciantes autorizadas.

Se null, é ilimitada.

Se não-nula, então é a lista completa de categorias permitidas após aplicar filtros definidos por solicitantes, emissor e restrições de produto.

deniedMerchantCategories ([MerchantCategory]) Categorias de comerciantes proibidas.

Se null, é ilimitada.

Se não-nula, então é a lista completa de categorias proibidas após aplicar filtros definidos por solicitantes, emissor e restrições de produto.

CardCurrencyRange

Declara limites operacionais para uma moeda.

Parâmetros de entrada

currency (String!) Código da moeda com 3 letras (ISO4217) Exemplo: EUR, USD, BRL...

min (Float) Valor mínimo ou null para ilimitado.

max (Float) Valor máximo ou null para ilimitado.

Merchant

Entidade de comerciantes.

Parâmetros de entrada

id (ID!)

name (String!)

legalName (String!)

description (String)

image (ImageUrl)

legalIds (CompanyLegalIds!)

contacts (CompanyContact!)

addresses (Address!)

url (String)

categories (MerchantCategory!) Categorias de comerciantes (Código ISO, nome)

CompanyLegalIds

Toda a possível identificação legal de uma empresa.

Parâmetros de entrada

cnpj (CNPJ)

CompanyContact

Ítem de contato com a empresa, como email ou telefone...

Parâmetros de entrada

type (CompanyContactType!) Tipo designa como interpretar o valor, podendo ser telefone, email, ou aplicativo de mensagens instantâneas.

context (String) Contexto do contato, que varia com o tipo:

  • Se o tipo for PHONE ou EMAIL, este poderia ser: vendas, suporte ...
  • Se o tipo for IM, pode ser: skype, whatsapp, facebook messenger...
  • Se for OTHER, pode ser qualquer texto

value (String!) Valor do contato. Exemplos: +12345678 para telefone, user@server.com para email, etc.

MerchantCategory

Categoria de comerciantes

A Categoria de Comerciante é associada a um código ISO18245 de 4 dígitos disponível no membro iso.

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto.

iso (Int!) Código ISO18245.

Também conhecido como MCC (Merchant Category Code), tem 4 dígitos.

name (String!) Nome da categoria de comerciante.

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 (ImageUrl) URL da imagem. 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.

merchants (MerchantsConnection) Consulta comerciantes (Merchant) nesta categoria.

MerchantsConnection

Conexão de comerciante (Merchant) em conformidade com o Relay.

Parâmetros de entrada

pageInfo (PageInfo!) Cursor opaco para ser usado com queries (consultas) after ou before.

edges ([MerchantsEdge]) Lista de arestas que compõem esta conexão.

totalCount (Int) Contagem total de objetos nesta conexão.

Arestas são limitadas a cursores before e after, assim como primeiras e últimas contagens. Assim o tamanho de arestas é possivelmente menor que a conexão como um todo.

totalCount, se não for null, indica o número total de itens na conexão considerando-se o filtro.

MerchantsEdge

Aresta de conexão contendo um comerciante (Merchant) em conformidade com o Relay.

Parâmetros de entrada

cursor (String!) Cursor opaco para ser usado com queries (consultas) after ou before.

node (Merchant) O objeto Merchant que compõe essa aresta de conexão.

CardHolderService

Serviço disponível ao portador do cartão.

A Elo oferece aos portadores serviços como acesso à internet, estes são representados por este tipo.

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome do serviço

description (String) Descrição do serviço

image (ImageUrl) URL da imagem. 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.

url (String) URL do serviço

BIN

Representa um BIN (Bank Identification Number ou Número de Identificação do Banco) no sistema.

O BIN é relativo aos números iniciais de um cartão e identifica o emissor e produtos associados ao mesmo.

Cada bandeira tem faixas de BIN reservadas a seu uso, estas estão disponíveis como reserved na consulta binTable.

Porém o maior interesse é por BIN em uso (alocados), o qual carregará informações sobre o emissor (banco), financiamento (funding, se crédito, débito ou ambos), produtos (pagamentos à prazo, pré-pago, Cartão para construção civil - Construcard...) e mesmo serviços como emissão de seguros ou acesso à WiFi.

A tabela de BIN é dinâmica:

  • Conforme os cartões de um mesmo prefixo (BIN) vão sendo inutilizados e ficam sem usuários, o BIN pode ser então reciclado para um novo uso.

  • Conforme novos produtos são inseridos, um BIN previamente reservado e sem usuários será então alocado, entrando em uso.

    Por isso é importante manter a tabela de BIN atualizada, vide consulta binTable. Para saber se a tabela foi atualizada utilize os campos de nome similares ao HTTP lastModified (data e horário da última modificação) e etag (entity tag ou etiqueta da entidade), que oferece um identificador único sobre a tabela, se ele mudou então a tabela mudou.

Parâmetros de entrada

number (String!)

panSizeRange (IntRange!)

funding (CardFunding!)

product (CardProduct!)

country (String!)

isInternational (Boolean!)

regexp (String!)

isCompany (Boolean!) Diz se o cartão é corporativo (pessoa jurídica) ou pessoa física.

Se true, então o cartão é corporativo, ou seja, pessoa jurídica. Se false, então o cartão é para pessoas físicas.

isToken (Boolean!) Diz se o cartão é virtual (token, vide CardToken).

Tokens são muitas vezes compreendidos como "cartões virtuais" (VCN - Virtual Card Numbers), eles são associados a um cartão real e podem ter maior controle, como restrição de moeda, número de compras, valor das compras, categoria de comerciante e outros.

O maior uso de tokens é para reduzir problemas com segurança, seja de um comerciante ou portador.

Para maior informação, veja API: createCardToken().

Se true, então este BIN é utilizado para tokens ao invés de cartões físicos (plástico). Se false então este BIN é utilizado para cartões tradicionais, físicos (plástico).

brand (CardBrand!) Bandeira do Cartão

A bandeira responsável pelo Cartão. Para cartões da Elo, sempre será Elo.

allowedCaptures (CardCapture!) Modos de captura permitidos para o cartão.

Esta lista diz quais os modos de captura são permitidos para o cartão, por exemplo se POS então pode ser utilizado num ponto de venda (Point Of Sale), caso contrário ao tentar utilizá-lo com tal irá resultar em transação rejeitada.

usages (CardUsage!) Usos permitidos permitidos para o cartão.

Esta lista diz se o cartão pode ser utilizado para débito, para crédito à vista, crédito parcelado pela loja, dentre outros.

network (CardNetwork!) Rede para uso do Cartão.

Cada cartão deve ser utilizado em uma rede, a qual é listada neste campo. Por exemplo os cartões Elo utilizam as redes:

  • Elo: uso doméstico (isInternational = false);
  • Elo-Discovery: uso internacional.

issuer (CardIssuer!) Emissor do cartão.

Todo BIN está associado a um e apenas um emissor, o qual pode ser consultado com este campo para obtenção do identificador global único, razão social, nome fantasia, CNPJ, endereço, contatos e afins.

metadata (CardMetadata!) Meta dados para apresentação do cartão ao usuário.

Meta dados tais como:

  • imagem
  • cores Estes deverão ser utilizados para apresentação de um cartão ao usuário de modo a esclarecer a informação e evitar erros.

services (CardHolderService!) Serviços (benefícios) disponíveis ao portador do cartão.

Os serviços, também conhecidos como benefícios, ao portador. Por exemplo:

  • Seguro Viagem, para compra de passagens aéreas;
  • Proteção de Compra, para compra de bens;
  • Garantia Estendida, para compra de bens;
  • Acesso ao WiFi.

IntRange

Define uma faixa de números inteiros.

Tanto min quanto max são inclusos na faixa. Ou seja:

  • min: 10, max: 12 define os números: 10, 11 e 12;
  • min: 100, max: 100 define apenas o número 100.

Parâmetros de entrada

min (Int!) Número mínimo (inicial), incluso na faixa.

max (Int!) Número máximo (final), incluso na faixa.

CardProduct

Informação de produto associado ao cartão

Cada cartão é relacionado a um produto. No caso da Elo, exemplos de produto são:

  • Básico
  • Clássico
  • Corporativo
  • Grafite
  • Nanquim
  • Viagem
  • Pré-pago

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome do produto.

Exemplos de Produtos Elo:

  • Básico
  • Clássico
  • Corporativo
  • Grafite
  • Nanquim
  • Viagem
  • Pré-pago

image (ImageUrl) URL da imagem. 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.

url (String) URL do produto

CardBrand

Bandeira (marca) do cartão

A bandeira do cartão atualmente retorna Elo.

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome da bandeira

image (ImageUrl) URL da imagem. 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.

url (String) URL da bandeira

CardCapture

Modo de captura (entrada) do cartão.

O modo de captura define como o cartão pode ser utilizado, exemplos tradicionais:

  • POS (Point of Sale, ou Ponto de Venda)
  • TEF (Transferência Eletrônica de Fundos)
  • Internet (lojas virtuais, e-commerce)
  • Telemarketing (centrais de venda por telefone)
  • ATM (Automated Teller Machine, ou Caixa Eletrônico)

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome da Captura

code (Int!) Código Bancário da Captura

Nos sistemas tradicionais pode ser necessário transitar o código da captura, que é fornecido por este número.

Por exemplo:

  • POS = 1
  • TEF = 2
  • Internet = 3
  • Telemarketing = 4
  • ATM = 5

CardUsage

Uso de um Cartão.

Define como as compras poderão ser realizadas, por exemplo:

  • Crédito à Vista
  • Débito
  • Parcelado pela loja

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome do Uso

code (Int!) Código Bancário do Uso

Nos sistemas tradicionais pode ser necessário transitar o código do uso, que é fornecido por este número.

Por exemplo:

  • Crédito à Vista = 70
  • Débito = 71
  • Parcelado Loja = 72

CardNetwork

Rede para utilização do Cartão

Cada cartão deve ser utilizado em uma rede, por exemplo para cartões Elo:

  • Elo para cartões domésticos;
  • Elo-Discovery para cartões internacionais.

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

name (String!) Nome da Rede

Exemplos para Elo:

  • Elo para cartões domésticos;
  • Elo-Discovery para cartões internacionais.

image (ImageUrl) URL da imagem. 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.

url (String) URL da rede

CardIssuer

Entidade do Emissor de Cartão

Parâmetros de entrada

id (ID!)

name (String!)

legalName (String!)

description (String)

image (ImageUrl)

legalIds (CompanyLegalIds!)

contacts (CompanyContact!)

addresses (Address!)

url (String)

cards (CardsConnection) Consulta todos os objetos de cartão (Card) disponíveis no contexto.

Se executado por um portador de cartão, serão retornados todos os cartões que este possui e foram emitidos por este emissor.

Se executado por um emissor de cartão, serão retornados todos os cartões emitidos por este.

Em outros casos, como ao ser executado por um comerciante, um erro será produzido.

CardMetadata

Metadados de cartão: como representar o cartão visualmente

Parâmetros de entrada

image (ImageUrl) URL da imagem. 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.

backgroundColor (String) Cor de fundo (background) em notação web padrão: #ffffff (branco), #ff0000 (vermelho), #00ff00 (verde), #0000ff (azul). Deve ser usado em conjunto com foregroundColor quando não é possível usar imagem.

foregroundColor (String) Cor de primeiro plano (foreground) em notação web padrão: #ffffff (branco), #ff0000 (vermelho), #00ff00 (verde), #0000ff (azul). Deve ser usado em conjunto com backgroundColor quando não é possível usar imagem.

issuer (String) Emissor de cartão, i.e.: "Um Banco" Deve ser usado quando não é possível utilizar imagem.

É o mesmo que consultar o BIN { issuer { name } }

brand (String) Bandeira do cartão, i.e: Elo Deve ser usado quando não é possível utilizar imagem.

É o mesmo que consultar o BIN { brand { name } }

product (String) Nome do produto associado ao cartão, i.e.: Nanquim, Grafite.

É o mesmo que consultar o BIN { product { name } }

CardTokenOrigin

Origem do token: contém informação sobre a criação do token.

TODO: Review in depth

Parâmetros de entrada

timestamp (DateTime!) Quando o token foi criado

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

O opcional ipv6Mapped estabelece que os endereços IPv4 sempre serão codificados como IPv6 usando regras de mapeamento: [::ffff:127.0.0.1]

Pode ser null se o endereço IP era desconhecido no momento de criação do token

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

device (Device) 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...

merchant (Merchant) Comerciante que solicitou a criação do token.

Se usando uma carteira digital pessoal, este será null. Caso contrário, será o comerciante.

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

wallet (Wallet) A carteira digital, caso tenha sido utilizada por um portador de cartão para isto. Caso contrário será null.

Geolocation

Geolocalização: localização geográfica mundial.

Parâmetros de entrada

lon (Float!) Longitude, mandatório: em graus.

lat (Float!) Latitude, mandatório: em graus.

alt (Float) Altitude, opcional: em metros acima da elipsoide de referência WGS84.

precision (Float) Precisão, opcional: precisão horizontal dessa localização, radial, em metros.

source (GeolocationSource) Origem da informação. Pode ser null para "desconhecida" ou "outra".

Device

Dispositivo do usuário.

Usado para permitir que o usuário rastreie de onde partiu uma ação no sistema, comparando com seus próprios dispositivos e contatando o suporte caso dispositivo desconhecido seja utilizado.

Parâmetros de entrada

userAgent (String) Agente de Usuário (User-Agent) usado nas requisições HTTP.

brand (String) Marca: como Apple, Samsung, LG...

model (String) Modelo: como iPhone 7 Plus, Galaxy 7...

type (DeviceType) Tipo: pode ser usado para mostrar um ícone

serialNumber (String) Número serial que pode ser usado para identificar dispositivos.

imei (String) IMEI de 15 dígitos, usado para identificar o modem, se houver.

os (String) Sistema operacional (nome e versão): como Windows 10, iOS 9...

CreateCardTokenPayload

Retorno da mutação createCardToken().

Compatível com Relay.

Parâmetros de entrada

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.

Parâmetros de entrada

clientMutationId (String)

cardToken (CardToken) O token suspenso ou null caso nenhum tenha sido.

Node

Node compatível com Relay.

Parâmetros de entrada

id (ID!) Identificador Global Único para este objeto

CardStatusInterface

Interface que todo estado de cartão (CardStatus) deve implementar

Parâmetros de entrada

status (CardStatus!) O estado

ActivateCardTokenInput

Entrada para mutação activateCardToken().

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

Compatível com Relay.

Parâmetros de entrada

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 (String) O identificador global único do token do cartão.

Caso tenha acesso ao ID do token 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 token do cartão, neste caso deverá ser utilizado cardTokenId.

Estrutura de assinatura e criptografia:

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

Ou seja, os dados conforme o esquema JSON CardTokenSensitiveInput 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 (CardTokenSensitiveInput):

  • pan: O número da conta primária (Primary Account Number), também conhecido como \"número do cartão\" virtual (Virtual Card Number - VCN). Exemplo: "1234567890123456"
  • expiry: Data de validade do token 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 token do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).
    • year: Ano da validade do token 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 token do cartão (Card Security Code), usualmente retornado na mutação createCardToken() no campo sensitive.

  • 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 e não é retornado em createCardToken(). 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"

    JSON Schema: CardTokenSensitiveInput.json

SearchFilterInput

Entrada para filtragens de busca com informações textuais.

Parâmetros de entrada

filter (String) TODO: document filter language, something like Google or GMail

CardFilterInput

Entrada que filtra cartões a serem retornados

Parâmetros de entrada

status (CardStatus) Se não-nula, retorna apenas cartões com dado estado. Exemplo: ACTIVE Se null, retorna cartões em todos os estados.

usageConstraints (CardUsageConstraintsInput) Se não-nula, retorna apenas cartões com as dadas restrições de uso. Se null, retorna cartões com quaisquer restrições de uso.

cardHolderServiceId (ID) Se não-nula, retorna apenas cartões oferecendo um certo serviço (CardHolderService), referente a availableServices. Se null, retorna cartões que ofereçam quaisquer serviços.

funding (CardFunding) Se não-nula, retorna apenas cartões com dado financiamento. Exemplo: DEBIT Se null, retorna cartões em todos os tipos.

cardProductId (ID) Se não-nula, retorna apenas cartões de um certo produto (CardProduct). Se null, retorna cartões de todos os produtos.

cardBrandId (ID) Se não-nula, retorna apenas cartões de uma certa bandeira (CardBrand). Se null, retorna cartões de todas as bandeiras.

cardCaptureId (ID) Se não-nula, retorna apenas cartões que permitem uma dada captura (CardCapture). Se null, retorna cartões de todas as capturas.

cardUsageId (ID) Se não-nula, retorna apenas cartões de um certo uso (CardUsage). Se null, retorna cartões de todos os usos.

cardNetworkId (ID) Se não-nula, retorna apenas cartões de um certa rede (CardNetwork). Se null, retorna cartões de todas as redes.

cardIssuerId (ID) Se não-nula, retorna apenas cartões de um certo emissor (CardIssuer). Se null, retorna cartões de todos os emissores.

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.

Parâmetros de entrada

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 ([CardCurrencyRangeInput]) 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.

allowedMerchants ([ID]) Lista de comerciantes autorizados.

Se null, é ilimitada.

allowedMerchantCategories ([MerchantCategoryRangeInput]) Série de categorias de comerciantes autorizadas, definidas por código ISO.

Se null, é ilimitada.

deniedMerchantCategories ([MerchantCategoryRangeInput]) Série de categorias de comerciantes proibidas, definidas por código ISO.

Se null, é ilimitada.

CardCurrencyRangeInput

Define limites operacionais para uma moeda.

Parâmetros de entrada

currency (String!) Código da moeda com 3 letras (ISO4217) Exemplo: EUR, USD, BRL...

min (Float) Valor mínimo ou null para ilimitado.

max (Float) Valor máximo ou null para ilimitado.

MerchantCategoryRangeInput

Série de códigos ISO18245 para categorias de comerciantes.

Também conhecido como MCC (Merchant Category Code), tem 4 dígitos.

Parâmetros de entrada

min (Int) Código ISO18245 mínimo a ser incluído na série.

max (Int) Código ISO18245 máximo a ser incluído na série.

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.

Parâmetros de entrada

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 (String) 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"

    JSON Schema: CardSensitiveInput.json

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.

Parâmetros de entrada

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 (String) O identificador global único do token do cartão.

Caso tenha acesso ao ID do token 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 token do cartão, neste caso deverá ser utilizado cardTokenId.

Estrutura de assinatura e criptografia:

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

Ou seja, os dados conforme o esquema JSON CardTokenSensitiveInput 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 (CardTokenSensitiveInput):

  • pan: O número da conta primária (Primary Account Number), também conhecido como \"número do cartão\" virtual (Virtual Card Number - VCN). Exemplo: "1234567890123456"
  • expiry: Data de validade do token 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 token do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).
    • year: Ano da validade do token 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 token do cartão (Card Security Code), usualmente retornado na mutação createCardToken() no campo sensitive.

  • 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 e não é retornado em createCardToken(). 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"

    JSON Schema: CardTokenSensitiveInput.json

permanent (Boolean) Se true, a suspensão é definitiva. É false por padrão.

reason (CardSuspendReason) 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.

Gender

Opções de gênero

Parâmetros de entrada

FEMALE

MALE

MaritalStatus

Opções de estado civil

Parâmetros de entrada

DIVORCED Divorciado

MARRIED Casado

COMMON_LAW_MARRIED União Estável

SINGLE Solteiro

WIDOWED Viúvo

PersonContactType

Tipo de contato com pessoa física.

Parâmetros de entrada

PHONE o valor é um número de telefone, celular ou fax

EMAIL o valor é um e-mail

IM aplicativo de mensagens instantâneas O valor é um identificador de usuário com o campo de contexto

OTHER valor que segue texto livre

VerifiedStatus

Estados de verificação.

Utilizado, por exemplo, para verificação de contatos de um portador.

Parâmetros de entrada

UNVERIFIED O ítem ainda não foi verificado.

PENDING Iniciou-se o processo de verificação, porém ele ainda não foi concluído. Após a conclusão mudará para VERIFIED ou FAILED.

VERIFIED O ítem foi verificado com sucesso.

FAILED O ítem falhou verificação.

NOT_APPLICABLE O processo de verificação não se aplica a este ítem.

CardStatus

Estado do cartão

Cada estado possui seu próprio payload em implementações específicas de CardStatusInterface. Use fragmentos para consultar seus campos.

Parâmetros de entrada

INACTIVE Cartão não foi ativado

ACTIVE Cartão foi ativado e está pronto para o uso

SUSPENDED Cartão foi suspenso e não pode ser utilizado

CompanyContactType

Tipo de contato com a empresa.

Parâmetros de entrada

PHONE o valor é um número de telefone, celular ou fax

EMAIL o valor é um e-mail

IM aplicativo de mensagens instantâneas O valor é um identificador de usuário com o campo de contexto

OTHER valor que segue texto livre

CardFunding

Financiamento do cartão: crédito, débito ou múltiplo.

Parâmetros de entrada

CREDIT Cartão de Crédito

DEBIT Cartão de Débito

MULTIPLE Cartão de Crédito e Débito (ambos simultaneamente).

GeolocationSource

Define a origem de uma informação geolocalizada.

Parâmetros de entrada

USER Preenchimento manual pelo usuário

CELLULAR Adquirido da rede celular.

WIFI Adquirido da rede WiFi.

GPS Adquirido do GPS (exemplos: carro, smartphone, tablet...)

DeviceType

Tipo de dispositivo do usuário.

Este tipo pode ser usado para auxiliar na interação com o usuário, como usando ícone do dispositivo se não houver uma imagem específica para uma marca e modelo.

Parâmetros de entrada

DESKTOP Computador pessoal (PC)

LAPTOP Laptop/Notebook

SMARTPHONE Smartphone

TABLET Tablet

E_READER Leitores de livros digitais (Electronic Book Readers - e-Readers)

WATCH Relógio ou pulseira. Exemplos: Apple Watch, Fitbit, Samsung Gear

OTHER_WEARABLE Outros dispositivos vestíveis (wearable) (que não relógios)

CAR Carro

MOTORCYCLE Motocicleta

BOAT Barco

AIRPLANE Avião

OTHER_VEHICLE Outros veículos (que não carro, motocicleta, barco ou avião)

PORTABLE_GAME_CONSOLE Vídeo games portáveis, como PS Vita, Nintendo 3DS...

GAME_CONSOLE Consoles de vídeo games, como PS4, XBox360

CAMERA Câmera de fotografia ou filmagem

SMARTTV TV Inteligente (SmartTV)

PORTABLE_MEDIA_DEVICE Dispositivos de mídia portáveis, como iPod.

MEDIA_DEVICE Dispositivos de mídia não portáveis, como DVD Player, Home Theater

HOME_APPLIANCE Eletrodomésticos como geladeiras ou torradeiras.