01
Primeiros passos
02
Introdução
03
Integração
- Http Headers
04
Usuário
- BcryptPassword
05
Login
- Challenge
- 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

Leia Introdução ao GraphQL, com exemplos reais da nossa API.
Crie um usuário no portal do desenvolvedor.
Cadastre sua primeira aplicação.
Utilize o dashboard para acessar suas configurações de acesso.
Para explorar rapidamente as APIs aqui na página de documentação, use o console de GraphQL, na seção de referências. Nele, você pode ver as consultas de exemplo, executá-las e alterá-las.



Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista



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



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

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

Exemplo do corpo da requisição:

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

Exemplo da resposta da API:

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

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

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

Exemplo do corpo da requisição:

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

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

Tipos de Usuário

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

Card Holder: Um usuário portador de um ou mais cartões Elo;
Card Issuer: Um usuário que emite cartões Elo;
Merchant: Um estabelecimento comercial que realiza transações com cartões Elo;

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

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

Exemplo do corpo da requisição:

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

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

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

Exemplo do corpo da requisição:

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

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

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

Exemplo do corpo da requisição:

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

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

Outras interações

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

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

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

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

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

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

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

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



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.



Login

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

Veja na figura abaixo os dois exemplos:

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

Exemplo do corpo da requisição:

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

Exemplo da resposta da API:

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

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

Exemplo do corpo da requisição:

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

Exemplo da resposta da API:

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

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

Exemplo do corpo da requisição:

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

Exemplo da resposta da API:

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



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.



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:

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

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

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

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

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

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

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

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

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

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

Outras interações

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



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.

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

TODO: notificação (subscription) do evento

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.

TODO: notificação (subscription) do evento

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.

TODO: notificação (subscription) do evento

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

TODO: document filter language, something like Google or GMail



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

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"

JSON Schema: CardSensitiveInput.json



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

addresses

list de AddressInput obrigatório

Endereços postais



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

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

pan: O número da conta primária (Primary Account Number), também conhecido como \"número do cartão\" físico. Exemplo: "1234567890123456"
expiry: Data de validade do cartão, ou seja, quando ele expira. É um objeto composto pelas chaves month e year descritas a seguir. Exemplo: {"month": 2, "year": 2020}
- month: Mês da validade do cartão. Número inteiro entre 1 (Janeiro) e 12 (Dezembro).
- year: Ano da validade do cartão. Número inteiro com 4 dígitos (2017, não 17).
name: Nome do portador do cartão. Exemplo: "João da Silva".

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

csc: Código de segurança do cartão (Card Security Code), usualmente impresso na parte de trás do cartão físico.
cscEntryTime: Data e horário quando o CSC (Código de Segurança do Cartão) foi digitado. É necessário quando o CSC é gerado por um chaveiro/token baseado em tempo. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"
authCode: Código de autorização. Este código não é o CSC (Código de Segurança do Cartão) pois não está impresso no cartão. Exemplo: "AB123Z1Y"
authCodeEntryTime: Data e horário quando o código de autorização (authCode) foi digitado. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"

JSON Schema: CardSensitiveInput.json

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

holderId

ID obrigatório

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

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

Portador: se o usuário do sistema é um portador, deve ser o seu CardHolder { id } da pessoa física ou uma pessoa jurídica associado.
Emissor: se o portador autorizou a criação de cartões.

billingAddress

AddressInput

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



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.



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.

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

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



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

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



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

list de PersonContactInput

Contatos do usuário

Caso null, não será alterado

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

addresses

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

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

list de CardHoldersEdge

Lista de arestas que compõem esta conexão.

totalCount

Int

Contagem total de objetos nesta conexão.

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

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



LegalIds

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

Campos:

cnpj

CNPJ

cpf

CPF

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

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



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

(

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:

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

(

format:

CryptoKeyFormat

)

String obrigatório

A chave serializada no formato requerido.

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

fingerprint

(

hash:

CryptoHashAlgorithm

)

String obrigatório

Fingerprint da chave utilizando o algoritmo de hash requerido.

Se nenhum algoritmo for especificado, será usado SHA256.



User

Usuário do Sistema

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

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

API Privada

Campos:

ID obrigatório

Identificador Global Único para este objeto

verified

VerifiedStatus

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

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

username

String

Nome do usuário para acesso ao sistema

name

String

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

firstName

String

Primeiro nome do usuário

lastName

String

Último nome do usuário

displayName

String

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

legalIds

LegalIds

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

birthday

Date

Data de nascimento

age

Int

Idade em anos

gender

Gender

Masculino ou Feminino, conforme documentos oficiais

maritalStatus

MaritalStatus

Estado civil

income

PersonYearlyIncome

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

occupation

(

language:

String

Língua a ser utilizada no retorno da consulta.

)

PersonOccupation

Profissão do usuário.

image

(

width:

Int

Caso fornecido, largura da imagem, em pixels.

height:

Int

Caso fornecido, altura da imagem, em pixels.

mimeType:

String

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

)

ImageUrl

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



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

list de AgreementTermsEdge

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



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



CreateUserPayload

Retorno da mutação createUser().

Compatível com Relay.

Campos:

clientMutationId

String

ID obrigatório

Identificador Global Único para este usuário

name

String

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



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

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.

creditSettlementBankNumber

Int

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

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

API Privada

debitSettlementBankNumber

Int

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

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

API Privada



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

Identificador Global Único para este objeto



SocialNetworkInterface

Interface comum às Redes Sociais

Campos:

provider

String obrigatório

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

username

String obrigatório

Nome de usuário na rede social



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



PersonContactType

Tipo de contato com pessoa física.

Valores possíveis:

PHONE

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

o valor é um e-mail

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:

JWK

JSON Web Key - JWK

PEM

Privacy Enhanced Mail PEM

X509

Certificado X.509