pt-BR|en

  • 01

    Primeiros passos

  • 02

    Introdução

  • 03

    Integração

    • Http Headers

  • 04

    Usuário

    • BcryptPassword

    • Contatos

    • Confirmação de contato

  • 05

    Login

    • Challenge

    • Atualização do accessToken

    • Reset de senha

  • 06

    Cartão

    • Sensitive

  • 07

    Carteira

  • 08

    Termo de Uso

  • 09

    Exemplos de Consultas

  • 10

    Glossário

  • 11

    Referências

    • Queries

    • Mutations

    • Tipos de Entrada

    • Tipos

    • Interfaces

    • Enumerações

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

Introdução

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

Campo Origin
Este campo pode ser utilizado para identificar a origem da criação do usuário em questão ele deve ser definido na chamada de criação do usuário mutation createUser.

Integração

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.

Http Headers

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

Usuário

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"
      }
    }
    origin: "Promoção cadastre sua conta Elo"
  })
  {
    clientMutationId,
    id,
    name,
    oauthToken {
      accessToken
      refreshToken
    }
  }
}

Exemplo da resposta da API:

{
   "data": {
        "createUser": {
            "id": "89bd51d6-8eaf-31a5-bd2c-1fve81d17db4",
            "name": "name"
        },
      "oauthToken": {
        "accessToken": "89bd51d6-8eaf-31a5-bd2c-1fve81d17db4",
        "refreshToken": "ccc0fba7-fa8d-3e85-a19e-2dc725bbb33d"
      }
   }
}

No exemplo acima, o campo oauthToken contém os tokens necessários para o fluxo oAuth de autenticação:

  • accessToken, token que deve ser sempre utilizado caso o usuário faça alguma requisição para algum recurso da API;

  • refreshToken, token necessário para a renovação do accessToken.

No campo id, temos também o mesmo accessToken informado.

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.

Já 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"
      }
    }
    origin: "Promoção cadastre sua conta Elo"
  })
  {
    clientMutationId,
    id,
    name,
    oauthToken {
      accessToken
      refreshToken
    }
  }
}

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

Campo Origin
Este campo permite identificar a origem da criação do usuário, ex.: uma promoção semanal, campanha de marketing... É possível fornecer uma String que poderá ser consultada nos dados do usuário.

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;

  • Acquirer: Um usuário que captura transações realizadas com cartões Elo em estabelecimentos;

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.

Para obter o id do Merchant, basta utilizar a Query Merchants(..). Essa consulta retorna os dados de cadastro de todos os Merchants sendo possível também a utilização de filtros para consultar Merchants específicos como mostra o exemplo.

query {
    merchants (
    filter: {
        legalIds:[
            {cnpj: "13941300000117"},
            {cnpj: "07513760000222"}
        ]
    })
    {
        edges {
            cursor
            node {
                id
                name
                legalName
                addresses {
                    context
                    city
                }
                legalIds {
                    cnpj {
                        number
                    }
                }
                categories {
                    id
                    iso
                    name
                }
            }
        }
    }
}

Para associar um usuário ao tipo Acquirer, basta utilizar a mutation addAcquirerToUser. Por questão de segurança o campo access_token no header da requisição é usado para identificar o usuário que está efetuando a operação.

mutation{
  addAcquirerToUser(
    input:{
      clientMutationId: "1234"
      acquirerId: "5d430aad-41ff-435c-99ec-69a8b8f584e9"
    }
  )
  {
    clientMutationId
    user{
      id
      username
    }
    acquirer{
      id
      name
      code
    }
  }
}

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.

BcryptPassword

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.

Contatos

O usuário pode complementar seu cadastro com suas informações de contato. Atualmente, é possível adicionar um contato para cada um dos tipos a seguir: EMAIL, PHONE e IM. Caso o usuário precise adicionar mais contatos, ele pode cadastrá-los utilizando o contato do tipo OTHER que não possui restrição de quantidade.

Confirmação de contato

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. Existem duas formas do usuário gerar o código de verificação:

  • Na criação do usuário, informando o campo opcional verifyContact;

  • Após a criação do usuário, utilizando a mutation requestContactVerification.

Em ambos os casos, é possível verificar apenas os contatos do tipo EMAIL e PHONE.

Confirmação de contato na criação do usuário

Para verificar o contato neste momento, é necessário informar o campo verifyContact, um Enum que possui como valores:

  • PHONE, para a verificação ser realizada com o telefone do usuário

  • EMAIL, para a verificação ser feita pelo e-mail do usuário

Abaixo, temos um exemplo de como seria essa chamada:

mutation{
  createUser(input:{  
    verifyContact: PHONE, # Enum opcional, aceita os valores PHONE e EMAIL
    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"
      }
    }
    origin: "Promoção cadastre sua conta Elo"
  })
  {
    clientMutationId,
    id,
    name
  }
}

Confirmação de contato através da mutation requestContactVerification

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.

Login

Para ter acesso às APIs da Elo, o usuário deve possuir um access_token válido e para isso ele deve ou efetuar login na plataforma, ou renovar o seu access_token.

Realizando o login

O processo de login pode ser realizado de duas formas:

  • Utilizando um nome de usuário e senha via createLoginSalt

  • Com uma rede social via socialNetworkOAuthLogin

Veja na figura abaixo os dois exemplos para a realização de login:

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,
    oauthToken{
      accessToken,
      refreshToken
    }
    }
}

Exemplo da resposta da API:

{
   "data": {
       "login": {
           "clientMutationId": "0123456789",
           "accessToken": "b64a0e34-24c5-39eb-b457-0c7331d176f0", 
           "oauthToken": {
               "accessToken": "b64a0e34-24c5-39eb-b457-0c7331d176f0",
               "refreshToken": "4a474832-1b48-4ae3-9ad9-1d767a48ebe6"
           }
       }
   }
}

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

Renovando o accessToken

Já para atualizar o access_token, é preciso utilizar a mutation refreshAccessToken, descrita ao final desta sessão.

Challenge

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.

Atualização do accessToken

Através da mutation refreshAccessToken, é possível realizar o fluxo de Atualização do accessToken. Esse fluxo consiste no envio para a API do refreshToken que, após validar junto com o Authorization enviado no header da requisição, retornará um novo accessToken, e um novo refreshToken, como exemplificado a seguir:

mutation {
  refreshAccessToken(input: {
    clientMutationId: "860e72f2-d58f-4bee-ad3a-532085f6f3eb",
    refreshToken: "ccc0fba7-fa8d-3e85-a19e-2dc725bbb33d"
  }) {
    clientMutationId,
    oauthToken{
      accessToken,
      refreshToken
    }
  }
}

Exemplo da resposta da API:

{
  "data": {
    "refreshAccessToken": {
      "clientMutationId": "860e72f2-d58f-4bee-ad3a-532085f6f3eb",
      "oauthToken": {
        "accessToken": "ffd2b5cf-be8b-3a8a-802d-41983dea5872",
        "refreshToken": "88803449-7c41-3c3f-adb2-3b32ef1a85ff"
      }
    }
  }
}

Atenção! Após a chamada desta mutation, o accessToken e o refreshToken enviados na requisição serão revogados - passando a valer apenas os tokens do retorno da mutation.

Reset de senha

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.

Após a execução da mutation de solicitação, será enviado um e-mail ou um SMS para o contato especificado, com um token que será usado para realizar o reset da senha, através da mutation passwordReset.

Todos os casos de reset de senha são válidos apenas para contatos do tipo e-mail e phone.

Solicitando o envio de um pedido de reset de senha

Através da mutation requestPasswordReset é possível solicitar o reset de duas formas:

  • Enviando o campo email ou phone (mas nunca ambos), sendo os mesmos contatos enviados no momento do cadastro, e que receberão o token para o reset da senha

  • Enviando o enum type, que quando indicado EMAIL ou PHONE, enviará o token ao respectivo contato salvo no momento do cadastro do usuário

Abaixo, temos a primeira forma:

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

E a seguir, temos a solicitação de reset de senha através do enum type:

mutation {
    requestPasswordReset(input: {
        clientMutationId: "123456",
        legalId: {
            cpf: "12345678900"
        },
    type: EMAIL
    }) {
        clientMutationId
        maskedEmail
    }
}

Realizando o reset de senha

Após a chamada anterior e após o envio do token através do e-mail/SMS para o contato especificado, é preciso utilizá-lo através da mutation passwordReset, para fazer o reset da senha.

Da mesma forma, como na mutation anterior, é possível realizar de duas formas o reset de senha: ou enviando os campos de e-mail/telefone, ou informando o type - e, assim, refenciar o contato salvo na criação do usuário.

Abaixo, temos um exemplo com o envio do campo e-mail:

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

Obs.: Lembrando que caso o token tenha sido solicitado usando phone (SMS), é preciso enviar o phone na requisição passwordReset; caso requestPasswordReset tenha sido solicitado usando email, se envia o campo email na passwordReset.

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.

Cartão

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,
        sensitive: "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway..."
    }) {
        card {
            id
            last4
            expiry{
                month
                year
            }
        }
    }
}

Neste exemplo estamos atualizando algumas informações do cartão - identificado pelo campo holderId. Além de alterarmos o endereço de cobrança do cartão (campo billingAddress) e seu status, será atualizado a data de validade e o nome impresso no cartão.

Atenção: Para ser válida a atualização, é preciso que o PAN do cartão seja igual ao do cartão criado previamente.

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.

Sensitive

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.

Exemplo completo do JSON de sensitive:

{
  "pan": "1234567890123456",
  "expiry": {
    "month": 2,
    "year": 2020
  },
  "name": "João da Silva",
  "csc": "222",
  "cscEntryTime": "2017-06-01T12:00:00-03:00"
}

Ou se preenchido por authCode:

{
  "pan": "1234567890123456",
  "expiry": {
    "month": 2,
    "year": 2020
  },
  "name": "João da Silva",
  "authCode": "AB123Z1Y",
  "authCodeEntryTime": "2017-06-01T12:00:00-03:00"
}

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.

Carteira

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

Termo de Uso

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

Exemplos de Consultas

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

Glossário

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

Referências


Queries



node

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

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

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

Fragmentos inline:

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

Fragmentos reusáveis:

fragment CardLast4Fragment on Card {
  last4
}

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

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

Argumentos:

id: ID obrigatório

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



cards

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.



cardHolders

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.



user

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.



agreementTerms

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.




Mutations



addCardToWallet

adiciona um cartão existente à uma carteira digital

Usável por:

  • Portadores de cartão

Argumentos:

input: AddCardToWalletInput obrigatório



removeCardFromWallet

remove um cartão existente de uma carteira digital

Usável por:

  • Portadores de cartão

Argumentos:

input: RemoveCardFromWalletInput obrigatório



createWallet

Cria Carteira Digital para um portador.

Usável por:

  • Portadores de cartão

Argumentos:

input: CreateWalletInput obrigatório



deleteWallet

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



updateWallet

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



createLoginSalt

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



login

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



socialNetworkOAuthLogin

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



createUser

Cria um usuário.

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

Argumentos:

input: CreateUserInput obrigatório



createCard

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



deleteCard

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



updateCard

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



requestPasswordReset

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



passwordReset

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



deleteUser

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



updateUser

Configura (altera) os campos do usuário

Para a imagem veja setImage()

Argumentos:

input: UpdateUserInput obrigatório



createCardHolderForUser

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

Argumentos:

input: CreateCardHolderForUserInput obrigatório



addCardIssuerToUser

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.

Argumentos:

input: AddCardIssuerToUserInput obrigatório



addMerchantToUser

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.

Argumentos:

input: AddMerchantToUserInput obrigatório



addPublicKeyToUser

Adiciona uma chave pública ao usuário

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

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

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

Argumentos:

input: AddPublicKeyToUserInput obrigatório



addAgreementToUser

Adiciona um termo aceito pelo usuário

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

Argumentos:

input: AddAgreementToUserInput obrigatório



removeAgreementFromUser

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




Tipos de Entrada



CardFilterInput

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.


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.



SearchFilterInput

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

Campos:

filter

:

String


RGInput

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



LegalIdsInput

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)



SocialNetworkInput

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



AgreementTermFilterInput

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

:

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



AddCardToWalletInput

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"



RemoveCardFromWalletInput

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.



CreateWalletInput

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.



DeleteWalletInput

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



UpdateWalletInput

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.



CreateLoginSaltInput

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.



LoginInput

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



SocialNetworkOAuthLoginInput

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



SocialNetworkOAuthInput

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

:

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



PersonYearlyIncomeInput

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



PersonContactInput

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.



AddressInput

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.



CreateUserInput

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

:

list de PersonContactInput obrigatório

Contatos do usuário.

São permitidos múltiplos contatos do tipo OTHER desde que eles não se repitam. Para os demais tipos são permitidos apenas um contato por tipo.


verifyContact

:

TypeContactVerification

Indica se o contato será verificado ou não no momento da criação do usuário.

Se enviada, informa qual o tipo de contato escolhido para a verificação.


addresses

:

list de AddressInput obrigatório

Endereços postais


origin

:

String

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



CreateCardInput

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"

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.



DeleteCardInput

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



UpdateCardInput

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.


status

:

CardStatus

Estado do cartão.

Se null, não será alterado.


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: (esse campo é obrigatório) O número da conta primária (Primary Account Number), também conhecido como "número do cartão" físico. Exemplo: "1234567890123456"

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

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

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

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

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

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

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

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

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



RequestPasswordResetInput

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.

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



PasswordResetInput

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


type

:

PersonContactType

Tipo do contato do usuário o qual deseja recuperar a senha.

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


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



DeleteUserInput

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



UpdateUserInput

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.

São permitidos múltiplos contatos do tipo OTHER desde que eles não se repitam. Para os demais tipos são permitidos apenas um contato por tipo.


addresses

:

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



CompanyLegalIdsInput

Entrada para CompanyLegalIds

Campos:

cnpj

:

String

Número CNPJ sem hífen ou pontos



CreateCardHolderForUserInput

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.



AddCardIssuerToUserInput

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



AddMerchantToUserInput

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



AddPublicKeyToUserInput

Entrada para mutação addPublicKeyToUser()

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

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

Compatível com Relay.


userId

:

ID obrigatório

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


key

:

String obrigatório

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

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


format

:

CryptoKeyFormat

Formato da chave key.

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



AddAgreementToUserInput

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.



RemoveAgreementFromUserInput

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




Tipos



PageInfo

PageInfo compatível com Relay.

Campos:

hasPreviousPage

:

Boolean obrigatório

hasNextPage

:

Boolean obrigatório

startCursor

:

String

endCursor

:

String


CardsEdge

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.



CardsConnection

Conexão de Card em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

Conexão de Card em conformidade com o Relay.


edges

:

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



CardHoldersEdge

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.



CardHoldersConnection

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



LegalIds

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

Campos:

cnpj

:

CNPJ

cpf

:

CPF

rg

:

RG


PersonYearlyIncome

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



PersonOccupation

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.



ImageUrl

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



PersonContact

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

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

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.



Address

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.



CardHolder

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

:

list de PersonContact obrigatório

Contatos do portador de cartão


addresses

:

list de Address obrigatório

Endereço postal


wallets

:

list 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

Query (consulta) tokens CardToken


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



Merchant

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

:

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



CardIssuer

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.



SocialNetwork

Redes Social

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



UserAgreement

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



AccessTokenInfo

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



PublicKey

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



Acquirer

Entidade do Credenciador

Campos:

id

:

ID obrigatório

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

code

:

String obrigatório

Identificador Global Único do Credenciador junto a Elo.

Este campo identifica unicamente os números designados pela Elo para Estabelecimentos/Credenciador.


countryCode

:

String obrigatório

Identificador Global Único do país onde está localizado o Credenciador. Transações nacionais utiliza-se o código 076 (Brasil). ISO 3166-1 numeric


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

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 CardIssuer pode realizar essas consulta.

)

:

CardFraudTransactionsConnection

Lista de transações fraudulentas



User

Usuário do Sistema

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

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

API Privada

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


verified

:

VerifiedStatus

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

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


username

:

String

Nome do usuário para acesso ao sistema


name

:

String

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


firstName

:

String

Primeiro nome do usuário


lastName

:

String

Último nome do usuário


displayName

:

String

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


legalIds

:

LegalIds

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


birthday

:

Date

Data de nascimento


age

:

Int

Idade em anos


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncome

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


occupation

(


language:

String

Língua a ser utilizada no retorno da consulta.

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

)

:

PersonOccupation

Profissão do usuário.

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


image

(


width:

Int

Caso fornecido, largura da imagem, em pixels.

height:

Int

Caso fornecido, altura da imagem, em pixels.

mimeType:

String

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

)

:

ImageUrl

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


contacts

:

list de PersonContact obrigatório

Contatos do usuário


addresses

:

list de Address obrigatório

Endereços postais


cardHolders

:

list de CardHolder obrigatório

Portadores de cartões associados ao usuário

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

Relação: 1:n


merchants

:

list de Merchant obrigatório

Comerciantes associados ao usuário

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

Relação: n:n


cardIssuers

:

list de CardIssuer obrigatório

Emissores de cartões associados ao usuário

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

Relação: n:n


socialNetworks

:

list de SocialNetwork obrigatório

Redes sociais relacionadas ao usuário


agreements

:

list de UserAgreement obrigatório

Termos de uso aceitos pelo usuário


accessTokens

:

list de AccessTokenInfo obrigatório

Lista de chaves de acesso ativas para este usuário


publicKeys

:

list de PublicKey obrigatório

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


origin

:

String

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


analyticsId

:

ID obrigatório

Identificador Global Único para este objeto


acquirer

:

Acquirer


AgreementTermsEdge

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.



AgreementTermsConnection

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.



Wallet

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.



Card

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

availableServices

:

list de CardHolderService obrigatório

usedServices

:

list 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

:

list de CardCapture obrigatório

usages

:

list de CardUsage obrigatório

network

:

CardNetwork

issuer

:

CardIssuer

metadata

:

CardMetadata

trackings

:

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

)

:

list 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


AddCardToWalletPayload

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.



RemoveCardFromWalletPayload

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.



CreateWalletPayload

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.



DeleteWalletPayload

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.



UpdateWalletPayload

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.



CreateLoginSaltPayload

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.



AccessTokenPayload

Retorno da mutação logout().

Compatível com Relay.

Campos:

accessToken

:

String obrigatório

A chave de acesso expirada (accessToken) de identificação do usuário.


refreshToken

:

String obrigatório

Informação que deve ser utilizada para gerar uma nova chave de accesso do usuário.



LoginPayload

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

@deprecated(reason: "Esse campo está sendo retornado dentro do campo oauthToken.")


oauthToken

:

AccessTokenPayload

Informações para autenticação e geração de uma nova chave de acesso



CreateUserPayload

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)


oauthToken

:

AccessTokenPayload

Informações para autenticação e geração de uma nova chave de acesso



CreateCardPayload

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



CardExpiry

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.



BIN

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

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

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

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

A tabela de BIN é dinâmica:

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

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

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

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

isP2PEligible

:

Boolean obrigatório

Se true, então o cartão poderá ser utilizado em transações P2P. Se false, então o cartão NÃO poderá ser utilizado em transações P2P.


isCompany

:

Boolean obrigatório

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.


isMigrated

:

Boolean

Identificada se um BIN que não teve origem no FLEX, foi migrado para FLEX. Se true, identifica que foi migrado para o FLEX. Se false, identifica que ainda não foi migrado para o FLEX.


isFlex

:

Boolean

Identificada se um BIN é FLEX ou não. Se true, identifica que é um bin FLEX. Se false, identifica que ainda não é um BIN Flex.


creditSettlementBankNumber

:

Int

Número do Banco liquidante da operação de Débito

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 Débito

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

API Privada



DeleteCardPayload

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.



UpdateCardPayload

Retorno da mutação updateCard().

Compatível com Relay.

Campos:

clientMutationId

:

String

card

:

Card

O cartão atualizado.



RequestPasswordResetPayload

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



PasswordResetPayload

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.



DeleteUserPayload

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



UpdateUserPayload

Retorno da mutação updateUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário modificado com os novos campos



CreateCardHolderForUserPayload

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.



AddCardIssuerToUserPayload

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



AddMerchantToUserPayload

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



AddPublicKeyToUserPayload

Retorno da mutação addPublicKeyToUser().

Compatível com Relay.

Campos:

clientMutationId

:

String

user

:

User

O usuário o qual teve chave adicionada.


publicKey

:

PublicKey

A chave adicionada.

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



AddAgreementToUserPayload

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



AgreementTerm

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.



RemoveAgreementFromUserPayload

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 }




Interfaces



Node

Node compatível com Relay.

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto




Enumerações


CardStatus

Estado do cartão

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


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




CardFunding

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)




VerifiedStatus

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.




Gender

Opções de gênero


Valores possíveis:


FEMALE


MALE




MaritalStatus

Opções de estado civil


Valores possíveis:


DIVORCED

Divorciado


MARRIED

Casado


SINGLE

Solteiro


WIDOWED

Viúvo


COMMON_LAW_MARRIED

União estável




TypeContactVerification

Tipos de contato válidos para a verificação de contato.


Valores possíveis:


PHONE

Telefone


EMAIL

E-mail




PersonContactType

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




CryptoKeyFormat

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


Valores possíveis:


PEM

Privacy Enhanced Mail PEM


X509

Certificado X.509