Tokenização Estabelecimento Comercial

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

Feito para:  Estabelecimentos ComerciaisMerchantsFacilitadoresAcquirersAdquirentes

Como funciona

Primeiros passos

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

  2. Crie uma conta no portal do desenvolvedor.

  3. Cadastre sua primeira aplicação.

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

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

Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    "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 (2027, não 27).

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

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

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

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

Exemplo completo do JSON de sensitive:

{
  "pan": "1234567890123456",
  "expiry": {
    "month": 2,
    "year": 2027
  },
  "name": "Joao da Silva",
  "csc": "123"
}

NOTA: Os atributos name e csc são opcionais.

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

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

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

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

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

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

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

A estrutura de assinatura segue a seguinte ideia:

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

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

query {
    serverPublicKey {
        key # Obrigatório
    }
}

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

A estrutura de criptografia segue a seguinte ideia:

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

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

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

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

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

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

query {
    serverPublicKey {
        key #Obrigatório
    }
}

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

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

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

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

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

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

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

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

Exemplo com o campo lifeCycleCallbackUrl:

createCardTokenForUser(input: {
  sensitive: "dados sensíveis criptografados",
  lifeCycleCallbackUrl: "https://seulinkdecallback.com/", #Link de callback para que a Elo possa notificar o parceiro em caso de mudança do status do cartão
  cardProductId: "354087fe-f3d0-31ae-a05e-a8705465f365", # Este é o produto vinculado ao cartão, onde o emissor, ao provisionar um cartão, deverá enviar as informações do produto cadastrado conforme a orientação do time de integração e operações da Elo
  tokenRequestorId: "00000000000", # Mais informações desse campo na seção "TokenRequestorId"
  userId: "81aae8ed-4d9f-3677-9957-5beb821e1b1d", # Id do usuário CardIssuer querendo tokenizar cartão em nome de outro usuário
  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"
    }
  }
})
{
  cardToken { # Token retornado, deve ser salvo pois não pode ser consultado!
    id # informação utilizada para suspender o cardToken
    last4
    expiry {
      month
      year
    }
    cardOrigin { id }
    sensitive
  }
}

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

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

Exemplo com lifeCycleCallbackUrl:

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

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

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

Os dados referentes ao tokenRequestorId serão repassados ao parceiro em tempo de projeto.

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

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

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

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

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

Em uma mesma chamada da API de Tokenização Elo, podem existir diferentes fluxos para diferentes tipos de usuários. A mutation createCardTokenForUser se enquadra nesta situação, onde para um determinado tipo de usuário, um campo da chamada pode ser obrigatório e em outro fluxo pode ser opicional.

A seguir você pode encontrar descrições dos principais campos utilizados na mutation createCardTokenForUser nos fluxos de Virtual Card Number (VCN) e E-commerce

  • sensitive e cardId - Os dois campos sensitive e cardId servem para informar e identificar o cartão original que será tokenizado e possível passar um campo ou o outro. O sensitive possui os dados do cartão cifrados e o cardId irá buscar por um cartão provisionado/tokenizado anteriormente.

  • cipheredCardVerificationData - Este campo possui o dado do csc (Card Security Code) ele é apenas é utilizado quando a request possui o campo cardId e assim o serviço válida o csc passado anteriormente (ao gerar o token com sensitive) com o novo csc informado na nova request.

  • user - Campo opcional, usuário a quem deve ser atribuído o card token criado, o serviço irá procurar por este usuário na API de Portadores e caso não seja encontrado é criado um usuário provisório na API (Usuário Provisório).

  • origin - Campo opcional, informando dados da origem do cartão/token que será criado.

  • usageConstraints - Campo opcional, define o número de vezes o token pode ser utilizado No fluxo de ECOMMERCE (Quando o usuário que esta executando a chamada é um Merchant ou Acquirer) o serviço sempre irá ignorar este campo e definir o valor 1 para o número máximo de vezes que o token pode ser utilizado.

    • maxUsage - O serviço sempre irá ignorar este campo e definir o valor 1 para o número máximo de vezes que o token pode ser utilizado

  • tokenRequestorId - Campo obrigatório mas principalmente utilizado no fluxo ECOMMERCE (Quando o usuário que esta executando a chamada é um Merchant ou Acquirer)

  • cardProductId - Campo opcional porem é validado, quando a request vem com o cardId o cardProductId é comparado com o que foi passsado anteriormente,sendo apenas utilizado no fluxo VCN (Quando o usuário que esta executando a chamada é um Card Issuer)

  • lifeCycleCallbackUrl - Url utilizada no processo de callback para notificar atualizações do token. Esta configuração se da á nível de cardId, por isso a cada criação de um card token para um mesmo cartão esta configuração será sobrescrita.

Também é possível atualizar a url de callback informada na mutation createCardTokenForUser no campo lifeCycleCallbackUrl, através da mutation updateCardTokenCallbackUrl.

mutation {
  updateCardTokenCallbackUrl(
    input: {
      url: "https://dev.elo.com.br/563a9b73-fcc6-4d16-b357/updateCard",
      cardId: "c13a05a9-f339-40d6-9b0f-38e794bdd8c7"
    }
  ) {
    success
  }
}

Para as solicitações de cardTokens de forma assíncrona, será utilizado a mutation createCardTokenForUserAsync, assim os pedidos de cardTokens não irão receber o retorno do Token criado no mesmo instante, retornará apenas um identificador desse pedido. Os pedidos serão enviados a uma fila, e ao serem processados, seu resultado será enviado através de uma callback (url que foi informada na requisição) contendo os dados da tokenização.

Assim como o processo de Tokenização, o Token pode ser criado a partir dos dados sensíveis do cartão (PAN, CSC e data de validade) assinados e cifrados conforme a seção de Criptografia.

mutation {
  createCardTokenForUserAsync (
    input: {
      clientMutationId: "123456789",
      sensitive: "<dados sensiveis criptografados>", 
      user: { # Campo opcional, usuário a quem deve ser atribuído o card token criado nesta mutation, 
        name: "name",
        legalIds: {
          cpf: "123456789"
        }
        birthday: "1993-08-09",
        gender: MALE, # enum FEMALE, MALE
        maritalStatus: SINGLE  # enum DIVORCED, MARRIED, SINGLE, WIDOWED, COMMON_LAW_MARRIED
        income: {
          personal: 1000,
          family: 2000,
          currency: "EUR"
        },
        occupationId: "1234-56",
        contacts: [
          {
            type: PHONE, # enum PHONE, EMAIL
            value: "+5519999999999"
          },
          {
            type: EMAIL, # enum PHONE, EMAIL
            context: "", 
            value: "elo@elo.com"
          }
        ],
        addresses: [{
          context: "casa"
          city: "cps",
          country: "BRA",
          state: "Bahia",
          number: -0,
          place: "algum",
          district: "$abc",
          zip: "13030000",
          complement: "111111"
        }],
        origin: "123" # Campo opcional, informando dados da origem do cartão/token que será criado
      },
      usageConstraints: {
        expiry: "2020-10-29T12:08:56Z",
        allowedTxAmounts: [{currency: "EUR", min: 5, max: 5}],
        allowedMerchantCategories: [{min: 15, max: 20}], 
        deniedMerchantCategories: [{min: 5, max: 10}]
      },
      tokenRequestorId: "57800100000",
      callbackUrl: "https://webhook.site/ee17b748-266a-404d-97f7-72ec5e23a437"
    }
  ) {
    clientMutationId
    cardTokenRequestId
  }
}

Com o cardTokenRequestId recebido da mutation acima, poderá ser consultado o status da solicitação dos tokens gerados usando a seguinte consulta:

{
  cardTokenForUserAsyncStatus(cardTokenRequestId: "e54c64ed-cebe-4ac9-9b3d-2864e4113910") {
    cardTokenRequestId
    callbackUrl
    status
    statusDetail
  }
}

As solicitações assíncronas não devolvem o retorno na response da chamada efetuada pelo usuário e sim um identificador desse pedido. O resultado do processamento é retornado via callback através de uma requisição na url de callback informada na requisição. O callback é uma espécie de ligação de volta, imagine a seguinte situação: numa primeira ligação do usuário a pessoa que atendeu não tem a resposta ainda, então ela desliga o telefone, obtem a resposta e liga de volta ao usuário para informar o resultado.

Ao realizar a chamada createTokenForUserAsync, será retornado um callback com o resultado do processamento, efetuando uma requisição POST à URL cadastrada através do campo callbackUrl. No exemplo acima foi enviado a URL https://webhook.site/ee17b748-266a-404d-97f7-72ec5e23a437, com este exemplo o parceiro estará preparado para receber uma requisição POST para este recurso.

Nota: Vale ressaltar ser de responsabilidade do parceiro estar preparado para receber o callback na URL cadastrada.

Nota: É de responsabilidade do parceiro gerar o callback URL enviado no campo callbackUrl da chamada createTokenForUserAsync.

Exemplo com o corpo JSON, enviada através da requisição de callback:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", --Identificador único da solicitação assíncrona
  "sensitive": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiRUNESC1FUyIsImtpZCI6ImtNeU14RzdFYkQ1XzAtQndzNm1uR0RibVB1ZXZHelc4UldrZXVXXzk2RTQiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJIbTNiMVRlWlVqVERFQXNKQVM5M01vNHU4Z3BnWE5ESXJjLVhtdXBNNEhBIiwieSI6IlZwbVl2WGhLUVN3Ulg1T3NzN2p6ekJtT2I4UU5UcFNyQS1tQ0UwUHYxTTAifX0..TGBQ.Vg.6JrLT6c2WzsXbN1XmX0zgQ", -- Dados do token gerado
  "cardId": "4846cc7a-c540-496d-8399-fbde2bc6bcdb", --Identificador do cartão aprovisionado
  "status": "SUCCESS", -- SUCCESS, ERROR
  "statusDetail": "Completed." -- Detalhes adicionais relacionados ao status
}

Ao enviar esta requisição de callback, é esperada uma resposta com Status Code 200 (OK).

Em casos em que o Emissor faça alguma atualização no cartão (como, por exemplo, a substituição por um novo devido ao vencimento do cartão antigo) ou durante o ciclo de vida do token, será disparada uma notificação para o parceiro na URL informada no campo lifeCycleCallbackUrl durante a chamada createCardTokenForUser.

A chamada de callback pode devolver 3 status possíveis: SUSPENDED, UPDATED e DELETED.

Abaixo um exemplo de uma notificação que poderá ser enviada através de uma requisição HTTP POST durante a atualização do cartão pelo Emissor:

{
  "timestamp": "2021-02-10T20:41:53.890Z",
  "status": "UPDATED",
  "cardOriginId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "newData": {
    "bin": "655000",
    "last4": "1234"
  }
}

Abaixo um exemplo de uma notificação que poderá ser enviada através de uma requisição HTTP POST durante o ciclo de vida do token:

{
  "cardTokenId": "02e683d8-01e3-4645-a313-b190ea1782f6",
  "timestamp": "2021-02-10T20:41:53.890Z",
  "status": "SUSPENDED",
  "cardOriginId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Ao enviar esta requisição de callback, a Elo espera uma resposta com Status Code 200 (OK).

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

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

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

Exemplo do uso da API:

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

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

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

As chamadas desta API retornam códigos de stauts junto com o retorno das requisições, a seguir serão listados os possíveis códigos de retorno respectivos significados.

404

  • 404.002: Password token email not found.

  • 404.003: Password token phone not found.

  • 404.005: Recovery password not found.

  • 404.006: User not found.

  • 404.007: Bin not found.

  • 404.009: Card Origin not found.

  • 405.001: Operation not allowed for this user.

412

  • 412.001: User name not informed.

  • 412.002: Password not informed.

  • 412.003: User name and password, or SocialNetwork required.

  • 412.004: Provider not informed.

  • 412.005: Token not informed.

  • 412.006: Password not informed.

  • 412.008: Invalid document.

  • 412.011: Social Type not informed.

  • 412.012: Social Type not allowed.

  • 412.013: Access token not informed.

  • 412.014: Provider not found.

  • 412.015: Choose one document (cpf, cnpj or rg).

  • 412.016: Inform phone or email or contact type.

  • 412.017: Invalid password length.

  • 412.018: Size not allowed for field

  • 412.019: UserId not informed.

  • 412.020: Old Password not informed.

  • 412.022: Confirmation of New Password not informed.

  • 412.023: Confirmation of New Password and New Password are not equal.

  • 412.024: Access unauthorized.

  • 412.025: Invalid application name.

  • 412.026: Old Password not found.

  • 412.027: Contact type invalid.

  • 412.028: Invalid token.

  • 412.029: Password token expired.

  • 412.007: Special characters found in sensitive data.

  • 412.009: Invalid data sended in provision card.

  • 412.021: Operation not allowed for token requestor id.

422

  • 422.001: User name already exists for application.

  • 422.002: Social token not found.

  • 422.004: Invalid data for password recovery

  • 422.005: Token not found.

  • 422.006: CPF or CNPJ not found.

  • 422.008: Login not found.

  • 422.009: Invalid old password.

  • 422.010: Template e-mail not found.

  • 422.011: It was not possible to send recovery message, try again later.

  • 422.012: SMS template not found.

  • 422.014: Contact system admin.

  • 422.015: Social user name already exists for application.

  • 422.016: It was not possible to generate a token.

  • 422.017: User contacts not found.

  • 422.018: It was not possible to generate a token due time restriction. Try again later.

  • 422.019: UserId: ''{0}'' not found.

  • 422.020: Risk Score integration failed.

  • 422.022: Authentication failed.

  • 422.023: No value found for this key.

  • 422.024: User authenticity verification has failed!

  • 422.003: Configuration not found for issuer.

  • 422.013: Processing error in TSP /tokenizeCard.

  • 422.021: Invalid expiry date.

  • 422.031: Card Token Reference Not Found. This cardId doesn't have a valid card token reference, consider use the card 'sensitive' data instead.

  • 422.041: Contact system admin.

  • 422.052: Public key not informed.

  • 422.053: Signature is invalid.

  • 422.054: Ciphered data invalid.

  • 422.056: Signed data received from user has a malformed payload.

  • 422.078: Invalid pan.

  • 422.086: Bin verification has failed.

  • 422.087: User not found. Integration failed.

  • 422.089: Check Card step failed.

  • 422.091: Enroll Card step failed.

  • 422.097: Activate Device Token step failed.

  • 422.103: Unable to tokenize card - Contact the Issuer.

  • 422.104: The card was denied during tokenization process - Contact the Issuer.

  • 422.105: The card was denied during tokenization process - Check informed data.

  • 422.108: Product not able to tokenize card.

  • 422.109: An internal integration step has failed. Please try again later.




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

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

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

Fragmentos inline:

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

Fragmentos reusáveis:

fragment CardLast4Fragment on Card {
  last4
}

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

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

Argumentos:

id: ID obrigatório

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



Argumentos:






Cria um token para um determinado cartão.

Usável por:

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

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

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

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

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

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

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

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

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

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

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

Argumentos:

input: CreateCardTokenInput obrigatório



Suspende um CardToken

Usável por:

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

  • Comerciantes para suspender tokens criados por si mesmos.

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

Argumentos:

input: SuspendCardTokenInput obrigatório



Ativa um cartão previamente inativo.

Usável por:

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

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

Argumentos:

input: ActivateCardTokenInput obrigatório



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

Argumentos:

input: UpdateCardOriginToTokenInput obrigatório



Adiciona uma chave pública ao usuário

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

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

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

Argumentos:

input: AddPublicKeyToUserInput obrigatório



Cria um CardToken para um usuário terceiro

Argumentos:

input: CreateCardTokenForUserInput obrigatório






Entrada para mutação createCardToken.

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

Campos:

ip

:

String

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

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


geolocation

:

GeolocationInput

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


device

:

DeviceInput

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


merchantUserId

:

String

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

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


walletId

:

ID

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

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



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

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

Campos:

maxUsage

:

Int

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

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

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


expiry

:

DateTime

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


allowedTxAmounts

:

list de CardCurrencyRangeInput obrigatório

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

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

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

Se null, é ilimitada.


allowedIdCodes

:

list de ID obrigatório

Lista de comerciantes autorizados.

Se null, é ilimitada.


allowedMerchantCategories

:

list de MerchantCategoryRangeInput obrigatório

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

Se null, é ilimitada.


deniedMerchantCategories

:

list de MerchantCategoryRangeInput obrigatório

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

Se null, é ilimitada.



Entrada para mutação createCardToken().

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

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


cardId

:

ID

O identificador global único do cartão.

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

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

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


sensitive

:

String

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

Estrutura de assinatura e criptografia:

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

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

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

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

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

    • month: Mês da validade do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).

    • year: Ano da validade do cartão. Número inteiro com 4 dígitos (2017, não 17).

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

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

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

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

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

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


origin

:

CreateCardTokenOriginInput

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


usageConstraints

:

CardUsageConstraintsInput

Restrições para o novo token.

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


tokenRequestorId

:

String obrigatório

Identificador do Token Requestor.



Entrada para mutação suspendCardToken().

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

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


cardTokenId

:

ID obrigatório

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


permanent

:

Boolean

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


reason

:

CardSuspendReason obrigatório

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

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



Entrada para mutação activateCardToken ().

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

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

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


cardTokenId

:

ID obrigatório

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



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

Campos:

updateCardOriginId

:

ID obrigatório

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


sensitiveCurrent

:

String

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

Estrutura de assinatura e criptografia:

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

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

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

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

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

    • month: Mês da validade do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).

    • year: Ano da validade do cartão. Número inteiro com 4 dígitos (2017, não 17).

  • name: Nome do portador do cartão. Exemplo: "Joao da Silva". (não utilizar caracteres especiais ou acentos)

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

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

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

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

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


sensitiveNew

:

String obrigatório

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

Estrutura de assinatura e criptografia:

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

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

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

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

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

    • month: Mês da validade do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).

    • year: Ano da validade do cartão. Número inteiro com 4 dígitos (2017, não 17).

  • name: Nome do portador do cartão. Exemplo: "Joao da Silva". (não utilizar caracteres especiais ou acentos)

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

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

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

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

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



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

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


cardOriginToTokens

:

lista obrigatória de CardOriginToTokenInput obrigatório


Entrada para mutação addPublicKeyToUser()

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


userId

:

ID obrigatório

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


key

:

String obrigatório

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

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


format

:

CryptoKeyFormat

Formato da chave key.

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



Entrada para mutação createProvisionedUser().

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

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de ProvisionedUser opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


name

:

String

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


legalIds

:

LegalIdsInput obrigatório

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


birthday

:

Date

Data de nascimento


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncomeInput

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


occupationId

:

ID

Profissão do usuário.

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

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


contacts

:

list de PersonContactInput

Contatos do usuário


addresses

:

list de AddressInput

Endereços postais


originId

:

ID

Identificador único da origem da campanha


origin

:

String

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


originUrl

:

String

Url de origem de cadastro do usuário


originChannelRaw

:

String

Parametros de web analytics brutos


originChannel

:

String

Campo tratado com os paramentros de mídia


localEvent

:

String

Cidade que estará recebendo o Show ou Evento


transaction

:

TransactionInput

Dados da transação


event

:

String

Identifica o evento do cadastro do usuário.


ticket

:

String

Identifica o ticket do cadastro do usuário.


motherName

:

String

Nome da mãe do usuário.



Entrada para mutação createCardTokenForUser().

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

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


sensitive

:

String

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

Estrutura de assinatura e criptografia:

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

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

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

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

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

    • month: Mês da validade do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).

    • year: Ano da validade do cartão. Número inteiro com 4 dígitos (2017, não 17).

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

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

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

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

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

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


cipheredCardVerificationData

:

String

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

Estrutura de assinatura e criptografia:

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

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

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


cardId

:

ID

O identificador global único do cartão.

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

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

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


user

:

CreateProvisionedUserInput

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


origin

:

CreateCardTokenOriginInput

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


usageConstraints

:

CardUsageConstraintsInput

Restrições para o novo token.

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


tokenRequestorId

:

String obrigatório

Identificador do Token Requestor.


cardProductId

:

String

Identificador do produto do cartão definido pelo CardIssuer.


lifeCycleCallbackUrl

:

String

Url utilizada no processo de callback para notificar atualizações do token. Esta configuração se da a nível de cardId, por isso a cada nova criação de um card token para um mesmo cartão esta configuração será sobreescrita.






Campos:

key

:

String obrigatório


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

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

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

Campos:

id

:

ID obrigatório

sensitive

(


keyId:

String

)

:

String

last4

:

String

expiry

:

CardExpiry

holder

:

CardHolder

billingAddress

:

Address

status

:

CardStatusInterface obrigatório

usageConstraints

:

CardUsageConstraints

availableServices

:

list de CardHolderService obrigatório

usedServices

:

list de CardHolderService obrigatório

bin

:

BIN

funding

:

CardFunding

product

:

CardProduct

isInternational

:

Boolean

isCompany

:

Boolean

isToken

:

Boolean

brand

:

CardBrand

allowedCaptures

:

list de CardCapture obrigatório

usages

:

list de CardUsage obrigatório

network

:

CardNetwork

issuer

:

CardIssuer

metadata

:

CardMetadata

transactions

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

CardTransactionFilterInput

Aplica filtro, se provido.

)

:

CardTransactionsConnection

transactionsSummary

(


filter:

CardTransactionSummaryFilterInput

Aplica filtro, se provido.

)

:

list de CardTransactionCategorySummary obrigatório

card

:

Card

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

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

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


cardOrigin

:

CardOrigin

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

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

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


origin

:

CardTokenOrigin

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


tokenRequestorId

:

String

Identificador do Token Requestor.


lifeCycleCallbackUrl

:

String

Url utilizada no processo de callback para notificar atualizações do token. Esta configuração se da a nível de cardId, por isso a cada nova criação de um card token para um mesmo cartão esta configuração será sobreescrita.



Retorno da mutação createCardToken().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

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



Retorno da mutação suspendCardToken().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

O token suspenso ou null caso nenhum tenha sido.



Retorno da mutação activateCardToken().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

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



Retorno dos dados de CardOriginToToken()

Campos:

statusUpdate

:

UpdateStatus

Status da atualização


updateCardOriginId

:

ID

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


bin

:

BIN

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


last4

:

String

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


errorDescription

:

String

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



Retorno da mutação updateCardOriginToToken()

Compatível com Relay.

Campos:

clientMutationId

:

String

cardOriginToTokens

:



Usuário do Sistema

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

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

API Privada

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


verified

:

VerifiedStatus

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

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


username

:

String

Nome do usuário para acesso ao sistema


name

:

String

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


firstName

:

String

Primeiro nome do usuário


lastName

:

String

Último nome do usuário


displayName

:

String

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


legalIds

:

LegalIds

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


birthday

:

Date

Data de nascimento


age

:

Int

Idade em anos


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncome

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


occupation

(


language:

String

Língua a ser utilizada no retorno da consulta.

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

)

:

PersonOccupation

Profissão do usuário.

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


image

(


width:

Int

Caso fornecido, largura da imagem, em pixels.

height:

Int

Caso fornecido, altura da imagem, em pixels.

mimeType:

String

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

)

:

ImageUrl

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


contacts

:

list de PersonContact obrigatório

Contatos do usuário


addresses

:

list de Address obrigatório

Endereços postais


cardHolders

:

list de CardHolder obrigatório

Portadores de cartões associados ao usuário

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

Relação: 1:n


merchants

:

list de MerchantEC obrigatório

Comerciantes associados ao usuário

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

Relação: n:n


cardIssuers

:

list de CardIssuer obrigatório

Emissores de cartões associados ao usuário

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

Relação: n:n


socialNetworks

:

list de SocialNetwork obrigatório

Redes sociais relacionadas ao usuário


agreements

:

list de UserAgreement obrigatório

Termos de uso aceitos pelo usuário


accessTokens

:

list de AccessTokenInfo obrigatório

Lista de chaves de acesso ativas para este usuário


publicKeys

:

list de PublicKey obrigatório

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


originId

:

ID

Identificador único da origem da campanha


origin

:

String

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


analyticsId

:

ID obrigatório

Identificador Global Único para este objeto


acquirer

:

Acquirer

validation

:

UserValidation obrigatório

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


motherName

:

String

Nome da mãe do usuário.


userIdSha256

:

String

Sha256 do id do usuário


createdDate

:

DateTime

Data de criação do registro do usuário


updatedDate

:

DateTime

Data de atualização do registro do usuário


promotions

(


limit:

Int obrigatório

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

offset:

Int obrigatório

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

filter:

UserPromotionsFilterInput

Aplica filtro, se provido.

)

:

UserPromotionsPage

communicationChannels

:

list de String obrigatório

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


interests

:

list de UserInterest obrigatório

Assuntos de interesse do usuário


communicationChannelBlocks

:

list de CommunicationChannelBlock


Campos:

id

:

String obrigatório

Identificador da chave para este usuário.

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

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

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


key

:

String obrigatório

A chave serializada no formato requerido.

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



Retorno da mutação addPublicKeyToUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual teve chave adicionada.


publicKey

:

PublicKey

A chave adicionada.

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



Retorno da mutação createCardTokenForUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardToken

:

CardToken

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






Node compatível com Relay.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto





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

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

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


Valores possíveis:


ISSUER

Emissor solicitou a suspensão


CARDHOLDER

Portador solicitou a suspensão


PIN_LOCKED

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


TOKEN_REQUESTOR

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




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


Valores possíveis:


PEM

Privacy Enhanced Mail PEM


X509

Certificado X.509