Cadastro do Portador

A interface de programação referente ao Cadastro do Portador é primariamente composta por consultas que retornam o tipo `CardHolder` e destes consultam-se os campos como nome, documentos, endereços, contatos e demais informações.

Feito para:  Estabelecimentos ComerciaisEmissoresAdquirentesFacilitadoresOutros Desenvolvedores

Primeiros passos

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

  2. Crie um usuário no portal do desenvolvedor.

  3. Cadastre sua primeira aplicação.

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

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

Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista

O portador é um usuário do sistema (User) o qual possuí cartões. Este usuário é denomidado CardHolder e gerencia cartões (Card) e carteiras (Wallet). Um portador (CardHolder) pode cadastrar, consultar, editar e deletar seus cartões, como também pode associar seus cartões ás suas carteiras. Este pode ser uma pessoa física, que possua cartões, ou pessoa jurídica que possua cartões corporativos.

query {
    user {
        id
        username
        cardHolders {
            companyName, 
            companyLegalName, 
            cards { 
                edges { 
                    node { 
                        transactions(filter: { 
                            startTimestamp: "2017-11-21T00:00:00Z", 
                            endTimestamp: "2017-12-30T00:00:00Z",
                            includeMerchantCategories: [{ min: 1,max: 3 }, { min: 4, max: 10 }], 
                            excludeMerchantCategories: [{ min: 10, max: 10 }], 
                            status: APPROVED
                        }) 
                        {
                            pageInfo { hasPreviousPage },
                            edges { 
                                cursor, 
                                node { 
                                    id, 
                                    bin { 
                                        number, 
                                        isInternational, 
                                        product { 
                                            id, 
                                            name
                                        }, 
                                        country
                                    }, 
                                    status, 
                                    capture { id, name }, 
                                    currency, 
                                    value, 
                                    installments
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Essa seção tem como objetivo detalhar alguns processos e trazer o passo-a-passo para integração com itens da API de Cadastro de Portador ELO.

A plataforma ELO de API foi construída pensando em expor as mais diversas informações para os mais diversos clientes de API possíveis, sejam eles bancos, estabelecimentos comerciais, pessoas físicas ou qualquer outro consumidor.

Dado esse cenário, houve a necessidade de se utilizar um protocolo que pudesse ser flexível e ao mesmo tempo seguro para autenticar e autorizar acessos ao recursos e dados contidos e expostos via API.

O OAuth 2.0 é um protocolo de autorização que habilita aplicações terceiras a obter acesso limitado a um serviço web / HTTP.

O OAuth, sendo uma especificação, descreve de forma detalhada uma maneira de tratar cenários simples e complexos de segurança de API. Ele estabelece definições como:

  • Resource Owner: a entidade que é capaz de controlar o acesso a um recurso protegido. É o "dono do recurso", mas nem sempre é uma pessoa. Quando ele é uma pessoa ele é o usuário final.

  • Resource Server: o servidor que possui os recursos protegidos e recebe as requisições para acessar esses recursos.

  • Authorization Server: é um servidor que gera tokens de acesso para permitir que o consumidor acesse os recursos que o resource owner permitiu com o nível de acesso que o resource owner especificou.

  • Client: é a aplicação que acessa os recursos no resource server em nome do usuário. O client pode ser qualquer tipo de aplicação que faça isso. É o consumidor da API.

Oauth

Com essas definições, o OAuth estabelece que quando uma aplicação precisa acessar um recurso protegido ela deve obter primeiro um token de acesso (Access Token). Este é um token contendo as informações que caracterizam o acesso que o dono do recurso permitiu aos dados protegidos.

Todas as requisições realizadas junto à API da ELO deverão utilizar o protocolo HTTPS, e deverão ter em seus cabeçalhos os dados necessários para o acesso ao serviço. São eles:

  • client_id: Identificador gerado quando o desenvolvedor cria uma aplicação no portal e que pode ser encontrado nas configurações da dashboard da aplicação.

  • Authorization ou access_token: Aqui é um ponto importante que deve ter bastante atenção do desenvolvedor. Enquanto o usuário não realizou o login na API é obrigatório o envio do Authorization. Após o login o desenvolvedor deve enviar apenas o access_token obtido.

Authorization

O Authorization pode ser obtido concatenando o texto "Basic " ao resultado da codificação em Base 64 dos campos client_id e client_secret concatenados com :.

Abaixo um exemplo de pseudo-código para gerar o Authorization:

var authorization = "Basic " + base64(client_id + ":" + client_secret);

e a seguir temos um exemplo de Authorization já definido no header da requisição:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

Para que seja possível iniciar a jornada dentro da plataforma de APIs da Elo, é necessário que um usuário seja criado. Para esse processo o desenvolvedor deverá usar a função createUser disponibilizada pela API. Esta função pode ser utilizada de duas maneiras:

  • O usuário utilizará o nome de usuário e senha como meio de autenticação.

  • O usuário utilizará uma rede social suportada pela plataforma da ELO como meio de autenticação.

A seguir é demonstrado uma visão geral desse processo.

Fluxo de criação de um usuário

fluxoCreateUser

Um exemplo da utilização da função createUser usando o nome de usuário e senha como autenticação é demonstrado a seguir.

Exemplo do corpo da requisição:

mutation{
  createUser(input:{
    clientMutationId: "123",
    username: "username",
    bcryptPassword: "$2a$12$oumE.pnRbsdi.c4KYsyNWOJoVyfi2jMKDe102Er5uGCdzd49SvE1Y",
    name: "name",
    firstName: "firstName",
    lastName: "lastName",
        contacts: [{
            type: PHONE
            context: "CASA"
            value: "+5519912345678"
        }]
    displayName: "displayName",
    legalIds:{
      cpf: "1234567890",
      rg:{
        number: "234567890",
        issuerOrganization: "SSP",
        issuerState: "SP",
        issueDate: "2020-12-03"
      }
    }
  })
  {
    clientMutationId,
    id,
    name
  }
}

Exemplo da resposta da API:

{
   "data": {
        "createUser": {
            "id": "89bd51d6-8eaf-31a5-bd2c-1fve81d17db4",
            "name": "name"
        }
   }
}

No exemplo acima o campo id é o access_token que deve ser utilizado caso o usuário faça alguma requisição a algum recurso da API. Nesse cenário não é necessário que o usuário faça login após a criação pois o mesmo já foi feito implicitamente pela função createUser e o token de acesso pode ser utilizado até sua expiração.

Um exemplo da utilização da função createUser usando uma rede social é demonstrado a seguir.

Exemplo do corpo da requisição:

mutation{
  createUser(input:{
    clientMutationId: "123",
    username: "username",
    socialNetwork:{
      provider: "FACEBOOK",
      username: "usernameFacebook@gmail.com"
    },
    oauth:{
      accessToken: "EAACEdEose0cBAPZAVQLY5qPqEfqPPPviCy5NYbYBX7zLndQWDiUZBOBMC5Ry...",
      refreshToken: "",
      scopes: "email",
      expiryTimestamp: "2018-03-01T00:00:00Z"
    },
    name: "name",
    firstName: "firstName",
    lastName: "lastName",
    displayName: "displayName",
    legalIds:{
      cpf: "1234567890",
      rg:{
        number: "234567890",
        issuerOrganization: "SSP",
        issuerState: "SP",
        issueDate: "2020-12-03"
      }
    }
  })
  {
    clientMutationId,
    id,
    name
  }
}

A resposta da criação do usuário usando uma rede social é a mesma do exemplo anterior.

Tipos de Usuário

Após a criação, um determinado usuário pode assumir 3 tipos distintos na plataforma da Elo, sendo eles:

  • Card Holder: Um usuário portador de um ou mais cartões Elo;

  • Card Issuer: Um usuário que emite cartões Elo;

  • Merchant: Um estabelecimento comercial que realiza transações com cartões Elo;

Cada tipo possui sua forma de ser associado, com informações pertinentes a cada um. Um usuário só pode ter um tipo associado ao mesmo tempo, logo, se um usuário está associado a um CardHolder e tenta se associar a um Merchant um erro será retornado. Neste caso, é necessário remover a associação do CardHolder do usuário e, somente depois, realizar a associação ao novo tipo.

Para associar um CardHolder ao usuário basta utilizar a função createCardHolderForUser, a mutation abaixo é um exemplo de sua utilização. Por questão de segurança o campo userId não se refere ao real id do usuário, e sim ao seu access_token.

Exemplo do corpo da requisição:

mutation{
    createCardHolderForUser(input:{
        clientMutationId: "123",
        userId: "33744898-9844-4864-a0ca-046d50fdaf15",
        companyName: "companyName",
        companyLegalName: "companyLegalName",
        companylegalIds: {
            cnpj: "1234567890"
        }
    })
    {
        clientMutationId,
        user{
            id,
            verified,
            name,
            displayName
        },
        cardHolder{
            id,
            name,
            companyName,
            companyLegalName
        }
    }
}

Neste exemplo estamos criando o CardHolder e associando o mesmo ao usuário identificado pelo access_token, que é refletido no campo userId. Os dados retornados após a criação e associação do CardHolder ao usuário, serão os que foram definidos na parte inferior da mutation.

Para associar um CardIssuer ao usuário basta utilizar a função addCardIssuerToUser, a seguir temos a chamada para esta mutation como exemplo de utilização. Por questão de segurança o campo userId não se refere ao real id do usuário, e sim ao access_token do mesmo.

Exemplo do corpo da requisição:

mutation{
    addCardIssuerToUser(input:{
        clientMutationId: "123",
        userId: "97c7fb10-174c-4e23-8feb-926d1d23a035",
        cardIssuerId: "1b253372-8215-4567-a54d-4fa78dadf0f6"
    })
    {
        clientMutationId,
        user{
            id,
            verified,
            name,
            displayName
        },
        cardIssuer{
            id,
            name,
            legalName
        }
    }
}

Neste exemplo estamos associando um CardIssuer ao usuário identificado pelo access_token, que é refletido no campo userId. Os dados retornados após a associação do CardIssuer ao usuário, serão os que foram definidos na parte inferior da mutation.

Para associar um Mechant ao usuário basta utilizar a função addMerchantToUser, a seguir temos um exemplo de sua utilização. Por questão de segurança o campo userId não se refere ao real id do usuário, e sim ao access_token do mesmo.

Exemplo do corpo da requisição:

mutation{
    addMerchantToUser(input:{
        clientMutationId: "123",
        userId: "14991673-f5b9-43b8-8cb3-8da353b9b70c",
        merchantId: "b86eb0ef-0c21-4ea5-b407-9f113a229190"
    })
    {
        clientMutationId,
        user{
            id,
            verified,
            name,
            displayName
        },
        merchant{
            id,
            name,
            legalName
        }
    }
}

Neste exemplo estamos associando um Merchant ao usuário identificado pelo access_token, que é refletido no campo userId. Os dados retornados após à associação do Merchant ao usuário, serão os que foram definidos na parte inferior da mutation.

Outras interações

Para consultar um usuário basta utilizar uma query de usuário, como no exemplo abaixo.

query {
   user(id: "70fa9e70-1b41-3f68-8df9-b207d76929f6") {
        id,
        username
        cardHolders{
            id
            name
            companyName
        }
    }
}

Para atualizar um usuário basta utilizar a função updateUser, a seguir temos um exemplo de sua utilização. Por questão de segurança o campo id não se refere ao real id do usuário, e sim ao access_token do mesmo.

mutation {  
    updateUser(input:{
        id: "0c9cd95a-365e-40d3-89c2-63c35340a0fa",
        firstName: "firstName changed"
    }) {
        user{
            id
            firstName
        }
    }
}

Neste exemplo estamos atualizando o firstName (primeiro nome) do usuário, porém outros atributos também podem ser atualizados.

Para deletar um usuário basta utilizar a função deleteUser, a seguir temos um exemplo de sua utilização. Por questão de segurança o campo userId não se refere ao real id do usuário, e sim ao access_token do mesmo.

mutation {  
    deleteUser(input:{
        userId: "e29e5d4b-c5f6-45c9-90e0-26b21fed43f9"
    }) {
        userId
        username
        displayName
    }
}

Neste exemplo estamos deletando o usuário com identificação informada no campo userId.

O campo bcryptPassword presente no cadastro de usuário refere-se aos dados sensíveis de acesso do usuário à API. Estes dados são o nome de usuário e senha criptografados usando o algoritmo conhecido como bcrypt. Isso é feito para não se armazenar as senhas no sistema. Os passos para utilização desse algoritmo com os parâmetros requisitados pela API da ELO são descritos abaixo:

1º Passo: Gerar um salt a partir do nome de usuário:

  • Aplicar o algoritmo SHA256 no nome do usuário e reservar os 16 primeiros caracteres.

  • Aplicar a codificação Base64 sobre o resultado do item anterior utilizando o alfabeto customizado do algoritmo bcrypt. O alfabeto utilizado pelo bcrypt utiliza "." ao invés de "+" e começa com "./". Segue abaixo:

    ./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789

  • Concatenar o resultado do item anterior com o texto "$2a$12". Exemplo de resultado:

    $2a$12$N9qo8uLOickgx2ZMRZoMye

2º Passo: Aplicar o algoritmo bcrypt utilizando a senha do usuário e o salt gerado no primeiro passo:

  • Aplicar o algoritmo SHA256 na senha do usuário.

  • Aplicar a codificação Base64 sobre o resultado do item anterior.

  • Aplicar o algoritmo bcrypt utilizando o resultado do item anterior e o salt gerado no primeiro passo.

NOTA: O custo utilizado pelo algoritmo do bcrypt deve ser igual a 12.

Os contatos informados para o usuário durante o cadastro, permanecem com status UNVERIFIED até que seja realizada a confirmação destes através de um verificationCode gerado pelo sistema. Segue abaixo os passos para solicitação do verificationCode e confirmação do contato:

1º Passo: Realizar uma requisição de verificação de contato:

mutation{
  requestContactVerification(input:{
    clientMutationId: "123",
    userId: "",
    type: EMAIL,
    value: "email@provedor.com"
  }) {
    clientMutationId
    user{
      id
      verified
      username
      name
      contacts{
        type
        value
        verified
      }
    }
    contact{
      type
      value
      verified
    }
  }
}

Exemplo da resposta da API:

{
  "data": {
    "requestContactVerification": {
      "clientMutationId": "123",
      "user": {
        "id": "fb9444fb-b9df-3cdd-a83e-808e0ce4b938",
        "verified": "UNVERIFIED",
        "username": "user1",
        "name": "Nome Usuário",
        "contacts": [
          {
            "type": "EMAIL",
            "value": "email@provedor.com",
            "verified": "PENDING"
          }
        ]
      },
      "contact": {
        "type": "EMAIL",
        "value": "email@provedor.com",
        "verified": "PENDING"
      }
    }
  }
}

Após esta etapa, o status de verificação do contato passa para PENDING e o usuário receberá no contato em verificação um verificationCode que deverá ser utilizado no próximo passo.

2º Passo: Efetivar a confirmação de contato:

mutation{
  contactVerification(input:{
    clientMutationId: "456",
    userId: "",
    type: EMAIL,
    value: "email@provedor.com",
    verificationCode: "5QI057"
  })
  {
    clientMutationId
    user{
      id
      verified
      username
      name
      contacts{
        type
        value
        verified
      }
    }
    contact{
      type
      value
      verified
    }    
  }
}

Exemplo da resposta da API:

{
  "data": {
    "contactVerification": {
      "clientMutationId": "456",
      "user": {
        "id": "fb9444fb-b9df-3cdd-a83e-808e0ce4b938",
        "verified": "VERIFIED",
        "username": "user1",
        "name": "Nome Usuário",
        "contacts": {
          {
            "type": "EMAIL",
            "value": "email@provedor.com",
            "verified": "VERIFIED"
          }
        ]
      },
      "contact": {
        "type": "EMAIL",
        "value": "email@provedor.com",
        "verified": "VERIFIED"
      }
    }
  }
}

Ao receber a resposta de sucesso, o contato tem seu status de verificação alterado para VERIFIED. Desta forma, pode-se garantir que o contato do usuário é um contato válido.

Para ter acesso às APIs da Elo o usuário deve possuir um access_token válido e para isso ele deve efetuar login na plataforma. O processo de login pode ser realizado de duas formas: utilizando um nome de usuário e senha via createLoginSalt ou utilizando uma rede social via socialNetworkOAuthLogin.

Veja na figura abaixo os dois exemplos:

login

Caso o usuário queira utilizar o nome de usuário e senha ele primeiro deve fazer uso da chamada createLoginSalt. Essa função retorna um salt que deve ser utilizado para gerar o challenge que será enviado no processo de login (Mais detalhes sobre como obter o challenge seram descritos posteriormente). Um exemplo dessa chamada pode ser vista abaixo.

Exemplo do corpo da requisição:

mutation {
    createLoginSalt(input:{
        username: "UserNameToLogin"
    }) 
    {
        username, 
        salt
    }
}

Exemplo da resposta da API:

{
  "data": {
    "createLoginSalt": {
      "username": "UserNameToLogin",
      "salt": "$2a$05$J/dgZmXIN23mEZtvkxDYeO"
    }
  }
}

Na sequência é necessário fazer uso da chamada login. Esta requisição é necessária para dar acesso ao usuário às demais chamadas da API. Desta forma, no retorno dessa chamada é disponibilizado o access_token que identifica o usuário de forma única.

Exemplo do corpo da requisição:

mutation {
    login(input:{
        clientMutationId: "0123456789",
        username: "UserNameToLogin",
        challenge:"$2a$05$J/dgZmXIN23mEZtvkxDYeOtRsNEY4xMU9HHkcBVMpiUlFSFBuhtxy"
    }) 
    {
        clientMutationId,
        accessToken
    }
}

Exemplo da resposta da API:

{
   "data": {
       "login": {
           "clientMutationId": "0123456789",
           "accessToken": "b64a0e34-24c5-39eb-b457-0c7331d176f0"
       }
   }
}

Caso o usuário queira utilizar uma rede social para se autenticar na API da Elo ele deverá fazer uso da chamada socialNetworkOAuthLogin. Assim como no fluxo descrito anteriormente, no retorno da função também é disponibilizado o access_token que identifica o usuário de forma única.

Exemplo do corpo da requisição:

mutation {
    socialNetworkOAuthLogin(input:{ 
        clientMutationId: "0123456789", 
        provider: "FACEBOOK", 
        username: "user.name@gmail.com",  
        accessToken:"AAECEdEose0cBANynsVcZChZBxB3ysAuxDeZC3ZB4eIzkUKJnvoaTO1Vf4gyj8sl9bFFNPlnGU0Qsnh2fys7gcymWE7lKL64ygGLCJAtgyJtNq4YSGBkdDZBcgnAGZBKaGiI6emZCap8WJYO8ex06ZAZB75IdWnDtPoGCF8yPQnW4JZALHgeL1A1o6ZC5nz5uLD2lnVoUpkxAr1CNQABCD"
    }) 
    {
        clientMutationId,
        accessToken
    }
}

Exemplo da resposta da API:

{
    "data": {
        "login": {
            "clientMutationId": "0123456789",
            "accessToken": "120faef6-5f31-3e74-afb2-864151c52880"
        }
    }
}

O campo challenge presente no login de usuário refere-se ao resultado do desafio (challenge) de login. É um hash utilizando o algoritmo bcrypt com salt (fornecido por createLoginSalt) e o conteúdo sendo o bcryptPassword (especificado em User).

Os passos são os mesmos da geração do bcryptPassword (na criação de usuário), porém com dois passos a mais.

Após gerar o bcryptPassword:

  • Gerar um salt a partir da função createLoginSalt.

  • Aplicar o algoritmo bcrypt utilizando o bcryptPassword e o salt gerado no item anterior.

NOTA: O resultado final deve estar no formato padrão, com prefixo, custo, salt e por fim o valor computado em Base64, totalizando 60 caracteres.

Exemplo de challenge: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy.

Caso um usuário não lembre sua senha e precise fazer o reset, existe um fluxo de Reset de Senha que pode ser feito. O primeiro passo é solicitar o envio de um pedido de reset de senha. Isso é feito através da mutation requestPasswordReset:

mutation {
    requestPasswordReset(input: {
        clientMutationId: "123456",
        legalId: {
            cpf: "12345678900"
        },
        email: "seu.email@provedor.com"
    }) {
        clientMutationId
        maskedEmail
    }
}

Essa mutation pode ser realizada enviando o campo email ou o campo phone, mas nunca ambos. Eles também precisam ser os mesmos contatos enviados no momento do cadastro.

Após isso, será enviado um e-mail ou um SMS para o contato especificado, com um token que será usado para fazer o reset da senha, através da mutation passwordReset:

mutation {
    passwordReset(input: {
        clientMutationId: "1234567",
        legalId: {
            cpf: "12345678900"
        },
        email: "seu.email@provedor.com",
        bcryptPassword: "$2a$12$yOCCL/0cbkvc5Lj/.EfnKeHm3oBPq28rGYbs8ayG8tbRYw4qtXflW",
        token: "C68M59"
    }) {
        clientMutationId
        user {
            id
            verified
            username
            name
            firstName
        }
    }
}

O bcryptPassword enviado nessa mutation precisa ser gerado com o mesmo username do usuário cadastrado e com a nova senha. Para saber como gerar esse campo, ver a seção BcryptPassword.

Para criar um cartão é necessário utilizar a função createCard. Esta requisição é responsável por criar um novo cartão associado ao usuário que o criou. Para poder fazer uso dessa função o usuário deve ser um portador (CardHolder). Abaixo é demonstrado uma visão geral do processo de criação de um cartão.

createCard fluxo1

Um exemplo da utilização do createCard pode ser visto abaixo.

mutation {
    createCard(input: {
        clientMutationId: "123",             
        sensitive:"eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway...",
        holderId: "9e5d64e4-409f-4900-b3b6-28319950fe5b",
        billingAddress: {
            context: "Casa",
            number: 123,
            country: "BRA",
            city: "Campinas",
            state: "São Paulo",
            zip: "1234",
            place: "via"
        }
    })
    {
        clientMutationId,
        card {
            id,
            last4,
            billingAddress{
            context,
            country,
            city
            }
        }
    }
}

Apoś a criação do cartão serão retornados os dados solicitados pelo usuário na parte inferior da mutation.

O campo sensitive é o conteúdo sensível (Número do cartão, Nome do portador, Vencimento, etc) gerado a partir de um processo de assinatura e criptografia, cujo payload foi assinado a partir do uso de uma a chave privada do usuário e na sequência criptografado fazendo uso de uma chave pública do servidor. Mais detalhes desse campo na seção Sensitive.

O campo holderId é o id do CardHolder que foi associado ao usuário. Logo não é o id (access_token) do usuário, e sim do CardHolder associado a ele.

Outras interações

Para consultar cartões utilizando filtros utiliza-se a query cards, abaixo segue um exemplo de utilização.

query {  
    cards(filter:{
        status:ACTIVE
    }) {
        edges{
            node{
                id
                last4
                expiry{
                    month
                    year
                }
            }
        }
    }
}

Neste exemplo estamos buscandos todos os cartões ativos. Outros filtros podem ser aplicados para esta consulta, como também pode ser solicitado outros retornos.

Para consultar cartão por identificador global único é utilizado a consulta node. Abaixo segue um exemplo de utilização.

query {  
    node(id: "b63dcf70-08ae-423f-9459-db580b3d6e95") {
        ... on Card {
            id
            last4
            status {
                status
            }
            bin {
                number
            }
        }
    }
}

Neste exemplo estamos solicitando uma consulta de nó (node) onde o identificador global único refere-se a um cartão. Outras informações de retorno podem ser solicitadas nesta requisição.

Também é possível listar os cartões pela consulta de usuário, como no exemplo abaixo.

query {  
    user {
        cardHolders{
            cards{
                edges{
                    node{
                        id
                        last4
                        expiry{
                            month
                            year
                        }
                    }
                }
            }
        }
    }
}

Nesta requisição estamos listando os cartões de um portador utilizando a query de usuário. Outras informações podem ser solicitadas no retorno desta consulta.

Para atualizar um cartão é utilizado a função updateCard. Abaixo segue um exemplo de utilização.

mutation {
    updateCard(input:{
        holderId: "d6f9605c-8da9-484a-bdb4-3e483db232ee",
        billingAddress:{
            country: "coutnry changed",
            city: "city changed",
            state: "SP changed",
            number: 32,
            place: "place changed"
        }
        status:SUSPENDED
    }) {
        card {
            id
            last4
            expiry{
                month
                year
            }
        }
    }
}

Neste exemplo estamos atualizando algumas informações do endereço de cobrança do cartão e o seu status. O cartão é identificado pelo campo holderId. Outras informações podem ser atualizadas além do endereço e status.

Para deletar um cartão é utilizado a função deleteCard. Abaixo segue um exemplo de utilização.

mutation {
    deleteCard(input:{
        cardId: "c049ac20-084b-46f1-ac03-817e855b5811"
    }) {
        cardId
        last4
        bin {
            number
        }
    }
}

Neste exemplo estamos deletando o cartão identificado pelo campo cardId, e solictando algumas informações do mesmo.

O campo sensitive presente no cadastro de cartão refere-se aos dados sensíveis de um cartão (número do cartão, código de verificação, validade e etc). Estes dados estarão assinados e criptografados para garantir sua segurança.

O primeiro passo na geração deste campo é ter os dados no 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": 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".

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

NOTA: a autorização é feita com os campos csc ou authCode e seus respectivos horários de entrada. Apenas um deles deve ser especificado.

O segundo passo é assinar os dados utilizando JSON Web Signature (JWS) em formato compacto, e utilizando Elliptic Curve (EC) como algoritmo de assinatura.

O terceiro passo é criptografar os dados do passo anterior utilizando a chave pública do servidor, que pode ser obtida a partir da query:

query {
    serverPublicKey {
        key
    }
}

Tal criptografia será realizada utilizando JSON Web Encryption (JWE) em formato compacto, e EC como algoritmo de criptografia.

A estrutura de assinatura e criptografia segue a seguinte ideia:

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

O quarto passo é cadastrar a chave pública do cliente a qual foi utilizada para assinar os dados sensíveis. Desta forma o servidor poderá validar a assinatura do cliente no processo de descriptografia do campo sensitive. Abaixo segue um exemplo da mutation de cadastro de chave pública.

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

NOTA: o quarto passo só é necessário caso a chave pública que assinou os dados sensíveis não tenha sido cadastrada anteriormente.

A carteira é uma forma do usuário organizar seus cartões. Para criar uma carteira utilizando a API da ELO basta que o usuário seja um portador (CardHolder) e faça uso da função CreateWallet. Um exemplo de utilização dessa função pode ser vista abaixo:

mutation { 
    createWallet(
        input: { 
            clientMutationId: "123", 
            cardHolderId: "fdf9f98e-a6ac-4878-ad45-cc133e4ca168", 
            name: "Carteira"
        }
    ) {
        clientMutationId, 
        wallet{ 
            id, 
            name, 
            holder{
                name, 
                firstName, 
                displayName
            }
        }
    }
}

Após a criação da carteira serão retornados seus dados e a partir deles é possível fazer seu gerenciamento adicionando ou removendo cartões. Abaixo temos um exemplo de cada operação possível com a carteira criada.

Adicionar um cartão à carteira:

mutation {
    addCardToWallet(
        input:{
            clientMutationId:"123", 
            walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51", 
            cardId: "2fde85bf-6935-4e9b-8262-94d82e08e4bd"
        }
    ) { 
        clientMutationId, 
        wallet{ 
            id,
            name 
        }, 
        card{
            id
        }
    }
}

Remover cartão de uma carteira:

mutation{
    removeCardFromWallet(
        input:{
            clientMutationId: "012", 
            walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51", 
            cardId: "2fde85bf-6935-4e9b-8262-94d82e08e4bd"}
    ) {
        clientMutationId, 
        wallet{
            name
        }, 
        card{
            id
        }
    }
}

Atualizar a carteira:

mutation{
  updateWallet(
      input: {
          clientMutationId: "123",
          walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51",
          name: "Carteira Principal"
        }
    ) {
        wallet {
            id,
            name
        }
    }
}

NOTA: Só é possível atualizar o nome da carteira.

Remover a carteira:

mutation{
    deleteWallet(
        input:{
            clientMutationId: "012", 
            walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51"
        }
    ) { 
        clientMutationId, 
        walletId, 
        name
    }
}

Termos de Uso podem ser adicionados ao usuário, isso siginifica que o mesmo aceitou tal termo. Para listar os termos de uso basta utilizar a query agreementTerms.

query{
  agreementTerms(filter:{
    nameContains: "",
    agreementTermIds: [
      "",
      ""
    ]
  })
  {
    pageInfo{
      hasPreviousPage
      hasNextPage
    }
    totalCount
    edges{
      cursor
      node{
        id
        title
        description
        url
      }
    }
  }
}

Obs: Filtros podem ser aplicados na consulta de termos de uso, mais detalhes podem ser encontrados no argumento filter AgreementTermFilterInput

Adicionar Termo de Uso ao usuário:

Para adicionar um termo de uso ao usuário utiliza-se a mutation addAgreementToUser.

mutation {
  addAgreementToUser(input: {
    clientMutationId: "012", 
    userId: "b1ca0944-7822-3538-920d-58b233154608", 
    agreementTermId: "e32a7918-eef5-41af-909b-f4c93cee2e22"
  }) {
    clientMutationId
    user {
      id
      username
      firstName
      lastName
      displayName
    }
    agreement {
      agreementTerm {
        id
        title
        description
        url
      }
    }
  }
}

Remover Termo de uso do usuário:

Para remover um termo de uso do usuário utiliza-se a mutation removeAgreementFromUser

mutation {
  removeAgreementFromUser(input: {
    clientMutationId: "013", 
    userId: "b1ca0944-7822-3538-920d-58b233154608", 
    agreementTermId: "e32a7918-eef5-41af-909b-f4c93cee2e22"
  }) {
    user {
      id
      firstName
      lastName
    }
    agreementTerm {
      id
      description
      url
    }
  }
}

Consulta

Consultar dados de portador utilizando a consulta de usuário:

query {
   user(id: "70fa9e70-1b41-3f68-8df9-b207d76929f6") {
        id,
        username
        cardHolders{
            id
            name
            companyName
        }
    }
}

NOTA: o parâmetro id se refere ao access_token do usuário.

Dados de um portador via ID

Consultar o nome, CPF, RG e data de nascimento de um portador dado o identificador global único:

query {
   node(id: "B8B1582B-1C2C-406B-9FC3-ACA842049207") {
      ... on CardHolder {
         firstName
         lastName
         legalIds {
            cpf {
               number
            }
            rg {
               number
               issuerOrganization
               issuerState
               issueDate
            }
         }
         birthday
      }
   }
}

NOTA: o parâmetro id se refere ao identificador global único do portador (CardHolder).

  • Access_token:: Código de acesso disponibilizado pela API após a realização do login e que deve ser utilizado pelo desenvolvedor ao realizar as chamadas aos recursos disponibilizados. Ele é utilizado para validação do acesso e identificação do usuário que está realizando as operações na API.

  • Bcrypt: Algoritmo de criptografia do tipo hash utilizado para segurança de senhas (Wikipedia). No contexto desta API é o resultado do algoritmo bcrypt sobre o nome de usuário e senha.

  • BIN: Número de Identificação do Banco (Bank Identification Number). O BIN é relativo aos números iniciais de um cartão e identifica o emissor e produtos associados ao mesmo.

  • CardIssuer: Um usuário do tipo pessoa jurídica que emite cartões. Também conhecido como Emissor.

  • CardHolder: Um usuário do tipo pessoa física ou jurídica que possui cartões. Também conhecido como Portador.

  • Challenge: Resultado do algoritmo bcrypt aplicado sobre um salt gerado e o bcrypt do nome do usuário e senha.

  • Client_id: Identificador utilizado pela API para verificar e validar qual a aplicação está fazendo uso dos recursos disponibilizados. Sua geração é feita no momento que o desenvolvedor cria uma nova aplicação no portal de desenvolvedores.

  • Merchant: Um usuário do tipo pessoa jurídica que é um estabelecimento comercial e realiza transações com cartões.

  • PAN: Número da conta primária (Primary Account Number), também conhecido como "número do cartão".

  • Salt: Dado gerado de forma aleatório que é usado no algoritmo de criptografia junto da senha como uma forma de proteção evitando que o hash de dois dados iguais gerem o mesmo resultado.

  • Sensitive: Conteúdo sensível (Número do cartão, Nome do portador, Vencimento, etc) gerado a partir de um processo de assinatura e criptografia, cujo payload foi assinado a partir do uso de uma a chave privada do usuário e na sequência criptografado fazendo uso de uma chave pública do servidor.

  • Wallet: Carteira virtual utilizada para organizar cartões criados pelo portador dentro da API da ELO.




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.



Query (consulta) cartões Card

Se executado por um portador de cartão, serão retornados todos os cartões que este possui. O mesmo que consultar os cartões deste portador.

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

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

Argumentos:

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: CardFilterInput

Aplica filtro, se provido.



Query (consulta) portadores de cartões CardHolder

Argumentos:

first: Int

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

after: String

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

last: Int

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

before: String

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

filter: SearchFilterInput

Aplica filtro, se definido.



Query (consulta) de usuário por vários meios de entrada.

Esta consulta deve ser feita com apenas um parâmetro não-null para designar o método de procura. Utilizar mais de um pode resultar em resultados distintos em cada chamada.

Argumentos:

id: String

Procura o usuário pelo identificador global único

username: String

Procura o usuário pelo seu username

legalId: LegalIdsInput

Procura o usuário pelo seu documento

socialNetwork: SocialNetworkInput

Procura o usuário pelo seu username na rede social especificada.

cardHolderId: String

Procura pelo usuário associado ao portador de cartões com o identificador global único especificado.

merchantId: String

Procura pelo usuário associado ao comerciante com o identificador global único especificado.

Caso o comerciante tenha mais de um usuário responsável, retorna o mais antigo.



Lista todos os Termos de uso conhecidos no sistema.

Argumentos:

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: AgreementTermFilterInput

Aplica filtro, se provido.






adiciona um cartão existente à uma carteira digital

Usável por:

  • Portadores de cartão

Argumentos:

input: AddCardToWalletInput obrigatório



remove um cartão existente de uma carteira digital

Usável por:

  • Portadores de cartão

Argumentos:

input: RemoveCardFromWalletInput obrigatório



Cria Carteira Digital para um portador.

Usável por:

  • Portadores de cartão

Argumentos:

input: CreateWalletInput obrigatório



Apaga uma Carteira Digital.

As informações associadas à carteira serão automaticamente apagadas.

Informações que estão sendo utilizadas por outras entidades, como Card ou CardToken ficarão vivas até que não tenham mais referências, sendo coletadas automaticamente.

Usável por:

  • Portadores de cartão (o dono da carteira)

Argumentos:

input: DeleteWalletInput obrigatório



Atualiza (Edita) informações de uma carteira digital.

Cartões e tokens não são manipulados por esta mutação, mas por mutações específicas:

  • addCardToWallet()

  • removeCardFromWallet()

  • createCardToken()

  • suspendCardToken()

Argumentos:

input: UpdateWalletInput obrigatório



Cria um salt para ser utilizado no desafio (challenge) de login().

Com a finalidade de evitar tráfego de senha utilizamos um desafio (challenge) que é baseado em um salt retornado por esta mutação.

O salt retornado será associado ao username e terá validade especificada em expiry.

Argumentos:

input: CreateLoginSaltInput obrigatório



Realiza um novo acesso ao sistema utilizando nome do usuário e senha.

Em caso de sucesso esta chamada retorna a chave de acesso (accessToken), a qual deve ser armazenada e enviada em toda requisição HTTP no cabeçalho access_token. Exemplo (XXXYYYZZZ é o valor retornado neste campo):

GET /graphql HTTP/1.1
...
access_token: XXXYYYZZZ
...

Um novo acesso não desfaz outros acessos existentes, para isto utilize logout() passando a chave de acesso retornada.

Para acesso utilizando redes sociais, utilize socialNetworkOAuthLogin().

NOTA: com a finalidade de evitar tráfego de senha utilizamos um desafio (challenge) que é baseado em um salt obtido com a mutação createLoginSalt(). Logo é necessário iniciar o processo de login() com aquela mutação.

Argumentos:

input: LoginInput obrigatório



Realiza um novo acesso ao sistema utilizando redes sociais (OAuth).

Um novo acesso não desfaz outros acessos existentes, para isto utilize logout() passando a chave de acesso retornada.

Para acesso utilizando usuário e senha, utilize login().

Argumentos:

input: SocialNetworkOAuthLoginInput obrigatório



Cria um usuário.

As informações poderão ser posteriormente alteradas com updateUser() e a imagem com setImage().

Argumentos:

input: CreateUserInput obrigatório



Cadastra um Cartão para um Portador.

O cadastro de um cartão deve ser feito pelo portador ou pelo emissor do cartão, sendo verificado:

  • Portador: se o usuário do sistema é associado ao portador (CardHolder), seja o seu pessoal ou um dos empresariais associados.

  • Emissor: se o emissor é responsável pelo BIN do cartão, obtido à partir do número do cartão (pan) nos campos cifrados sensitive. O emissor deve ter permissão de criar cartões para o portador, conseguindo assim o seu holderId (CardHolder { id }).

Os dados do cartão são inferidos à partir do BIN, ou seja, do prefixo do número do cartão (pan) descrito em sensitive.

Argumentos:

input: CreateCardInput obrigatório



Apaga um cartão

Todas as informações associadas serão automaticamente apagadas.

Informações que estão sendo utilizadas por outras entidades, como CardToken ficarão vivas até que não tenham mais referências, sendo coletadas automaticamente.

Argumentos:

input: DeleteCardInput obrigatório



Atualiza um Cartão de um Portador.

A atualização de um cartão deve ser feita pelo portador ou pelo emissor do cartão, sendo verificado:

  • Portador: se o usuário do sistema é associado ao portador (CardHolder), seja o seu pessoal ou um dos empresariais associados.

  • Emissor: se o emissor é responsável pelo BIN do cartão.

Argumentos:

input: UpdateCardInput obrigatório



Inicia o processo de recuperação de senha para um usuário.

A recuperação de senha é um processo no qual um código de recuperação de senha é enviado para o email ou telefone do usuário, conforme registrado no sistema.

O usuário então acessa um link que apresenta um formulário contendo o código enviado e pedindo a nova senha. Ambos devem ser repassados para a mutação passwordReset().

O processo de recuperação de senha tradicional exige um documento legal, como por exemplo o CPF, e então envia um email com um link que leva para formulário de alteração de senha em nosso sistema.

Porém muitos usuários esquecem do email ou telefone que foram cadastrados e ficam sem saber em qual procurar. Para isso é retornado o meio de contato de forma mascarada, isso é, parcialmente visível de forma a lembrar o usuário sem revelar informações confidenciais e previne utilização do sistema de recuperação de senha para mineração de dados dos usuários. Um email `user@gmail.comficaria mascarado comouxxx@gmail.com, jáfirst.last@company.comficariafxxxx.lxxx@company.com. De maneira similar, um telefone celular+55 (11) 99123-4567seria apresentado como+55 (11) 9xxx3-xx67`.

Outro caso que tratamos é de usuários associados a múltiplos emails e telefones e perderam acesso a eles. Por exemplo uma pessoa tinha cadastrado seu email corporativo e pessoal, porém deixou a empresa e consequentemente perdeu acesso ao email corporativo. Neste caso é oferecida a opção de especificar outro meio de contato, com a restrição que este deverá estar previamente cadastrado no sistema, evitando fraudes.

Adicionalmente, ao invés de utilizar o link para formulário em nosso sistema, pode criar um formulário próprio, pedir a entrada manual da chave de recuperação enviada e realizar a chamada passwordReset().

Argumentos:

input: RequestPasswordResetInput obrigatório



Finaliza o processo de recuperação de senha para um usuário, redefinindo-a.

A recuperação de senha é um processo iniciado pela mutação requestPasswordReset() no qual um código de recuperação de senha é enviado para o email ou telefone do usuário, conforme registrado no sistema.

O usuário então acessa um link que apresenta um formulário contendo o código enviado e pedindo a nova senha. Ambos devem ser repassados para esta mutação, a qual irá alterar a senha salva no sistema.

Em geral essa chama é realizada à partir do formulário em nosso sistema, o qual foi enviado na forma de link para o contato do usuário que deseja recuperar a senha.

Argumentos:

input: PasswordResetInput obrigatório



Apaga um usuário

Todas as informações associadas como portadores, carteiras, contatos, redes sociais, termos aceitos e outros serão automaticamente apagadas.

Informações que estão sendo utilizadas por outras entidades, como Card ou CardToken ficarão vivas até que não tenham mais referências, sendo coletadas automaticamente.

Associações com CardIssuer e Merchant serão automaticamente desfeitas.

Argumentos:

input: DeleteUserInput obrigatório



Configura (altera) os campos do usuário

Para a imagem veja setImage()

Argumentos:

input: UpdateUserInput obrigatório



Adiciona um portador de cartões ao usuário

Um usuário pode ter apenas um portador de cartões para sua pessoa física (campos companyName, companyLegalName sendo null) e os demais deverão conter dados das pessoas jurídicas (companhias).

TODO: notificação (subscription) do evento

Argumentos:

input: CreateCardHolderForUserInput obrigatório



Adiciona um emissor de cartões ao usuário

Um emissor pode ser gerenciado por múltiplos usuários e um usuário pode gerenciar vários emissores.

Caso o emissor já esteja associado, retorna erro.

TODO: notificação (subscription) do evento

Argumentos:

input: AddCardIssuerToUserInput obrigatório



Adiciona um comerciante ao usuário

Um comerciante pode ser gerenciado por múltiplos usuários e um usuário pode gerenciar vários comerciantes.

Caso o comerciante já esteja associado, retorna erro.

TODO: notificação (subscription) do evento

Argumentos:

input: AddMerchantToUserInput 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



Adiciona um termo aceito pelo usuário

Caso o termo já tenha sido aceito anteriormente, retorna erro.

Argumentos:

input: AddAgreementToUserInput obrigatório



Remove um termo aceito pelo usuário

Indica que o usuário não aceita mais os termos. Pode retornar erro caso o termo não possa ser removido.

Argumentos:

input: RemoveAgreementFromUserInput obrigatório






Define limites operacionais para uma moeda.

Campos:

currency

:

String obrigatório

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.



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

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

Campos:

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.



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

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

Campos:

maxUsage

:

Int

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

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


expiry

:

DateTime

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


allowedTxAmounts

:

lista 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

:

lista de ID obrigatório

Lista de comerciantes autorizados.

Se null, é ilimitada.


allowedMerchantCategories

:

lista de MerchantCategoryRangeInput obrigatório

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

Se null, é ilimitada.


deniedMerchantCategories

:

lista de MerchantCategoryRangeInput obrigatório

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

Se null, é ilimitada.



Entrada que filtra cartões a serem retornados

Campos:

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.

NOTA: em cardBrandId só possuí bandeira ELO disponível.


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.



Filtro para pesquisa de CardTokens

Campos:

ip

:

String

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


deviceType

:

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.


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

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



Entrada que filtra tokens a serem retornados

Campos:

status

:

CardStatus

Se não-nula, retorna apenas tokens com dado estado. Exemplo: ACTIVE Se null, retorna tokens em todos os estados.


origin

:

CardTokenOriginFilter

Se não-nula, retorna apenas tokens com a origem igual à especificada em origin. Se null, retorna tokens com quaisquer dados de origem.



Entrada que filtra Seguros Viagem (TravelInsurance) a serem retornados.

Campos:

status

:

CardHolderInsuranceStatus

Se não-nula, retorna apenas seguros com dado estado. Exemplo: ACTIVE. Se null, retorna seguros em todos os estados.


startDate

:

Date

Se não-nula, retorna apenas seguros posteriores à data (inclusive). Se null, retorna até o seguro mais antigo.


endDate

:

Date

Se não-nula, retorna apenas seguros anteriores à data (inclusive). Se null, retorna até o seguro mais recente.


originCountry

:

String

Se não-nula, retorna apenas seguros emitidos para o dado País de Origem da viagem. Se null, retorna seguros para todas as origens.

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


destinationCountry

:

String

Se não-nula, retorna apenas seguros emitidos para o dado País de Destino da viagem. Se null, retorna seguros para todos os destinos.

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



Entrada que filtra Seguros de Garantia Estendida (ExtendedWarrantyInsurance) a serem retornados.

Campos:

status

:

CardHolderInsuranceStatus

Se não-nula, retorna apenas seguros com dado estado. Exemplo: ACTIVE. Se null, retorna seguros em todos os estados.


startDate

:

Date

Se não-nula, retorna apenas seguros posteriores à data (inclusive). Se null, retorna até o seguro mais antigo.


endDate

:

Date

Se não-nula, retorna apenas seguros anteriores à data (inclusive). Se null, retorna até o seguro mais recente.


categoryId

:

ID

Se não-nula, retorna apenas seguros de uma certa categoria de produtos. Se null, retorna seguros de todas as categorias de produtos.

Obtenha lista de categorias com extendedWarrantyProductCategories.



Entrada que filtra Seguros de Proteção de Compra de Produtos (PurchaseSecurityInsurance) a serem retornados.

Campos:

status

:

CardHolderInsuranceStatus

Se não-nula, retorna apenas seguros com dado estado. Exemplo: ACTIVE. Se null, retorna seguros em todos os estados.


startDate

:

Date

Se não-nula, retorna apenas seguros posteriores à data (inclusive). Se null, retorna até o seguro mais antigo.


endDate

:

Date

Se não-nula, retorna apenas seguros anteriores à data (inclusive). Se null, retorna até o seguro mais recente.


categoryId

:

ID

Se não-nula, retorna apenas seguros de uma certa categoria de produtos. Se null, retorna seguros de todas as categorias de produtos.

Obtenha lista de categorias com purchaseSecurityProductCategories.



Entrada que filtra assistências residenciais a serem retornados.

Campos:

id

:

ID obrigatório

Identificador global uníco da assistência.


status

:

HomeAssistenceStatus

Status de assistência residencial.


type

:

HomeAssistenceType

Tipos de assistência residencial.



Campos:

documentType

:

DocumentType

Tipo do documento (CNH, RG).


startDate

:

Date

Data de início a partir de quando foi criado o documento.


endDate

:

Date

Data fim de quando foi criado o documento.


status

:

DocumentStatus

Status do processo de verificação do documento.


validationStatus

:

DocumentValidationStatus

Status da validação do documento.



Entrada que filtra transações a serem retornadas.

Campos:

startTimestamp

:

DateTime

Se não-nula, retorna apenas transações à partir (inclusive) da data e horário dados. Se null, retorna transações até o início dos tempos.


endTimestamp

:

DateTime

Se não-nula, retorna apenas transações até (inclusive) a data e horário dados. Se null, retorna transações até o momento atual.


includeMerchantCategories

:

lista de MerchantCategoryRangeInput obrigatório

Se não-nula e não vazia, especifica série de códigos ISO de categorias a serem incluídas.

Se null ou vazia, não filtra por categoria de comerciantes (MCC).


excludeMerchantCategories

:

lista de MerchantCategoryRangeInput obrigatório

Se não-nula e não vazia, especifica série de códigos ISO de categorias a serem excluídas.

Se null ou vazia, não filtra por categoria de comerciantes (MCC).


status

:

CardTransactionStatus

Se não-nula, retorna apenas transações no dado estado. Se null, retorna transações em qualquer estado.


captureId

:

ID

Se não-nula, retorna apenas transações capturadas pelo dado método Se null, retorna transações capturadas por qualquer método.

Exemplos de método de captura: POS, TEF, Internet...

O id se refere ao CardCapture { id }


usageId

:

ID

Se não-nula, retorna apenas transações com o uso especificado. Se null, retorna transações com qualquer uso.

Exemplos de uso: Débito, Crédito à Vista, Crédito parcelado pela loja...

O id se refere ao CardUsage { id }



Entrada que filtra transações a serem consolidadas retornadas.

Campos:

startTimestamp

:

DateTime

Se não-nula, retorna apenas transações à partir (inclusive) da data e horário dados. Se null, retorna transações até o início dos tempos.


endTimestamp

:

DateTime

Se não-nula, retorna apenas transações até (inclusive) a data e horário dados. Se null, retorna transações até o momento atual.


includeMerchantCategories

:

lista de MerchantCategoryRangeInput obrigatório

Se não-nula e não vazia, especifica série de códigos ISO de categorias a serem incluídas.

Se null ou vazia, não filtra por categoria de comerciantes (MCC).


excludeMerchantCategories

:

lista de MerchantCategoryRangeInput obrigatório

Se não-nula e não vazia, especifica série de códigos ISO de categorias a serem excluídas.

Se null ou vazia, não filtra por categoria de comerciantes (MCC).



Entrada que filtra transações fraudulentas a serem retornadas.

Campos:

cardTransactionId

:

ID

Identificador Global Único para CardTransaction.

O id se refere ao CardTransaction { id }


codeCapture

:

Int

Tipo de Captura cardCapture { code: Int }.


codeUsage

:

Int

Uso do Cartão CardUsage { code: Int }.


legalIds

:

CompanyLegalIdsInput

Os documentos legais para determinar o comerciante (i.e: CNPJ)

Ao menos um documento legal deverá ser especificado para que esta consulta retorne o comerciante.


iso

:

Int

startTimestamp

:

DateTime

Se não-nula, retorna apenas transações fraudulentas à partir (inclusive) da data e horário dados. Se null, retorna transações fraudulentas até o início dos tempos.


endTimestamp

:

DateTime

Se não-nula, retorna apenas transações fraudulentas até (inclusive) a data e horário dados. Se null, retorna transações fraudulentas até o momento atual.



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

Campos:

filter

:

String

TODO: document filter language, something like Google or GMail



Entrada para CompanyLegalIds

Campos:

cnpj

:

String

Número CNPJ sem hífen ou pontos



Entrada para RG

Campos:

number

:

String obrigatório

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



Entrada para LegalIds

Campos:

cpf

:

String

Número CPF sem hífen ou pontos


cnpj

:

String

Número CNPJ sem hífen ou pontos


rg

:

RGInput

documento de Registro Geral (RG)



Entrada com dados básicos para redes sociais.

Campos:

provider

:

String obrigatório

Nome do provedor da rede social, ex: Facebook, Twitter...


username

:

String obrigatório

Nome do usuário na rede social



Entrada para filtragens de busca por termo de uso.

Todos os campos especificados (não-null) são aplicados (comportamento AND), para obter comportamento OR, utilize várias consultas.

Campos:

nameContains

:

String

Se null ou vazio, não realiza filtragem. Caso contrário, define texto que deve estar contido no nome do termo de uso.


agreementTermIds

:

lista de ID obrigatório

Lista de identificadores globais únicos de termos (AgreementTerm) Se null ou vazio, não realiza filtragem.


isWalletDigital

:

Boolean

Realiza o filtro pelos termos de uso, que são referentes a carteira digital. Se o valor informado for "true", somente os termos que forem de carteira digital, serão retornados. Se o valor informado for "false", somente os termos que não forem de carteira digital, serão retornados. Se o atributo não for informado na consulta, serão retornados todos os termos de uso, idenpendente se forem ou não de carteira digital.



Entrada para mutação addCardToWallet().

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.


walletId

:

ID obrigatório

O identificador global da carteira onde se quer adicionar o cartão.


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"

JSON Schema: CardSensitiveInput.json



Entrada para mutação removeCardFromWallet().

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.


walletId

:

ID obrigatório

O identificador global da carteira de onde se quer remover o cartão.


cardId

:

ID obrigatório

O identificador global do cartão a ser removido. Deve ter sido previamente adicionado a carteira.



Entrada para mutação createWallet().

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.


name

:

String obrigatório

Especifica novo nome da carteira.



Entrada para mutação deleteWallet().

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.


walletId

:

ID obrigatório

O identificador global da carteira a ser apagada.

O usuário do sistema deve ter permissão para apagar carteiras do portador da carteira a ser apagada (Wallet { holder }).



Entrada para mutação updateWallet().

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.


walletId

:

ID obrigatório

O identificador global da carteira em que se quer editar informação.


name

:

String obrigatório

Se provido, especifica novo nome da carteira.



Entrada para mutação createLoginSalt().

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.


username

:

String obrigatório

Nome do usuário para acesso ao sistema

Note que o salt sempre será retornado, mesmo que o usuário não exista.



Entrada para mutação login().

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.


username

:

String obrigatório

Nome do usuário para acesso ao sistema


challenge

:

String obrigatório

Resultado do desafio (challenge) de login().

Hash utilizando o algoritmo bcrypt com salt fornecido por createLoginSalt() e conteúdo sendo o bcryptPassword especificado em createUser() ou updateUser(). Código utilizando as bibliotecas crypto e bcrypt com Node.js:

var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs

function sha256AsBase64(data) {
  return crypto.createHash('sha256')
    .update(data)
    .digest('base64');
}

function bcryptSaltFromUsername(username) {
  var hash = crypto.createHash('sha256').update(username).digest();
  return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}

function bcryptUserPassword(username, password) {
  var userSalt = bcryptSaltFromUsername(username);
  return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}

var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);

var challengeSalt = createLoginSalt(username);
var challenge = bcrypt.hashSync(bcryptPassword, challengeSalt);

A String final deve estar no formato padrão, com prefixo, custo, salt e por fim o valor computado em Base64, totalizando 60 caracteres. Por exemplo: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy



Entrada para mutação socialNetworkOAuthLogin().

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.


provider

:

String obrigatório

Nome do provedor da rede social, ex: Facebook, Twitter...


username

:

String obrigatório

Nome de usuário na rede social

NOTA: não confundir com o usuário do sistema User { username }.


accessToken

:

String

Chave de acesso do usuário mantida pelo aplicativo na rede social

NOTA: não confundir com a chave de acesso retornada em LoginPayload por login() ou socialNetworkOAuthLogin().



Entrada com dados extras para redes sociais baseadas em OAuth

Campos:

accessToken

:

String obrigatório

Caso o processo OAuth foi executado com sucesso, contém o código de acesso


refreshToken

:

String

Caso o processo OAuth foi executado com sucesso, contém o código de renovação de acesso


scopes

:

lista de String obrigatório

Caso o processo OAuth foi executado com sucesso, contém os escopos autorizados.


expiryTimestamp

:

DateTime

Caso o processo OAuth foi executado com sucesso, contém a data e horário que o código de acesso (accessToken) expira.



Entrada para renda anual de uma pessoa física.

Campos:

personal

:

Float obrigatório

Renda anual pessoal (individual) da pessoa física.


family

:

Float obrigatório

Renda anual total da família da pessoa física.


currency

:

String obrigatório

Moeda associada aos valores informados.

Código da moeda com 3 letras ISO4217 Exemplo: EUR, USD, BRL...



Entrada para ítem de contato com o portador de cartão, como email ou telefone...

Campos:

type

:

PersonContactType obrigatório

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 obrigatório

Valor do contato. Exemplos: +12345678 para telefone, `user@server.com` para email, etc.



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

Campos:

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 obrigatório

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


city

:

String obrigatório

Nome da cidade em UTF-8


state

:

String obrigatório

Nome do estado por completo.


stateAbbrev

:

String

Nome do estado abreviado (opcional).


zip

:

String

Código postal (opcional).


district

:

String

Distrito opcional


kind

:

String

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


number

:

Int obrigatório

Número da construção


place

:

String obrigatório

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.



Entrada para mutação createUser().

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


username

:

String

Nome do usuário para acesso ao sistema

Pode ser nulo se e somente se for especificado socialNetwork, ou seja, o usuário será criado baseado na rede social.


bcryptPassword

:

String

Hash utilizando o algoritmo bcrypt da senha do usuário.

Os parâmetros para cálculo do hash são:

  • cost: 12

  • salt: os 16 primeiros bytes do Hash utilizando o algoritmo SHA256 do nome do usuário, codificados como base64 utilizando o alfabeto particular do bcrypt.

  • data: a representação Base64 do Hash utilizando SHA256 da senha do usuário. Isto é necessário pois bcrypt tem um limite de 72 caracteres.

Ou seja:

var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs

function sha256AsBase64(data) {
  return crypto.createHash('sha256')
    .update(data)
    .digest('base64');
}


function bcryptSaltFromUsername(username) {
  var hash = crypto.createHash('sha256').update(username).digest();
  return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}

function bcryptUserPassword(username, password) {
  var userSalt = bcryptSaltFromUsername(username);
  return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}

var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);

A String deve ser serializada no formato padrão bcrypt contendo o prefixo, custo, salt e o hash serializado em Base64, totalizando 60 caracteres. Por exemplo: $2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

Pode ser nulo se e somente se for especificado socialNetwork, ou seja, o usuário será criado baseado na rede social.


socialNetwork

:

SocialNetworkInput

Usuário associado a uma rede social.

Contém apenas as informações básicas da rede social (provedor e usuário da rede). Caso seja uma rede social baseada em OAuth, então envie também o campo oauth com as extensões particulares deste protocolo.

Pode ser nulo se e somente se ambos bcryptPassword e username forem especificados, ou seja, o usuário tradicional com nome e senha mantidos no sistema.

Caso username ou bcryptPassword sejam fornecidos em conjunto com socialNetwork, então é similar a criar um usuário e então chamar addSocialNetworkToUser().

Caso bcryptPassword seja nulo a senha será indefinida e a chamada login() não irá funcionar, somente socialNetworkOAuthLogin().

Caso username seja nulo, será gerado um nome de usuário.


oauth

:

SocialNetworkOAuthInput

Usuário associado a uma rede social OAuth.

Caso socialNetwork se refira a uma rede que utiliza o protocolo OAuth, então este campo oferece os dados específicos como accessToken, refreshToken, scopes e expiryTimestamp.


name

:

String obrigatório

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

:

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

:

lista de PersonContactInput obrigatório

Contatos do usuário


addresses

:

lista de AddressInput obrigatório

Endereços postais



Entrada para mutação createCard().

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


sensitive

:

String obrigatório

Conteúdo sensível (número do cartão, código de verificação e validade) 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: 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

O número do cartão (pan) será utilizado para descoberta dos demais campos do cartão, como availableServices, bin, funding, product, isInternational, isCompany, isToken, brand, allowedCaptures, usages, network, issuer e metadata.


holderId

:

ID obrigatório

Identificador global único do portador do cartão (CardHolder { id }).

Note que o usuário do sistema deve ter permissão para criar cartões para este portador, ou seja:

  • Portador: se o usuário do sistema é um portador, deve ser o seu CardHolder { id } da pessoa física ou uma pessoa jurídica associado.

  • Emissor: se o portador autorizou a criação de cartões.


billingAddress

:

AddressInput

Endereço de cobrança do cartão.


usageConstraints

:

CardUsageConstraintsInput

Restrições de uso do cartão.

Caso indisponível ou sem restrições, usar null.



Entrada para mutação deleteCard().

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 obrigatório

Identificador global único do cartão a apagar



Entrada para mutação updateCard().

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.


holderId

:

ID obrigatório

Identificador global único do cartão (Card { id }).

Note que o usuário do sistema deve ter permissão para atualizar:

  • Portador: se o usuário do sistema é um portador, deve ser o seu CardHolder { id } da pessoa física ou uma pessoa jurídica associado.

  • Emissor: se é responsável pelo BIN do cartão.


billingAddress

:

AddressInput

Endereço de cobrança do cartão.

Se null, não será alterado.


usageConstraints

:

CardUsageConstraintsInput

Restrições de uso do cartão.

Se null, não será alterado.


status

:

CardStatus

Estado do cartão.

Se null, não será alterado.



Entrada para mutação requestPasswordReset().

Ao menos um documento, email ou telefone devem ser utilizados para identificar o usuário no sistema.

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.


legalId

:

LegalIdsInput obrigatório

Documento do usuário o qual deseja recuperar a senha

Pode-se especificar apenas um documento, por exemplo apenas o CPF ou CNPJ.


email

:

String

Email do usuário o qual deseja recuperar a senha.

Caso seja fornecido e esteja cadastrado no sistema será o meio utilizado para envio da chave para recuperação de senha, conforme exigido em passwordReset().


phone

:

String

Telefone do usuário o qual deseja recuperar a senha.

Caso seja fornecido e esteja cadastrado no sistema será o meio utilizado para envio da chave para recuperação de senha, conforme exigido em passwordReset().


type

:

PersonContactType

Tipo do contato no qual será enviado o TOKEN para realizar o reset da senha.

O TOKEN só será enviado ao contato, caso o mesmo tenha sido validado anteriormente.

NOTA: apenas os tipos de contatos PHONE e EMAIL são verificáveis.



Entrada para mutação passwordReset().

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.


legalId

:

LegalIdsInput obrigatório

Documento do usuário o qual deseja recuperar a senha

Este campo deve conter os mesmos valores passados por RequestPasswordResetInput para requestPasswordReset().


email

:

String

Email do usuário o qual deseja recuperar a senha.

Este campo deve conter o mesmo valor passado por RequestPasswordResetInput para requestPasswordReset().


phone

:

String

Telefone do usuário o qual deseja recuperar a senha.

Este campo deve conter o mesmo valor passado por RequestPasswordResetInput para requestPasswordReset().


token

:

String obrigatório

A chave de recuperação de senha enviada por email ou telefone após o processo iniciado com requestPasswordReset().


bcryptPassword

:

String obrigatório

Hash utilizando o algoritmo bcrypt da nova senha do usuário.

Os parâmetros para cálculo do hash são:

  • cost: 12

  • salt: os 16 primeiros bytes do Hash utilizando o algoritmo SHA256 do nome do usuário, codificados como base64 utilizando o alfabeto particular do bcrypt.

  • data: a representação Base64 do Hash utilizando SHA256 da senha do usuário. Isto é necessário pois bcrypt tem um limite de 72 caracteres.

Ou seja:

var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs

function sha256AsBase64(data) {
  return crypto.createHash('sha256')
    .update(data)
    .digest('base64');
}


function bcryptSaltFromUsername(username) {
  var hash = crypto.createHash('sha256').update(username).digest();
  return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}

function bcryptUserPassword(username, password) {
  var userSalt = bcryptSaltFromUsername(username);
  return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}

var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);

A String deve ser serializada no formato padrão bcrypt contendo o prefixo, custo, salt e o hash serializado em Base64, totalizando 60 caracteres. Por exemplo: $2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy



Entrada para mutação deleteUser().

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 apagar



Entrada para mutação updateUser().

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

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.


id

:

ID obrigatório

Identificador global único referente ao usuário a ser modificado


username

:

String

Nome do usuário para acesso ao sistema

Caso null, não será alterado


name

:

String

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

Caso null, não será alterado


firstName

:

String

Primeiro nome do usuário

Caso null, não será alterado


lastName

:

String

Último nome do usuário

Caso null, não será alterado


displayName

:

String

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

Caso null, não será alterado


legalIds

:

LegalIdsInput

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

Caso null, não será alterado

Caso não-null então deverá conter todos os documentos, isto permite remover documentos, mantê-los ou então adicionar novos em uma única entrada.


birthday

:

Date

Data de nascimento

Caso null, não será alterado


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais

Caso null, não será alterado


maritalStatus

:

MaritalStatus

Estado civil

Caso null, não será alterado


income

:

PersonYearlyIncomeInput

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

Caso null, não será alterado


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.

Caso null, não será alterado


contacts

:

Contatos do usuário

Caso null, não será alterado

Caso não-null então deverá conter todos os contatos, isto permite remover contatos, mantê-los ou então adicionar novos em uma única entrada.


addresses

:

lista de AddressInput

Endereços postais

Caso null, não será alterado

Caso não-null então deverá conter todos os endereços, isto permite remover endereços, mantê-los ou então adicionar novos em uma única entrada.



Entrada para mutação createCardHolderForUser().

Um usuário pode ter apenas um portador de cartões para sua pessoa física (campos companyName, companyLegalName sendo null) e os demais deverão conter dados das pessoas jurídicas (companhias).

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 que terá um portador associado


companyName

:

String

Nome da empresa, caso portador de cartões corporativos.

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. Note que apenas um portador de cartões pessoa física existirá para o usuário.


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. Note que apenas um portador de cartões pessoa física existirá para o usuário.


companylegalIds

:

CompanyLegalIdsInput

Documentos legais de identificação da empresa.

Para cartões de pessoa física será sempre null. Note que apenas um portador de cartões pessoa física existirá para o usuário.



Entrada para mutação addCardIssuerToUser().

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 que será associado ao emissor


cardIssuerId

:

ID obrigatório

Identificador global único do emissor de cartões



Entrada para mutação addMerchantToUser().

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 que será associado ao comerciante


merchantId

:

ID obrigatório

Identificador global único do comerciante



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

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 que aceitou o termo


agreementTermId

:

ID obrigatório

Identificador global único do termo aceito


timestamp

:

DateTime

Quando o termo foi aceito. Se null então gerado automaticamente.



Entrada para mutação removeAgreementFromUser().

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 o qual não aceita mais o termo.


agreementTermId

:

ID obrigatório

Identificador global único do termo previamente aceito






PageInfo compatível com Relay.

Campos:

hasPreviousPage

:

Boolean obrigatório

hasNextPage

:

Boolean obrigatório

startCursor

:

String

endCursor

:

String


Validade do cartão: Mês e Ano

Campos:

month

:

Int obrigatório

Mês - Janeiro é 1, Dezembro é 12


year

:

Int obrigatório

Ano - 4 dígitos, exemplo: 2017, não 17.



CNPJ: Cadastro Nacional Pessoas Jurídicas

Campos:

number

:

String obrigatório

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



CPF: Cadastro Pessoa Física

Campos:

number

:

String obrigatório

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



RG: documento de Registro Geral

Campos:

number

:

String obrigatório

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



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

Campos:

cnpj

:

CNPJ

cpf

:

CPF

rg

:

RG


Renda anual de uma pessoa física (individual e familiar).

Campos:

personal

:

Float

Renda anual pessoal (individual) da pessoa física.


family

:

Float

Renda anual total da família da pessoa física.


currency

:

String

Moeda associada aos valores informados.

Código da moeda com 3 letras ISO4217 Exemplo: EUR, USD, BRL...



Profissão (ocupação) de uma pessoa física.

Campos:

id

:

ID obrigatório

Identificador opaco da Profissão

Deve ser informado como entrada em mutações que precisam de profissão.


display

:

String obrigatório

Texto a ser exibido ao usuário em formulários e consultas.

Este texto é localizado (traduzido) para a linguagem informada na consulta.



URL de imagem com tamanho e mimeType.

Campos:

url

:

String obrigatório

URL para acessar a imagem


width

:

Int obrigatório

largura em pixels


height

:

Int obrigatório

altura em pixels


mimeType

:

String obrigatório

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



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

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

Campos:

type

:

PersonContactType obrigatório

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 obrigatório

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.



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

Campos:

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 obrigatório

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


city

:

String obrigatório

Nome da cidade em UTF-8


state

(


abbrev:

Boolean

)

:

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


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 obrigatório

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.



Carteira digital (Digital Wallet)

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String obrigatório

Nome da carteira


holder

:

CardHolder obrigatório

Nome e contato do portador


cards

(


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:

CardFilterInput

Aplica filtro, se provido.

)

:

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.



Conexão de Card em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

Conexão de Card em conformidade com o Relay.


edges

:

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



Conexão de CardToken em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

_t("CardTokensConnection")


edges

:

lista de CardTokensEdge

_t("CardTokensConnection.edges")


totalCount

:

Int

_t("CardTokensConnection.totalCount")



Conexão de TravelInsurance em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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.



_("ExtendedWarrantyInsurancesConnection")

Campos:

pageInfo

:

PageInfo obrigatório

_("ExtendedWarrantyInsurancesConnection.pageInfo")


edges

:

_("ExtendedWarrantyInsurancesConnection.edges")


totalCount

:

Int

_("ExtendedWarrantyInsurancesConnection.totalCount")



Conexão de PurchaseSecurityInsurance em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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.



Conexão de HomeAssistence em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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.



Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

lista de DocumentsEdge

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.



Portador de cartão

Usualmente uma pessoa

Campos:

id

:

ID obrigatório

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


income

:

PersonYearlyIncome

Renda anual do portador (individual e familiar).

Este campo é informacional e pode ser utilizado no preenchimento de formulários de outros serviços, por exemplo para emissão de seguros.


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

Este campo é informacional e pode ser utilizado no preenchimento de formulários de outros serviços, por exemplo para emissão de seguros.

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

:

lista de PersonContact obrigatório

Contatos do portador de cartão


addresses

:

lista de Address obrigatório

Endereço postal


wallets

:

lista de Wallet obrigatório

Carteiras em posse deste portador de cartão.


cards

(


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:

CardFilterInput

Aplica filtro, se provido.

)

:

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.


cardTokens

(


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:

CardTokenFilterInput

Aplica filtro, se provido.

)

:

CardTokensConnection

_t("CardHolder.cardTokens")


travelInsurances

(


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:

TravelInsuranceFilter

Aplica filtro, se provido.

)

:

TravelInsurancesConnection

Seguros Viagem relacionados ao portador.

Lista todos os seguros viagem relacionados ao portador utilizando paginação e um filtro opcional.

A ordem da listagem é do mais recente para o mais antigo.

Opcionalmente pode-se utilizar o filter para selecionar apenas seguros ativos, expirados, cancelados e limitar a um certo intervalo de datas.


extendedWarrantyInsurances

(


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:

ExtendedWarrantyInsuranceFilter

Aplica filtro, se provido.

)

:

ExtendedWarrantyInsurancesConnection

Seguros de Garantia Estendida relacionados ao portador.

Lista todos os seguros de extensão de garantia de produtos relacionados ao portador utilizando paginação e um filtro opcional.

A ordem da listagem é do mais recente para o mais antigo.

Opcionalmente pode-se utilizar o filter para selecionar apenas seguros ativos, expirados, cancelados e limitar a um certo intervalo de datas.


purchaseProtectionInsurances

(


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:

PurchaseProtectionInsuranceFilter

Aplica filtro, se provido.

)

:

PurchaseProtectionInsurancesConnection

Seguros de Proteção de Compra relacionados ao portador.

Lista todos os seguros de proteção de compra de produtos relacionados ao portador utilizando paginação e um filtro opcional.

A ordem da listagem é do mais recente para o mais antigo.

Opcionalmente pode-se utilizar o filter para selecionar apenas seguros ativos, expirados, cancelados e limitar a um certo intervalo de datas.


homeAssistences

(


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:

HomeAssistenceFilter

Aplica filtro, se provido.

)

:

HomeAssistencesConnection

Assistência residencial solicitadas pelo portador.

Lista todas as Assistências residencias relacionadas ao portador utilizando paginação e um filtro opcional.

A ordem da listagem é do mais recente para o mais antigo.

Opcionalmente pode-se utilizar o filter para selecionar assistências pelo seu status, tipo ou ID.


documents

(


first:

Int

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

after:

String

, 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:

DocumentsFilterInput

Aplica filtro, se provido.

)

:

DocumentConnection

Query (consulta) documentos enviados para verificação



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

Campos:

cursor

:

String obrigatório

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


node

:

Card

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



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

Campos:

id

:

ID obrigatório

sensitive

(


keyId:

String

)

:

String

last4

:

String

expiry

:

CardExpiry

holder

:

CardHolder

billingAddress

:

Address

status

:

CardStatusInterface obrigatório

usageConstraints

:

CardUsageConstraints

availableServices

:

lista de CardHolderService obrigatório

usedServices

:

lista de CardHolderService obrigatório

bin

:

BIN

funding

:

CardFunding

product

:

CardProduct

isInternational

:

Boolean

isCompany

:

Boolean

isToken

:

Boolean

cardTokens

:

CardTokensConnection

Retorna uma conexão para os tokens relacionados a esse cartão


brand

:

CardBrand

allowedCaptures

:

lista de CardCapture obrigatório

usages

:

lista de CardUsage obrigatório

network

:

CardNetwork

issuer

:

CardIssuer

metadata

:

CardMetadata

trackings

:

lista de Track

Só será retornado os dados caso seja um CardIssuer realizando a consulta, caso outro tipo de usuário faça essa consulta o campo deve retornar vazio.


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.

)

:

lista de CardTransactionCategorySummary obrigatório

fraudTransactions

(


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:

CardFraudTransactionFilterInput

Aplica filtro, se provido. Consulta as transações fraudulentas que já foram processadas. Apenas Card Issuer pode realizar essas consulta.

)

:

CardFraudTransactionsConnection

queueFraudTransactions

(


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:

CardFraudTransactionFilterInput

Aplica filtro, se provido. Consulta as transações fraudulentas que estão na fila de processamento. Apenas Card Issuer pode realizar essas consulta.

)

:

CardFraudTransactionsConnection


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

:

lista de CardHolderService obrigatório

usedServices

:

lista de CardHolderService obrigatório

bin

:

BIN

funding

:

CardFunding

product

:

CardProduct

isInternational

:

Boolean

isCompany

:

Boolean

isToken

:

Boolean

brand

:

CardBrand

allowedCaptures

:

lista de CardCapture obrigatório

usages

:

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

)

:

lista de CardTransactionCategorySummary obrigatório

card

:

Card

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

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


origin

:

CardTokenOrigin

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



_t("CardTokensEdge")

Campos:

cursor

:

String obrigatório

_t("CardTokensEdge.cursor")


node

:

CardToken

_t("CardTokensEdge.node")



Seguro de Viagem para portadores de cartão ou dependentes.

Cada instância de seguro viagem é correspondente a uma chamada de createTravelInsurance(), atrelada a um portador de cartões e o BIN que oferece tal serviço (benefício), além de ter um viajante associado (o segurado) e uma lista de beneficiários.

Para viagens com múltiplos viajantes, um seguro de viagem deve ser emitido para cada viajante, ou seja, uma chama de createTravelInsurance() para cada viajante, resultando em um TravelInsurance para cada um.

Campos:

id

:

ID obrigatório

cardHolder

:

CardHolder obrigatório

O Portador, segurado primário da viagem.

O serviço (benefício) de seguro de viagem é oferecido para determinados produtos (i.e: Cartões Elo Nanquim) ao portador do cartão e extensível a demais segurados que viajarão em conjunto.

Em caso de viagem com múltiplos viajantes, o cardHolder será o mesmo, porém os dados do viajante (traveler) listados neste seguro serão referentes ao viajante segurado.


bin

:

BIN obrigatório

merchant

:

MerchantInsurance

Informações do comerciante.


journey

:

Journey obrigatório

Dados da Viagem.


startDate

:

Date obrigatório

A data inicial da cobertura.

A data inicial é computada automaticamente como a data de emissão do seguro.


endDate

:

Date obrigatório

A data final da cobertura.

A data final é computada automaticamente à partir da data da nota fiscal (invoiceDate) acrescida dos dias da proteção escolhidos (securityDays).


companyInsurance

:

String obrigatório

Seguradora responsável pelo seguro.



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

Campos:

cursor

:

String obrigatório

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


node

:

TravelInsurance

O objeto TravelInsurance que compõe esta aresta de conexão.



Seguro de Garantia Estendida para portadores de cartão.

Campos:

id

:

ID obrigatório

insuranceId

:

ID obrigatório

Identificador Global Único de Seguro contratado, retornado pela seguradora.


cardHolder

:

CardHolder obrigatório

bin

:

BIN obrigatório

status

:

CardHolderInsuranceStatus obrigatório

merchant

:

MerchantInsurance

Informações do comerciante.


startDate

:

Date obrigatório

A data inicial da cobertura.

A data inicial é computada automaticamente como a data de emissão do seguro.


endDate

:

Date obrigatório

A data final da cobertura.

A data final é computada automaticamente à partir da data da nota fiscal (invoiceDate) acrescida dos meses de garantia do fabricante (manufacturerWarrantyMonths) e então dos meses estendidos com este seguro (extendedWarrantyMonths).


companyInsurance

:

String

Seguradora responsável pelo seguro.


invoiceNumber

:

String

Número da Nota Fiscal


invoiceDate

:

Date

Data da Nota Fiscal


serialNumber

:

String

Número de Série do Produto


category

(


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.

)

:

ExtendedWarrantyProductCategory

Categoria do Produto

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.


brand

:

String

Marca do Produto


model

:

String

Modelo do Produto


description

:

String

Descrição do Produto


value

:

Float

Valor do Produto


extendedWarrantyMonths

:

Int

Número de meses estendidos por este seguro.


manufacturerWarrantyMonths

:

Int

Número de meses cobertos pela garantia do fabricante.



_("ExtendedWarrantyInsurancesEdge")

Campos:

cursor

:

String obrigatório

_("ExtendedWarrantyInsurancesEdge.cursor")


node

:

ExtendedWarrantyInsurance

_("ExtendedWarrantyInsurancesEdge.node")



Seguro de Proteção de Compra de Produtos para portadores de cartão.

Campos:

id

:

ID obrigatório

insuranceId

:

ID obrigatório

Identificador Global Único de Seguro contratado, retornado pela seguradora.


cardHolder

:

CardHolder obrigatório

merchant

:

MerchantInsurance

Informações do comerciante.


bin

:

BIN obrigatório

status

:

CardHolderInsuranceStatus obrigatório

startDate

:

Date obrigatório

A data inicial da cobertura.

A data inicial é computada automaticamente como a data de emissão do seguro.


endDate

:

Date obrigatório

A data final da cobertura.

A data final é computada automaticamente à partir da data da nota fiscal (invoiceDate) acrescida dos dias da proteção escolhidos (securityDays).


companyInsurance

:

String obrigatório

Seguradora responsável pelo seguro.


invoiceNumber

:

String obrigatório

Número da Nota Fiscal


invoiceDate

:

Date obrigatório

Data da Nota Fiscal


serialNumber

:

String

Número de Série do Produto


category

(


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.

)

:

PurchaseProtectionProductCategory

Categoria do Produto

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.


brand

:

String obrigatório

Marca do Produto


model

:

String obrigatório

Modelo do Produto


description

:

String obrigatório

Descrição do Produto


value

:

Float obrigatório

Valor do Produto


coverageDays

:

Int

Número de dias o qual o produto será protegido (segurado).



Aresta de conexão contendo um PurchaseSecurityInsurance em conformidade com o

Relay.

Campos:

cursor

:

String obrigatório

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


node

:

PurchaseProtectionInsurance

O objeto PurchaseSecurityInsurance que compõe esta aresta de conexão.



Dados da assistência residencial solicitada.

Campos:

id

:

ID obrigatório

Identificador global uníco da assistência.


openedAt

:

DateTime obrigatório

Data de quando foi realizado a solicitação do atendimento.


updatedAt

:

DateTime

Data da ultima atualização na solicitação.


cardHolder

:

CardHolder obrigatório

bin

:

BIN obrigatório

status

:

HomeAssistenceStatus obrigatório

Status da solicitação.


type

:

HomeAssistenceType obrigatório

Tipo de assistência


address

:

Address obrigatório

Endereço para prestar a assistência.


person

:

PersonType obrigatório

Dados do contato responsável por atender o prestador.


providerAssistence

:

ProviderAssistence

Dados do prestador de serviço responsável pelo atendimento.


description

:

String obrigatório

Descrição do atendimento.



_t("HomeAssistencesEdge")

Campos:

cursor

:

String obrigatório

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


node

:

HomeAssistence

O objeto HomeAssistence que compõe essa aresta conexão.



Representa a imagem de um documento enviado para verificação.

Campos:

id

:

ID obrigatório

Identificador único do documento.


documentType

:

DocumentType obrigatório

Tipo do documento (CNH, RG).


status

:

DocumentStatus obrigatório

Status do processo de verificação do documento.


validationStatus

:

DocumentValidationStatus obrigatório

Status da validação do documento.


createdAt

:

DateTime obrigatório

Data de criação do documento na API.


updatedAt

:

DateTime

Data da última atualização do documento.


cpf

:

DocumentCpf

Dados obtidos a partir do documento.


message

:

String

Mensagem relevante do processo de verificação. Geralmente preenchido em caso de erro.



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

Campos:

cursor

:

String

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


node

:

Document

O objeto Document que compõe esta aresta de conexão.



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.

Campos:

maxUsage

:

Int

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

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


expiry

:

DateTime

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


allowedTxAmounts

:

lista de CardCurrencyRange 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.


allowedMerchants

:

lista de Merchant obrigatório

Lista de comerciantes autorizados.

Se null, é ilimitada.


allowedMerchantCategories

:

lista de MerchantCategory obrigatório

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

:

lista de MerchantCategory obrigatório

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.



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.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String obrigatório

Nome do serviço


description

:

String

Descrição do serviço


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


discounts

:

Discounts

Percentual de descontos



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.

Campos:

number

:

String obrigatório

panSizeRange

:

IntRange obrigatório

funding

:

CardFunding obrigatório

product

:

CardProduct obrigatório

country

:

String obrigatório

isInternational

:

Boolean obrigatório

regexp

:

String obrigatório

isCompany

:

Boolean obrigatório

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 obrigatório

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.

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 obrigatório

Bandeira do Cartão

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


allowedCaptures

:

lista obrigatória de CardCapture obrigatório

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

:

lista obrigatória de CardUsage obrigatório

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 obrigatório

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 obrigatório

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 obrigatório

Metadados para apresentação do cartão ao usuário.

Metadados 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

:

lista obrigatória de CardHolderService obrigatório

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.


creditSettlementBankNumber

:

Int

Número do Banco liquidante da operação de Crédito

Indica qual o código do banco deverá ser utilizado para liquidar operações de crédito.

API Privada


debitSettlementBankNumber

:

Int

Número do Banco liquidante da operação de Crédito

Indica qual o código do banco deverá ser utilizado para liquidar operações de crédito.

API Privada



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

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


code

:

CodeProduct obrigatório

Código que identifica produto.


name

:

String obrigatório

Nome do produto.

Exemplos de Produtos Elo:

  • Básico

  • Clássico

  • Corporativo

  • Grafite

  • Nanquim

  • Viagem

  • Pré-pago


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



Bandeira (marca) do cartão

A bandeira do cartão atualmente retorna Elo.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String obrigatório

Nome da bandeira


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



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)

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String obrigatório

Nome da Captura


code

:

Int obrigatório

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:

  • OUTROS = 0

  • POS = 1

  • TEF = 2

  • INTERNET = 3

  • TELEMARKETING = 4

  • ATM = 5

  • E-COMMERCE = 7

  • CONTA CARTÃO ARMAZENADA = 10

  • CONTACTLESS = 81

  • MOBILE COMMERCE (MCOMMERCE) = 82

  • CONTACTLESS = 83

  • FALLBACK = 85

  • CONTACTLESS = 86

  • TARJA TOTAL = 90

  • VOICE RESPONSE UNIT (VRU) / (URA) = 91

  • BATCH DE AUTORIZAÇÕES = 92

  • BATCH DE AUTORIZAÇÕES CASH ACCESS = 91

  • CARTÃO COM CHIP SEM TRATAMENTO CVV = 95



Uso de um Cartão.

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

  • Crédito à Vista

  • Débito

  • Parcelado pela loja

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String obrigatório

Nome do Uso


code

:

Int obrigatório

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



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.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String obrigatório

Nome da Rede

Exemplos para Elo:

  • Elo para cartões domésticos;

  • Elo-Discovery para cartões internacionais.


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



Entidade do Emissor de Cartão

Campos:

id

:

ID obrigatório

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

image

(


width:

Int

height:

Int

mimeType:

String

)

:

ImageUrl

legalIds

:

CompanyLegalIds obrigatório

contacts

:

lista obrigatória de CompanyContact obrigatório

addresses

:

lista obrigatória de Address obrigatório

url

:

String

cards

(


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:

CardFilterInput

Aplica filtro, se provido.

)

:

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.



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

Campos:

image

(


width:

Int

height:

Int

mimeType:

String

)

:

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



Dados utilizado no embolssing.

Campos:

type

:

TrackType obrigatório

key

:

String obrigatório

value

:

String obrigatório


Conexão de CardTransaction em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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.



Sumário de Transações de Cartão para uma Categoria de Comerciante

Campos:

category

:

MerchantCategory obrigatório

Categoria deste sumário


count

:

Int obrigatório

Número de transações nesta categoria


value

:

String obrigatório

Valor total das transações em BRL (R$) nesta categoria



Conexão de CardFraudTransaction em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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.



Declara limites operacionais para uma moeda.

Campos:

currency

:

String obrigatório

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.



Um estabelecimento comercial que realiza transações com cartões Elo.

Campos:

id

:

ID obrigatório

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

image

(


width:

Int

height:

Int

mimeType:

String

)

:

ImageUrl

legalIds

:

CompanyLegalIds obrigatório

contacts

:

lista obrigatória de CompanyContact obrigatório

addresses

:

lista obrigatória de Address obrigatório

url

:

String

categories

:

lista obrigatória de MerchantCategory obrigatório

Categorias de comerciantes (Código ISO, nome)


transactionFees

:

lista de MerchantTransactionFees obrigatório

Preços de Transações efetivos para o Comerciante

As taxas e custos são associados a um uso (i.e: Crédito à vista, Crédito parcelado pela loja...), quantidade de parcelas e tem uma validade, ou seja, são dinâmicos. Devem ser consultados e posteriormente refrescados para este comerciante.

Alguns comerciantes têm valores negociados individualmente para seu CNPJ, estes são retornados preferencialmente. No entanto a maioria dos comerciantes não tem negociação individual, para estes vale os valores da categoria (MerchantCategory), o qual é retornado na ausência dos valores negociados individualmente.

Note que se o comerciante não estiver na base de dados ou não for possível determinar sua categoria será retornado null. Para estes casos deve-se, então, utilizar os preços estabelecidos para a sua categoria procurando diretamente por merchantCategory(iso: X) { transactionFees }.

Os custos são dinâmicos: foram alterados em MerchantTransactionFees { lastModified } e são vigentes até MerchantTransactionFees { expiry }. O usuário deve usar expiry para invalidar o cache local, refrescando as informações após tal data e horário.


cardTransactions

(


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

Consulta transações deste comerciante.

A consulta paginada permite obter transações feitas por este comerciante com um filtro opcional.

Ao ser chamado por um CardHolder (portador), apenas suas transações com este comerciante serão exibidas (filtro implícito).

Para transações de um cartão específico, utilize CardInterface { transactions }, primeiramente obtendo o Card ou CardToken por outras consultas, por exemplo cardInterfaceByHash(hash)

Pode ser null em caso de falta de permissão, por exemplo outro comerciante.



Categoria de comerciantes

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

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto.


iso

:

Int obrigatório

Código ISO18245.

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


name

(


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.

)

:

String obrigatório

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

(


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


transactionFees

:

lista de MerchantTransactionFees obrigatório

Preços de Transações para a Categoria de Comerciante.

As taxas e custos são associados a um uso (i.e: Crédito à vista, Crédito parcelado pela loja...) e tem uma validade, ou seja, são dinâmicos e podem ser consultados para esta categoria.

Note que alguns comerciantes possuem custos de transação específicos, negociados individualmente. Para estes deve-se consultar o comerciante e então seus preços diretamente via API com merchant(legalIds: {cnpj: X}) { transactionFees }, utilizando os valores da categoria aqui retornados apenas para comerciantes sem preços específicos.

Os custos são dinâmicos: foram alterados em MerchantTransactionFees { lastModified } e são vigentes até MerchantTransactionFees { expiry }. O usuário deve usar expiry para invalidar o cache local, refrescando as informações após tal data e horário.


merchants

(


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:

SearchFilterInput

Aplica filtro, se provido.

)

:

MerchantsConnection

Consulta comerciantes (Merchant) nesta categoria.



Informa o percentual de descontos (ex: 100% de desconto, 50% de desconto, ou se não tem desconto)

Campos:

holderOrAdditional

:

Int

Percentual de desconto aplicado para o portador ou adicional.


companion

:

Int

Percentual de desconto aplicado ao acompanhante.



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.

Campos:

min

:

Int obrigatório

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


max

:

Int obrigatório

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



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

Campos:

cnpj

:

CNPJ


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

Campos:

type

:

CompanyContactType obrigatório

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 obrigatório

Valor do contato. Exemplos: +12345678 para telefone, `user@server.com` para email, etc.



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

Campos:

cursor

:

String obrigatório

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


node

:

CardTransaction

O objeto CardTransaction que compõe essa aresta conexão.



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

Campos:

cursor

:

String obrigatório

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


node

:

CardFraudTransaction

O objeto CardFraudTransaction que compõe essa aresta conexão.



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

Campos:

lon

:

Float obrigatório

Longitude, mandatório: em graus.


lat

:

Float obrigatório

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



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.

Campos:

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



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

TODO: Review in depth

Campos:

timestamp

:

DateTime obrigatório

Quando o token foi criado


ip

(


ipv6Mapped:

Boolean

)

:

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.



Campos:

legalId

:

String obrigatório

Documento Legal (CNPJ ou CPF) que identifica o comerciante.

Apenas dígitos, sem hífen ou pontos.


name

:

String obrigatório

Nome Fantasia do Comerciante


legalName

:

String obrigatório

Razão Social do Comerciante



Trechos da vigem (Possíveis escalas).

Campos:

tripNumber

:

Int

Identificador Global Único do trecho da viagem.


tripLocator

:

String

Número de Confirmação.


type

:

TripType

Identifica o tipo de viagem.


departure

:

Layover

Informações da saída da escala.


arrival

:

Layover

Informações da chegada da escala.


travelers

:

lista obrigatória de TravelInsuranceTraveler obrigatório

Dados do(s) Viajante(s) a qual este seguro se refere.

Para emissão de seguro informar os dados de todos os viajantes, informe todos os campos obrigatórios.



Propósito (Motivo) da Viagem

Campos:

leisure

:

Boolean obrigatório

Se true, um dos propósitos da viagem é lazer.


business

:

Boolean obrigatório

Se true, um dos propósitos da viagem é negócios.


adventure

:

Boolean obrigatório

Se true, um dos propósitos da viagem é realizar atividades de aventura.

Atividades de aventura ou perigosas, tais como andar a cavalo, jet ski, bungee jump, rafting, canoagem ou ciclismo.



Dados da viagem.

Campos:

companyTravel

:

String

Companhia responsável pela viagem.


journeyLocator

:

String

Número de Confirmação.


trips

:

lista obrigatória de Trip obrigatório

Trechos da vigem (Possíveis escalas).


purpose

:

TravelPurpose

Propósito da viagem (lazer, negócios...)



Produto coberto pelo seguro

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto.


display

:

String obrigatório

Texto a ser exibido ao usuário em formulários e consultas.



Categoria de Produtos para Seguros de Garantia Estendida

Campos:

id

:

ID obrigatório

Identificador opaco da categoria de produto.

Deve ser informado como entrada quando a categoria for requisitada.


display

:

String obrigatório

Texto a ser exibido ao usuário em formulários e consultas.

Este texto é localizado (traduzido) para a linguagem informada na consulta ou mutação


products

:

lista obrigatória de ProductCategory obrigatório

Produto segurado.



_t("PurchaseProtectionProductCategory")

Campos:

id

:

ID obrigatório

_t("PurchaseProtectionProductCategory.id")


display

:

String obrigatório

_t("PurchaseProtectionProductCategory.display")


products

:

lista obrigatória de ProductCategory obrigatório

Produto segurado.



Dados para contato da pessoa responsável em receber o prestador.

Campos:

name

:

String obrigatório

Nome de contato no momento do atendimento


contacts

:

lista obrigatória de PersonContact obrigatório

Contatos



Campos:

legalId

:

String obrigatório

Documento Legal (CNPJ ou CPF) que identifica o comerciante.

Apenas dígitos, sem hífen ou pontos.


name

:

String obrigatório

Nome Fantasia do Comerciante


legalName

:

String obrigatório

Razão Social do Comerciante



Dados do Prestador.

Campos:

name

:

String obrigatório

Nome do prestador.


code

:

String obrigatório

Codigo de identificação do prestador.


legalIds

:

LegalIds

Todos os documentos legais de identificação de empresas ou pessoas.


contacts

:

lista obrigatória de PersonContact obrigatório

Contatos do prestador


geolocation

:

Geolocation

Dados de geolocalização do prestador.


merchant

:

MerchantAssistence

Informações do comerciante.



Campos:

number

:

String

Número do CPF (Pode contém formatação).


name

:

String

Nome da pessoa.


birthday

:

Date

Data de nascimento.


death

:

String

Ano do óbito.


status

:

String

Status do registro do documento.


issuedAt

:

String

Data de registro do documento.



Retorno do cálculo de custo final em BRL (R$) a ser pago para uma transação.

Veja a consulta MerchantTransactionFees { calc } para detalhes do cálculo.

Campos:

cardUsage

:

CardUsage obrigatório

Os custos de transação se referem a este uso.

Por exemplo:

  • Crédito à vista = 70

  • Débito = 71

  • Crédito parcelado pela loja = 72

É o mesmo que MerchantTransactionFees { cardUsage }, retornado aqui apenas para facilitar o uso.


expiry

:

DateTime

Data e horário que limitam a vigência do valor, ou seja.

É o mesmo que MerchantTransactionFees { expiry }, retornado aqui apenas para facilitar o uso.


installments

:

Int obrigatório

Número de parcelas considerado.

Caso o uso (cardUsage) se não permita parcelamento, será retornado 1.

Caso o uso (cardUsage) permita parcelamento, porém o parâmetro de cálculo seja fora da faixa, será retornado o número de parcelas que melhor se aproxima. Por exemplo:

  • calc(installments: 10) e installmentsRange {min: 1, max: 5} irá retornar installments: 5.

  • calc(installments: 3) e installmentsRange {min: 6, max: 12} irá retornar installments: 6.

Caso o número de parcelas especificadas para o cálculo esteja dentro da faixa, então será retornado o valor especificado, inalterado.


totalCost

:

Float obrigatório

Valor final a ser pago em tarifas para a transação, em BRL (R$).

É equivalente à soma dos demais custos..


processingCost

:

Float obrigatório

Tarifa de processamento na mensageria de autorizações, em BRL (R$).

Este valor é fixo para este uso (cardUsage), independente do valor ou número de parcelas.

É o mesmo que MerchantTransactionFees { processingCost }, retornado aqui apenas para facilitar o uso.


installmentsCost

:

Float obrigatório

Tarifa adicional por parcelamento, em BRL (R$).

Este valor resulta do additionalInstallmentCost aplicado a cada parcela adicional.

Para cardUsage que não permite parcelamento, será retornado zero (0.0).


marketingCost

:

Float obrigatório

Valor a ser pago para a tarifa de desenvolvimento da bandeira e marketing, em BRL (R$).

Valor final já calculado à partir do transactionValue e marketingFee, considerando marketingFeeCeilValue.


acquiringServiceCost

:

Float obrigatório

Valor a ser pago para desenvolvimento e suporte de produtos ao credenciador, em BRL (R$).

Valor final já calculado à partir do transactionValue e acquiringServiceFee, considerando acquiringServiceFeeCeilValue.



Custos de Transação ao Comerciante.

Baseado no tipo de uso (i.e: Crédito à vista, Crédito parcelado pela loja...) e número de parcelas o comerciante terá que pagar uma taxa à bandeira e ao credenciador. Recomenda-se que o usuário sempre considere cardUsage, installmentsRange e expiry em todas as consultas.

Exemplo de listagem:

  • cardUsage: 70, installmentsRange: null.

  • cardUsage: 71, installmentsRange: null.

  • cardUsage: 72, installmentsRange { min: 1, max: 6 }.

  • cardUsage: 72, installmentsRange { min: 7, max: 12 }.

Os custos são dinâmicos: foram alterados em lastModified e são vigentes até expiry. O usuário deve usar expiry para invalidar o cache local, refrescando as informações após tal data e horário.

O cálculo do valor final a ser pago é feito e esclarecido na consulta calc.

Campos:

cardUsage

:

CardUsage obrigatório

Os custos de transação se referem a este uso.

Por exemplo:

  • Crédito à vista = 70

  • Débito = 71

  • Crédito parcelado pela loja = 72

Note que para produtos parcelados, como 72, serão retornadas diversas entradas com o mesmo cardUsage, porém com faixas de parcelamento diferentes em installmentsRange. Por exemplo se as tarifas para parcelamento de 1 à 6 são diferentes que parcelamentos de 7 à 12, então teríamos duas entradas com o mesmo cardUsage, sendo que cada uma terá installmentsRange diferente:

  • cardUsage: 72, installmentsRange { min: 1, max: 6 }.

  • cardUsage: 72, installmentsRange { min: 7, max: 12 }.


installmentsRange

:

IntRange

A faixa de parcelas a qual estes custos de transação se referem.

Para cardUsage que permite parcelamento, será retornado a faixa de parcelas a qual estes custos se aplicam. Por exemplo se as tarifas para parcelamento de 1 à 6 são diferentes que parcelamentos de 7 à 12, então teríamos duas entradas com o mesmo cardUsage, sendo que cada uma terá installmentsRange diferente:

  • cardUsage: 72, installmentsRange { min: 1, max: 6 }.

  • cardUsage: 72, installmentsRange { min: 7, max: 12 }.

Para cardUsage que não permite parcelamento, será retornado null.


lastModified

:

DateTime obrigatório

Data e horário da última modificação.


expiry

:

DateTime

Data e horário que limitam a vigência do valor, ou seja.


marketingFee

:

Float obrigatório

Percentual a ser pago para a tarifa de desenvolvimento da bandeira e marketing.

Caso marketingFeeCeilValue seja não-nulo, então especifica um teto em BRL (R$) pra limitar o valor final a ser pago.


marketingFeeCeilValue

:

Float

Teto do custo da tarifa de desenvolvimento da bandeira e marketing, em BRL (R$).

Caso seja não-nulo, após aplicar marketingFee ao valor da compra deve-se limitar o valor final em BRL (R$) ao montante especificado.


acquiringServiceFee

:

Float obrigatório

Percentual a ser pago para desenvolvimento e suporte de produtos ao credenciador.

Caso acquiringServiceFeeCeilValue seja não-nulo, então especifica um teto em BRL (R$) pra limitar o valor final a ser pago.


acquiringServiceFeeCeilValue

:

Float

Teto do custo da tarifa de desenvolvimento e suporte de produtos ao credenciador da transação, em BRL (R$).

Caso seja não-nulo, após aplicar acquiringServiceFee ao valor da compra deve-se limitar o valor final em BRL (R$) ao montante especificado.


processingCost

:

Float obrigatório

Tarifa de processamento na mensageria de autorizações, em BRL (R$).

Este valor é fixo para este uso (cardUsage), independente do valor ou número de parcelas.


additionalInstallmentCost

:

Float

Tarifa adicional para cada parcela, em BRL (R$).

Para uso parcelado, por exemplo cardUsage 72 (crédito parcelado pela loja), cada parcela deve pagar este custo adicional.

Ou seja, para uma compra em 3 parcelas, paga-se 2 * additionalInstallmentCost.

Para cardUsage que não permite parcelamento, será retornado null.


calc

(


transactionValue:

Float obrigatório

Valor da transação a calcular o custo final, em BRL (R$).

installments:

Int

Número de parcelas da transação.

Para pagamentos à vista (cardUsage 70 ou 71), será desconsiderado.

Se omitido, será considerado 1 (pagamento à vista).

)

:

MerchantTransactionFeesCalc obrigatório

Calcula o custo final em BRL (R$) a ser pago para uma transação de transactionValue realizada em installments parcelas com o uso retornado no campo cardUsage.

Esta consulta é um utilitário que calcula:

let marketingCost = transactionValue * marketingFee;
if (marketingFeeCeilValue && marketingCost > marketingFeeCeilValue) {
   marketingCost = marketingFeeCeilValue;
}

let acquiringServiceCost = transactionValue * acquiringServiceFee;
if (acquiringServiceFeeCeilValue && acquiringServiceCost > acquiringServiceFeeCeilValue) {
   acquiringServiceCost = acquiringServiceFeeCeilValue;
}

let installmentsCost = 0.0;
if (installments && installments > 1) {
   installmentsCost = (installments - 1) * additionalInstallmentCost;
}

let totalCost = processingCost + installmentsCost + marketingCost + acquiringServiceCost;


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

Campos:

cursor

:

String obrigatório

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


node

:

Merchant

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



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

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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



Campos:

currency

:

String

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


balance

:

String

Saldo disponivel.



Representa uma transação de cartão.

As transações são retornadas em consultas derivadas (enraizadas) em outros tipos mais específicos, tais como:

  • CardInterface { transactions }: transações de um cartão específico.

  • Merchant { cardTransactions }: transações de um dado comerciante.

Todas as consultas são sujeitas às permissões de acesso:

  • Um comerciante (Merchant) não tem permissão para transações de outros comerciantes.

  • Um portador (CardHolder) não tem permissão para transações de outros portadores.

As consultas também são filtradas implicitamente pelas permissões de acesso, ou seja:

  • Um comerciante ao consultar as transações de um dado cartão, só receberá em retorno suas próprias transações e não de outros comerciantes.

  • Um portador ao consultar as transações de um dado comerciante, só receberá em retorno suas próprias transações e não de outros portadores.

O acesso direto via node(id) também é sujeito às mesmas permissões, só entidades relacionadas (comerciante ou portador) podem ter acesso à transação.

Ao Implementador: internamente guarde o hash do cartão (Card) ou token (CardToken) (não os retorne em consulta direta). Ao fazer a busca por CardInterface { transactions }, caia sempre para o mesmo código, à partir do hash (utilizando o valor armazenado internamente).

Para Merchant, sempre faça a o filtro conter a lista merchants com apenas o seu próprio id.

Se utilizar Cassandra ou NoSQL, precisa desnormalizar a tabela em:

  • Por hash;

  • Por MerchantId (comerciante);

  • Por MCC (código da categoria). Como comerciantes têm no mínimo 1 MCC, pode-se fazer como compound key de MCC, MerchantId. Ao listar o comerciante liste todos os seus MCC... em geral vai ser apenas 1. Neste caso não precisa desnormalizar por Merchant, apenas MCC, MerchantId

Para encadear consultas, como no caso de CardHolder descrito acima, cuidado com paginação. Se fizer numa consulta só, a paginação deve vir de "graça".

Campos informativos são altamente repetidos e não precisam estar nas tabelas desnormalizadas. Apenas referencie o id e então mantenha um cache local. Por exemplo CardCapture, CardUsage e BIN.

Caso replique os campos informativos, não os atualize com atualizações no campo original, seria até mais correto manter o snapshot do momento em que a transação foi registrada. Por exemplo o BIN poderia ser associado a um produto naquele momento e o BIN foi reciclado, utilizando outro produto.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto.


capture

:

CardCapture obrigatório

Como o cartão foi capturado na transação (i.e: POS, TEF, Internet...)


usage

:

CardUsage

Como o cartão foi utilizado (i.e: Crédito à vista, Débito...)


bin

:

BIN

Informações do BIN do cartão.

BIN (Bank Identification Number ou Número de Identificação do Banco) elucida várias propriedades do cartão, como se é corporativo, internacional, se é um token, qual o emissor (CardIssuer), dentre outros.

Pode ser null em caso de falta de permissão.


merchant

:

Merchant

O comerciante que realizou a transação.

Possui campos como razão social, nome fantasia, documentos legais (CNPJ) e categorias (MCC).


currency

:

String obrigatório

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


value

:

String obrigatório

Valor total da transação

A moeda é especificada em currency. A compra pode ter sido parcelada conforme installments.


installments

:

Int obrigatório

Número de parcelas.

Caso a compra não tenha sido parcelada, será 1.


status

:

CardTransactionStatus

Estado da transação


timestamp

:

DateTime obrigatório

Quando a transação ocorreu.


approvalCode

:

String

Código de autorização do emissor.


prePaid

:

PrePaid

Informação do saldo disponivel. Retorno apenas para cartão pré-pago



Dados da autorização de uma transação

Campos:

date

:

DateTime obrigatório

Data da autorização da transação.


code

:

ID obrigatório

Código da autorização da transação.


decision

:

String obrigatório

Descrição da autorização da transação.



Representa uma transação fraudulenta de cartão.

Campos:

cardTransaction

:

CardTransaction obrigatório

Dados da Transação fraudulenta.


last4

:

String

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


authorization

:

Authorization obrigatório

Dados da autorização


status

:

CardFraudTransactionStatus obrigatório

Estado da transação fraudulenta


reference

:

String

Número de referência do Banknet.


codePos

:

ID obrigatório

Código que identifica o PDV.


liability

:

LiabilityType

Identifica o responsável pela transação fraudulenta.


codeEic

:

Int obrigatório

Identificar o código 3D Secure específico aplicável.


flaggedAt

:

DateTime

Data que o cartão foi cancelado após ser confirmado como fraude pelo titular do cartão.


arn

:

Int obrigatório

Número de referença do adquirente, são 23 números unicos que marcam a transação do cartão quando ela vai da processadora para o emissor. Somente esta disponivel para transações finalizadas. Esta campo é util para estabelecimentos comerciais para fazer o de-para do alerta como a transação original, especialmente quando existem multiplas transações no mesmo cartão e no mesmo estabelecimento comercial com o mesmo valor e na mesma hora.


initiated

:

InitiatedType obrigatório

Identificar quem detectou a fraude.


settled

:

Date obrigatório

Data que a transação foi liquidada (se já liquidada).



Informações da escala.

Campos:

IataCode

:

String

IATA - Associação Internacional de Transportes Aéreos

Caso o tipo da viagem seja aérea, esse campo deve ser informado.

Exemplo: GRU - Guarulhos/SP


IcaoCode

:

String

ICAO ou OACI - Organização da Aviação Civil Internacional

Exemplo: SBGR - Guarulhos/SP


city

:

String obrigatório

Nome da Cidade.


country

:

String obrigatório

País da viagem. Código do país com 3 letras (ISO3166-alpha3). Exemplos: USA, BRA...


dateTime

:

DateTime obrigatório

Data e hora da escala. Seguindo o formato estendido ISO 8601: Exemplo: "2017-06-01T12:00:00-03:00"



Viajante do Seguro Viagem

Campos:

insurances

:

lista de InsuranceTraveler obrigatório

Lista de Seguro viagem contratados.


legalIds

:

InsuranceLegalIds obrigatório

Todos os documentos legais de identificação do viajante.


name

:

String obrigatório

Nome completo do viajante como no documento oficial (CPF).


birthday

:

Date obrigatório

Data de nascimento.


gender

:

Gender obrigatório

Masculino ou Feminino, conforme documentos oficiais.


pregnancyWeeks

:

Int

Se feminino e estiver grávida, de quantas semanas.

Se masculino ou não estiver grávida, será null.


maritalStatus

:

MaritalStatus obrigatório

Estado civil.


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

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.


income

:

PersonYearlyIncome

Renda anual do viajante (individual e familiar).


address

:

Address obrigatório

Endereço do viajante.


contacts

:

lista de PersonContact obrigatório

Contatos do viajante.


politicalExposure

:

Boolean obrigatório

Pessoa Exposta Politicamente.



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

Campos:

cursor

:

String obrigatório

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


node

:

CardHolder

O objeto CardHolder que compõe esta aresta de conexão.



Conexão de CardHolder em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

lista de CardHoldersEdge

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.



Dados de Seguro viagem contratados para viajante.

Campos:

insuranceId

:

ID obrigatório

Identificador Global Único de Seguro contratado, retornado pela seguradora.


description

:

String obrigatório

Descrição do Produto


status

:

CardHolderInsuranceStatus obrigatório


Toda a possível identificação legal de pessoa Física

Campos:

cpf

:

CPF obrigatório

rg

:

RG


Termo de Uso

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


title

:

String obrigatório

Título deste termo


description

:

String

Descrição do termo


url

:

String

Endereço da Página com informações sobre o termo


isWalletDigital

:

Boolean

Identifica se o termo de uso é referente a carteira digital ou não.



Termo de uso aceito pelo usuário

Campos:

agreementTerm

:

AgreementTerm obrigatório

O termo que foi aceito


timestamp

:

DateTime obrigatório

Quando o termo foi aceito



Chave de acesso (accessToken) e informações sobre sua origem.

Campos:

accessToken

:

String obrigatório

A chave de acesso (accessToken) ativa para este usuário


timestamp

:

DateTime obrigatório

Quando a chave de acesso (accessToken) foi criada


ip

(


ipv6Mapped:

Boolean

)

:

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 da chave de acesso.


geolocation

:

Geolocation

Localização geográfica de onde partiu a solicitação de criação da chave de acesso (accessToken). Pode ser aproximada à partir do IP.

Pode ser null.


device

:

Device

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



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


fingerprint

:

String obrigatório

Fingerprint da chave utilizando o algoritmo de hash requerido.

Se nenhum algoritmo for especificado, será usado SHA256.



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

:

lista de PersonContact obrigatório

Contatos do usuário


addresses

:

lista de Address obrigatório

Endereços postais


cardHolders

:

lista 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

:

lista de Merchant obrigatório

Comerciantes associados ao usuário

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

Relação: n:n


cardIssuers

:

lista 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

:

lista de SocialNetworkInterface obrigatório

Redes sociais relacionadas ao usuário


agreements

:

lista de UserAgreement obrigatório

Termos de uso aceitos pelo usuário


accessTokens

:

lista de AccessTokenInfo obrigatório

Lista de chaves de acesso ativas para este usuário


publicKeys

:

lista de PublicKey obrigatório

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



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

Campos:

cursor

:

String obrigatório

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


node

:

AgreementTerm

O objeto AgreementTerm que compõe esta aresta de conexão.



Conexão de AgreementTerms em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

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


edges

:

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.



Retorno da mutação addCardToWallet().

Compatível com Relay.

Campos:

clientMutationId

:

String

wallet

:

Wallet

A carteira onde o cartão foi adicionado, ou null em caso de erro.


card

:

Card

O cartão adicionado, ou null em caso de erro.



Retorno da mutação removeCardFromWallet().

Compatível com Relay.

Campos:

clientMutationId

:

String

wallet

:

Wallet

A carteira de onde o cartão foi removido, ou null em caso de erro.


card

:

Card

O cartão removido, ou null em caso de erro.



Retorno da mutação createWallet().

Compatível com Relay.

Campos:

clientMutationId

:

String

wallet

:

Wallet

A carteira criada ou null em caso de erro.


holder

:

CardHolder

O portador que recebeu a carteira ou null em caso de erro.



Retorno da mutação deleteWallet().

Compatível com Relay.

Campos:

clientMutationId

:

String

walletId

:

ID

O identificador global único da carteira apagada ou null em caso de erro.


name

:

String

O nome da carteira apagada ou null em caso de erro.


holder

:

CardHolder

O portador o qual teve a carteira apagada ou null em caso de erro.



Retorno da mutação updateWallet().

Compatível com Relay.

Campos:

clientMutationId

:

String

wallet

:

Wallet

A carteira onde a informação foi editada, ou null em caso de erro.



Retorno da mutação createLoginSalt()

Compatível com Relay.

Campos:

clientMutationId

:

String

username

:

String obrigatório

Nome do usuário para acesso ao sistema.

Mesmo que fornecido para createLoginSalt().


salt

:

String obrigatório

Valor a ser utilizado no desafio (challenge) de login().

Note que este salt terá validade especificada em expiry, ao chegar na data e horário definidos o salt não será mais válido.

O valor de salt inclui um prefixo (i.e: $2a) seguido do número de iterações a serem feitas, também referido como custo (cost) ou saltRounds -- i.e: $10, seguido de $ e 22 caracteres representando a Base64 dos 128 bits com o real salt, totalizando 29 caracteres. É o formato utilizado pela maioria das bibliotecas. Exemplo: $2a$10$XDIZcWCyQ1dlF24wQplooO


expiry

:

DateTime obrigatório

Data e horário de validade do salt.



Retorno das mutações login() ou socialNetworkOAuthLogin().

Compatível com Relay.

Campos:

clientMutationId

:

String

accessToken

:

String

A chave de acesso (accessToken) de identificação do usuário. Deve ser armazenada e enviada em toda requisição HTTP no cabeçalho access_token. Exemplo (XXXYYYZZZ é o valor retornado neste campo):

GET /graphql HTTP/1.1
...
access_token: XXXYYYZZZ
...


Retorno da mutação createUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

id

:

ID obrigatório

Identificador Global Único para este usuário


name

:

String

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



Retorno da mutação createCard().

Compatível com Relay.

Campos:

clientMutationId

:

String

card

:

Card

O cartão criado e associado ao portador.

Note que o portador pode ser consultado em Card { holder }.



Retorno da mutação deleteCard().

Compatível com Relay.

Campos:

clientMutationId

:

String

cardId

:

ID obrigatório

Identificador global único do cartão apagado


last4

:

String

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

Pode ser nulo dependendo de permissões e acesso.


expiry

:

CardExpiry

Data de validade do cartão

Pode ser nulo dependendo de permissões e acesso.


holder

:

CardHolder

Nome e contato do portador do cartão

Pode ser nulo dependendo de permissões e acesso.


bin

:

BIN

Informações do BIN do cartão.

BIN (Bank Identification Number ou Número de Identificação do Banco) elucida várias propriedades do cartão, por exemplo banco emissor, uso, metadados (imagens) e afins.

Pode ser null em caso de falta de permissão.



Retorno da mutação updateCard().

Compatível com Relay.

Campos:

clientMutationId

:

String

card

:

Card

O cartão atualizado.



Retorno da mutação requestPasswordReset().

Compatível com Relay.

Campos:

clientMutationId

:

String

maskedEmail

:

String

Retorna versão mascarada do email que receberá a chave de recuperação de acesso.

Esta informação permite ao usuário distinguir dentre vários emails que podem estar cadastrados no sistema e identificar qual deverá verificar a chave. Por exemplo um usuário tem cadastrado os seguintes emails:

O mascaramento de emails permitirá identificar qual foi enviado:

Pode ser nulo caso o código tenha sido enviado para um telefone, neste caso verifique maskedPhone


maskedPhone

:

String

Retorna versão mascarada do telefone que receberá a chave de recuperação de acesso.

Esta informação permite ao usuário distinguir dentre vários telefones que podem estar cadastrados no sistema e identificar qual deverá verificar a chave. Por exemplo um usuário tem cadastrado os seguintes telefones:

  • +55 (11) 99123-4567

  • +55 (21) 99999-1234

O mascaramento de telefones permitirá identificar qual foi enviado:

  • +55 (11) 9xxx3-xx67

  • +55 (21) 9xxx9-xx34

Pode ser nulo caso o código tenha sido enviado para um email, neste caso verifique maskedEmail



Retorno da mutação passwordReset().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

Em caso de sucesso contém o usuário o qual teve sua senha alterada.

Em caso de falha, como por exemplo um token inválido ou senha fora dos padrões determinados, será retornado null.



Retorno da mutação deleteUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

userId

:

ID obrigatório

Identificador global único do usuário apagado


username

:

String obrigatório

Nome do usuário apagado


name

:

String

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


firstName

:

String

Primeiro nome do usuário apagado


lastName

:

String

Último nome do usuário apagado


displayName

:

String

Nome de exibição do usuário apagado



Retorno da mutação updateUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário modificado com os novos campos



Retorno da mutação createCardHolderForUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual criou um portador de cartões associado.


cardHolder

:

CardHolder

O portador o qual foi criado para o usuário.



Retorno da mutação addCardIssuerToUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual foi associado ao emissor


cardIssuer

:

CardIssuer

O emissor o qual foi associado ao usuário



Retorno da mutação addMerchantToUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual foi associado ao comerciante


merchant

:

Merchant

O comerciante o qual foi associado ao usuário



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

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual aceitou o termo


agreement

:

UserAgreement

O aceite e suas informações como agreementTerm e timestamp



Retorno da mutação removeAgreementFromUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual não aceita mais o termo


agreementTerm

:

AgreementTerm

O termo previamente aceito e que já não consta mais em User { agreements }






Node compatível com Relay.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto



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

Campos:

status

:

CardStatus obrigatório

O estado



Interface comum às Redes Sociais

Campos:

provider

:

String obrigatório

Nome do provedor da rede social, ex: Facebook, Twitter...


username

:

String obrigatório

Nome de usuário na rede social





Estado do cartão

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


Valores possíveis:


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




Financiamento do cartão: crédito, débito, múltiplo, Alimentação e Refeição.


Valores possíveis:


CREDIT

Cartão de Crédito


DEBIT

Cartão de Débito


MULTIPLE

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


MEAL

Cartão de benefícios (Refeição)


FOOD

Cartão de benefícios (Alimentação)




Opções de gênero


Valores possíveis:


FEMALE


MALE




Opções de estado civil


Valores possíveis:


DIVORCED

Divorciado


MARRIED

Casado


SINGLE

Solteiro


WIDOWED

Viúvo


COMMON_LAW_MARRIED

União estável




Tipo de contato com pessoa física.


Valores possíveis:


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




Estados de verificação.

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


Valores possíveis:


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.




Estado do Seguro

As transições de estado de um seguro são:

  • RECEIVED

  • HIRED

  • CANCELED


Valores possíveis:


RECEIVED

Solicitação de contratação do seguro foi registrada.


HIRED

Seguro contratado.


CANCELED

Seguro cancelado e não está mais vigente.




Status de assistência residencial.


Valores possíveis:


SERVICE_REQUESTED

Solicitação enviada.


TO_BE_CONFIRMED

Aguardando agendamento.


CONFIRMED

Confirmado


PROVIDER_UNDER_WAY

Prestador em deslocamento.


PROVIDER_ON_SERVICE

Prestador em atendimento.


COMPLETED

Concluido




Tipos de assistência residencial.


Valores possíveis:


PLUMBER

Encanador


LOCKSMITH

Chaveiro


ELECTRICIAN

Eletrecista


GLAZIER

Vidraceiro




Tipos de documento de identificação.


Valores possíveis:


CNH

Carteira de motorista.


RG

RG.




Status de processamento.


Valores possíveis:


ERROR

Erro na verificação do documento. Vide campo Document.message para mais detalhes.


PENDING

Documento recebido. Pendente de envio para verificação.


PROCESSING

Verificação do documento em andamento.


PROCESSED

Verificação do documento concluída.




Status da validação do documento.


Valores possíveis:


NOT_VALIDATED

Documento não validado.


VALID

Documento válido.


INVALID

Documento inválido.




Código que identifica produto. Pode ser adicionados novos registros nessa lista. Exemplos de Produtos Elo:


Valores possíveis:


BASIC

  • BÁSICO


BUSINESS

  • EMPRESARIAL


CORPORATE

  • CORPORATIVO


ELO_PLUS

  • ELO MAIS


SHOPPING

  • COMPRAS


GRAFITE

  • GRAFITE


NANQUIM

  • NANQUIM


AWARDS

  • PREMIAÇÃO


CORPORATE_EXPENDITURE

  • DESPESAS CORPORATIVAS


TRAVEL

  • VIAGEM


CORPORATE_NANQUIM

  • CORPORATIVO NANQUIM


GRAFITE_BUSINESS

  • EMPRESARIAL GRAFITE


PAYMENT_OF_SUPPLIERS

  • PAGAMENTO DE FORNECEDORES


GENERAL_USE

  • USO GERAL


GIFT_CARD

  • GIFT CARD


PAYMENTS

  • PAGAMENTOS


ELO_PLUS_ENTERPRISE

  • EMPRESARIAL ELO MAIS


PREPAID_ENTERPRISE

  • PRÉ PAGO EMPRESARIAL


NANQUIM_CORPORATE_DINERS

  • CORPORATIVO NANQUIM DINERS




Tipo de filtro para trilha do cartão.


Valores possíveis:


SELLER

Vendedor




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.


Valores possíveis:


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.




Tipo de contato com a empresa.


Valores possíveis:


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




Estado da Transação feita por Comerciante via Facilitador


Valores possíveis:


APPROVED

Aprovada


REJECTED

Negada


RETURNED

Desfeita


REFUNDED

Estornada ou Cancelada


CHARGEBACK

TODO Confirmar ??? senão unificar com Facilitadores PSPTransactionStatus




Define a origem de uma informação geolocalizada.


Valores possíveis:


USER

Preenchimento manual pelo usuário


CELLULAR

Adquirido da rede celular.


WIFI

Adquirido da rede WiFi.


GPS

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




Estado da Transação fraudulenta


Valores possíveis:


RECEIVED

Recebida


IN_PROGRESS

Em processamento


PROCESSED

Processada


COMPLETED

Concluido




Identifica se o emissor ou o comerciante é responsável pela transação fraudulenta.


Valores possíveis:


YES

Issuer is liable


NO

Merchant is liable


NOT_APPLICABLE

Not Applicable




Identificar se o emissor ou o portador de cartão detectou a fraude.


Valores possíveis:


CARD_ISSUER

Emissor


CARD_HOLDER

Portador




Indicador do tipo de viagem. Pode ser adicionados novos registros nessa lista. Valores possíveis:


Valores possíveis:


AIR

  • Viagem Aérea


SEA

  • Viagem Marítima


ROAD

  • Viagem Terrestre.




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


Valores possíveis:


PEM

Privacy Enhanced Mail PEM


X509

Certificado X.509




Algoritmo de hash de dados.

Especifica qual algoritmo utilizar para processar os dados originais de tamanho variável e retornar dado de tamanho fixo, fácil de comparar e busca evitar colisões, servindo como verificação do conteúdo original do arquivo, ou seja, ao se calcular hash de dois arquivos diferentes eles devem produzir hashes diferentes.


Valores possíveis:


SHA1


SHA256


SHA384


SHA512