01
Primeiros passos
02
Introdução
03
Integração
Http Headers
04
Usuário
BcryptPassword
Contatos
Confirmação de contato
05
Login
Challenge
Atualização do accessToken
Reset de senha
06
Cartão
Sensitive
07
Carteira
08
Termo de Uso
09
Exemplos de Consultas
10
Glossário
11
Referências
Queries
Mutations
Tipos de Entrada
Tipos
Interfaces
Enumerações
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.
Jaydson GomesDesenvolvedor Evangelista
O portador é um usuário do sistema (User
) o qual possuí cartões. Este usuário é denomidado CardHolder
e gerencia cartões (Card
) e carteiras (Wallet
). Um portador (CardHolder
) pode cadastrar, consultar, editar e deletar seus cartões, como também pode associar seus cartões ás suas carteiras. Este pode ser uma pessoa física, que possua cartões, ou pessoa jurídica que possua cartões corporativos.
query {
user {
id
username
origin
cardHolders {
companyName,
companyLegalName,
cards {
edges {
node {
transactions(filter: {
startTimestamp: "2017-11-21T00:00:00Z",
endTimestamp: "2017-12-30T00:00:00Z",
includeMerchantCategories: [{ min: 1,max: 3 }, { min: 4, max: 10 }],
excludeMerchantCategories: [{ min: 10, max: 10 }],
status: APPROVED
})
{
pageInfo { hasPreviousPage },
edges {
cursor,
node {
id,
bin {
number,
isInternational,
product {
id,
name
},
country
},
status,
capture { id, name },
currency,
value,
installments
}
}
}
}
}
}
}
}
}
Campo Origin
Este campo pode ser utilizado para identificar a origem da criação do usuário em questão ele deve ser definido na chamada de criação do usuário mutation createUser
.
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.
Todas as requisições realizadas junto à API da ELO deverão utilizar o protocolo HTTPS, e deverão ter em seus cabeçalhos os dados necessários para o acesso ao serviço. São eles:
client_id
: Identificador gerado quando o desenvolvedor cria uma aplicação no portal e que pode ser encontrado nas configurações da dashboard da aplicação.
Authorization
ou access_token
: Aqui é um ponto importante que deve ter bastante atenção do desenvolvedor. Enquanto o usuário não realizou o login na API é obrigatório o envio do Authorization
. Após o login o desenvolvedor deve enviar apenas o access_token
obtido.
Authorization
O Authorization
pode ser obtido concatenando o texto "Basic "
ao resultado da codificação em Base 64 dos campos client_id
e client_secret
concatenados com :
.
Abaixo um exemplo de pseudo-código para gerar o Authorization
:
var authorization = "Basic " + base64(client_id + ":" + client_secret);
e a seguir temos um exemplo de Authorization
já definido no header
da requisição:
Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==
Para que seja possível iniciar a jornada dentro da plataforma de APIs da Elo, é necessário que um usuário seja criado. Para esse processo o desenvolvedor deverá usar a função createUser
disponibilizada pela API. Esta função pode ser utilizada de duas maneiras:
O usuário utilizará o nome de usuário e senha como meio de autenticação.
O usuário utilizará uma rede social suportada pela plataforma da ELO como meio de autenticação.
A seguir é demonstrado uma visão geral desse processo.
Um exemplo da utilização da função createUser
usando o nome de usuário e senha como autenticação é demonstrado a seguir.
Exemplo do corpo da requisição:
mutation{
createUser(input:{
clientMutationId: "123",
username: "username",
bcryptPassword: "$2a$12$oumE.pnRbsdi.c4KYsyNWOJoVyfi2jMKDe102Er5uGCdzd49SvE1Y",
name: "name",
firstName: "firstName",
lastName: "lastName",
contacts: [{
type: PHONE
context: "CASA"
value: "+5519912345678"
}]
displayName: "displayName",
legalIds:{
cpf: "1234567890",
rg:{
number: "234567890",
issuerOrganization: "SSP",
issuerState: "SP",
issueDate: "2020-12-03"
}
}
origin: "Promoção cadastre sua conta Elo"
})
{
clientMutationId,
id,
name,
oauthToken {
accessToken
refreshToken
}
}
}
Exemplo da resposta da API:
{
"data": {
"createUser": {
"id": "89bd51d6-8eaf-31a5-bd2c-1fve81d17db4",
"name": "name"
},
"oauthToken": {
"accessToken": "89bd51d6-8eaf-31a5-bd2c-1fve81d17db4",
"refreshToken": "ccc0fba7-fa8d-3e85-a19e-2dc725bbb33d"
}
}
}
No exemplo acima, o campo oauthToken
contém os tokens necessários para o fluxo oAuth de autenticação:
accessToken
, token que deve ser sempre utilizado caso o usuário faça alguma requisição para algum recurso da API;
refreshToken
, token necessário para a renovação do accessToken
.
No campo id
, temos também o mesmo accessToken
informado.
Nesse cenário não é necessário que o usuário faça login após a criação pois o mesmo já foi feito implicitamente pela função createUser
e o token de acesso pode ser utilizado até sua expiração.
Já um exemplo da utilização da função createUser
usando uma rede social é demonstrado a seguir.
Exemplo do corpo da requisição:
mutation{
createUser(input:{
clientMutationId: "123",
username: "username",
socialNetwork:{
provider: "FACEBOOK",
username: "usernameFacebook@gmail.com"
},
oauth:{
accessToken: "EAACEdEose0cBAPZAVQLY5qPqEfqPPPviCy5NYbYBX7zLndQWDiUZBOBMC5Ry...",
refreshToken: "",
scopes: "email",
expiryTimestamp: "2018-03-01T00:00:00Z"
},
name: "name",
firstName: "firstName",
lastName: "lastName",
displayName: "displayName",
legalIds:{
cpf: "1234567890",
rg:{
number: "234567890",
issuerOrganization: "SSP",
issuerState: "SP",
issueDate: "2020-12-03"
}
}
origin: "Promoção cadastre sua conta Elo"
})
{
clientMutationId,
id,
name,
oauthToken {
accessToken
refreshToken
}
}
}
A resposta da criação do usuário usando uma rede social é a mesma do exemplo anterior.
Campo Origin
Este campo permite identificar a origem da criação do usuário, ex.: uma promoção semanal, campanha de marketing... É possível fornecer uma String
que poderá ser consultada nos dados do usuário.
Após a criação, um determinado usuário pode assumir 3 tipos distintos na plataforma da Elo, sendo eles:
Card Holder: Um usuário portador de um ou mais cartões Elo;
Card Issuer: Um usuário que emite cartões Elo;
Merchant: Um estabelecimento comercial que realiza transações com cartões Elo;
Acquirer: Um usuário que captura transações realizadas com cartões Elo em estabelecimentos;
Cada tipo possui sua forma de ser associado, com informações pertinentes a cada um. Um usuário só pode ter um tipo associado ao mesmo tempo, logo, se um usuário está associado a um CardHolder
e tenta se associar a um Merchant
um erro será retornado. Neste caso, é necessário remover a associação do CardHolder
do usuário e, somente depois, realizar a associação ao novo tipo.
Para associar um CardHolder
ao usuário basta utilizar a função createCardHolderForUser
, a mutation abaixo é um exemplo de sua utilização. Por questão de segurança o campo userId
não se refere ao real id
do usuário, e sim ao seu access_token
.
Exemplo do corpo da requisição:
mutation{
createCardHolderForUser(input:{
clientMutationId: "123",
userId: "33744898-9844-4864-a0ca-046d50fdaf15",
companyName: "companyName",
companyLegalName: "companyLegalName",
companylegalIds: {
cnpj: "1234567890"
}
})
{
clientMutationId,
user{
id,
verified,
name,
displayName
},
cardHolder{
id,
name,
companyName,
companyLegalName
}
}
}
Neste exemplo estamos criando o CardHolder
e associando o mesmo ao usuário identificado pelo access_token
, que é refletido no campo userId
. Os dados retornados após a criação e associação do CardHolder
ao usuário, serão os que foram definidos na parte inferior da mutation.
Para associar um CardIssuer
ao usuário basta utilizar a função addCardIssuerToUser
, a seguir temos a chamada para esta mutation como exemplo de utilização. Por questão de segurança o campo userId
não se refere ao real id
do usuário, e sim ao access_token
do mesmo.
Exemplo do corpo da requisição:
mutation{
addCardIssuerToUser(input:{
clientMutationId: "123",
userId: "97c7fb10-174c-4e23-8feb-926d1d23a035",
cardIssuerId: "1b253372-8215-4567-a54d-4fa78dadf0f6"
})
{
clientMutationId,
user{
id,
verified,
name,
displayName
},
cardIssuer{
id,
name,
legalName
}
}
}
Neste exemplo estamos associando um CardIssuer
ao usuário identificado pelo access_token
, que é refletido no campo userId
. Os dados retornados após a associação do CardIssuer
ao usuário, serão os que foram definidos na parte inferior da mutation.
Para associar um Mechant
ao usuário basta utilizar a função addMerchantToUser
, a seguir temos um exemplo de sua utilização. Por questão de segurança o campo userId
não se refere ao real id
do usuário, e sim ao access_token
do mesmo.
Exemplo do corpo da requisição:
mutation{
addMerchantToUser(input:{
clientMutationId: "123",
userId: "14991673-f5b9-43b8-8cb3-8da353b9b70c",
merchantId: "b86eb0ef-0c21-4ea5-b407-9f113a229190"
})
{
clientMutationId,
user{
id,
verified,
name,
displayName
},
merchant{
id,
name,
legalName
}
}
}
Neste exemplo estamos associando um Merchant
ao usuário identificado pelo access_token
, que é refletido no campo userId
. Os dados retornados após à associação do Merchant
ao usuário, serão os que foram definidos na parte inferior da mutation.
Para obter o id do Merchant
, basta utilizar a Query Merchants(..)
. Essa consulta retorna os dados de cadastro de todos os Merchants
sendo possível também a utilização de filtros para consultar Merchants
específicos como mostra o exemplo.
query {
merchants (
filter: {
legalIds:[
{cnpj: "13941300000117"},
{cnpj: "07513760000222"}
]
})
{
edges {
cursor
node {
id
name
legalName
addresses {
context
city
}
legalIds {
cnpj {
number
}
}
categories {
id
iso
name
}
}
}
}
}
Para associar um usuário ao tipo Acquirer
, basta utilizar a mutation addAcquirerToUser
. Por questão de segurança o campo access_token
no header da requisição é usado para identificar o usuário que está efetuando a operação.
mutation{
addAcquirerToUser(
input:{
clientMutationId: "1234"
acquirerId: "5d430aad-41ff-435c-99ec-69a8b8f584e9"
}
)
{
clientMutationId
user{
id
username
}
acquirer{
id
name
code
}
}
}
Para consultar um usuário basta utilizar uma query de usuário, como no exemplo abaixo.
query {
user(id: "70fa9e70-1b41-3f68-8df9-b207d76929f6") {
id,
username
cardHolders{
id
name
companyName
}
}
}
Para atualizar um usuário basta utilizar a função updateUser
, a seguir temos um exemplo de sua utilização. Por questão de segurança o campo id
não se refere ao real id
do usuário, e sim ao access_token
do mesmo.
mutation {
updateUser(input:{
id: "0c9cd95a-365e-40d3-89c2-63c35340a0fa",
firstName: "firstName changed"
}) {
user{
id
firstName
}
}
}
Neste exemplo estamos atualizando o firstName
(primeiro nome) do usuário, porém outros atributos também podem ser atualizados.
Para deletar um usuário basta utilizar a função deleteUser
, a seguir temos um exemplo de sua utilização. Por questão de segurança o campo userId
não se refere ao real id
do usuário, e sim ao access_token
do mesmo.
mutation {
deleteUser(input:{
userId: "e29e5d4b-c5f6-45c9-90e0-26b21fed43f9"
}) {
userId
username
displayName
}
}
Neste exemplo estamos deletando o usuário com identificação informada no campo userId
.
O campo bcryptPassword presente no cadastro de usuário refere-se aos dados sensíveis de acesso do usuário à API. Estes dados são o nome de usuário e senha criptografados usando o algoritmo conhecido como bcrypt. Isso é feito para não se armazenar as senhas no sistema. Os passos para utilização desse algoritmo com os parâmetros requisitados pela API da ELO são descritos abaixo:
1º Passo: Gerar um salt a partir do nome de usuário:
Aplicar o algoritmo SHA256
no nome do usuário e reservar os 16 primeiros caracteres.
Aplicar a codificação Base64
sobre o resultado do item anterior utilizando o alfabeto customizado do algoritmo bcrypt. O alfabeto utilizado pelo bcrypt utiliza "." ao invés de "+" e começa com "./". Segue abaixo:
./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789
Concatenar o resultado do item anterior com o texto "$2a$12". Exemplo de resultado:
$2a$12$N9qo8uLOickgx2ZMRZoMye
2º Passo: Aplicar o algoritmo bcrypt utilizando a senha do usuário e o salt gerado no primeiro passo:
Aplicar o algoritmo SHA256
na senha do usuário.
Aplicar a codificação Base64
sobre o resultado do item anterior.
Aplicar o algoritmo bcrypt utilizando o resultado do item anterior e o salt gerado no primeiro passo.
NOTA: O custo utilizado pelo algoritmo do bcrypt deve ser igual a 12.
O usuário pode complementar seu cadastro com suas informações de contato. Atualmente, é possível adicionar um contato para cada um dos tipos a seguir: EMAIL, PHONE e IM. Caso o usuário precise adicionar mais contatos, ele pode cadastrá-los utilizando o contato do tipo OTHER que não possui restrição de quantidade.
Os contatos informados para o usuário durante o cadastro, permanecem com status UNVERIFIED até que seja realizada a confirmação destes através de um verificationCode gerado pelo sistema. Existem duas formas do usuário gerar o código de verificação:
Na criação do usuário, informando o campo opcional verifyContact
;
Após a criação do usuário, utilizando a mutation requestContactVerification
.
Em ambos os casos, é possível verificar apenas os contatos do tipo EMAIL e PHONE.
Para verificar o contato neste momento, é necessário informar o campo verifyContact
, um Enum que possui como valores:
PHONE
, para a verificação ser realizada com o telefone do usuário
EMAIL
, para a verificação ser feita pelo e-mail do usuário
Abaixo, temos um exemplo de como seria essa chamada:
mutation{
createUser(input:{
verifyContact: PHONE, # Enum opcional, aceita os valores PHONE e EMAIL
clientMutationId: "123",
username: "username",
bcryptPassword: "$2a$12$oumE.pnRbsdi.c4KYsyNWOJoVyfi2jMKDe102Er5uGCdzd49SvE1Y",
name: "name",
firstName: "firstName",
lastName: "lastName",
contacts: [{
type: PHONE
context: "CASA"
value: "+5519912345678"
}]
displayName: "displayName",
legalIds:{
cpf: "1234567890",
rg:{
number: "234567890",
issuerOrganization: "SSP",
issuerState: "SP",
issueDate: "2020-12-03"
}
}
origin: "Promoção cadastre sua conta Elo"
})
{
clientMutationId,
id,
name
}
}
requestContactVerification
Segue abaixo os passos para solicitação do verificationCode e confirmação do contato:
1º Passo: Realizar uma requisição de verificação de contato:
mutation{
requestContactVerification(input:{
clientMutationId: "123",
userId: "",
type: EMAIL,
value: "email@provedor.com"
}) {
clientMutationId
user{
id
verified
username
name
contacts{
type
value
verified
}
}
contact{
type
value
verified
}
}
}
Exemplo da resposta da API:
{
"data": {
"requestContactVerification": {
"clientMutationId": "123",
"user": {
"id": "fb9444fb-b9df-3cdd-a83e-808e0ce4b938",
"verified": "UNVERIFIED",
"username": "user1",
"name": "Nome Usuário",
"contacts": [
{
"type": "EMAIL",
"value": "email@provedor.com",
"verified": "PENDING"
}
]
},
"contact": {
"type": "EMAIL",
"value": "email@provedor.com",
"verified": "PENDING"
}
}
}
}
Após esta etapa, o status de verificação do contato passa para PENDING e o usuário receberá no contato em verificação um verificationCode que deverá ser utilizado no próximo passo.
2º Passo: Efetivar a confirmação de contato:
mutation{
contactVerification(input:{
clientMutationId: "456",
userId: "",
type: EMAIL,
value: "email@provedor.com",
verificationCode: "5QI057"
})
{
clientMutationId
user{
id
verified
username
name
contacts{
type
value
verified
}
}
contact{
type
value
verified
}
}
}
Exemplo da resposta da API:
{
"data": {
"contactVerification": {
"clientMutationId": "456",
"user": {
"id": "fb9444fb-b9df-3cdd-a83e-808e0ce4b938",
"verified": "VERIFIED",
"username": "user1",
"name": "Nome Usuário",
"contacts": {
{
"type": "EMAIL",
"value": "email@provedor.com",
"verified": "VERIFIED"
}
]
},
"contact": {
"type": "EMAIL",
"value": "email@provedor.com",
"verified": "VERIFIED"
}
}
}
}
Ao receber a resposta de sucesso, o contato tem seu status de verificação alterado para VERIFIED. Desta forma, pode-se garantir que o contato do usuário é um contato válido.
Para ter acesso às APIs da Elo, o usuário deve possuir um access_token
válido e para isso ele deve ou efetuar login na plataforma, ou renovar o seu access_token
.
O processo de login pode ser realizado de duas formas:
Utilizando um nome de usuário e senha via createLoginSalt
Com uma rede social via socialNetworkOAuthLogin
Veja na figura abaixo os dois exemplos para a realização de login:
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
serão descritos posteriormente). Um exemplo dessa chamada pode ser vista abaixo.
Exemplo do corpo da requisição:
mutation {
createLoginSalt(input:{
username: "UserNameToLogin"
})
{
username,
salt
}
}
Exemplo da resposta da API:
{
"data": {
"createLoginSalt": {
"username": "UserNameToLogin",
"salt": "$2a$05$J/dgZmXIN23mEZtvkxDYeO"
}
}
}
Na sequência, é necessário fazer uso da chamada login
. Esta requisição é necessária para dar acesso ao usuário às demais chamadas da API. Desta forma, no retorno dessa chamada é disponibilizado o access_token
que identifica o usuário de forma única.
Exemplo do corpo da requisição:
mutation {
login(input:{
clientMutationId: "0123456789",
username: "UserNameToLogin",
challenge:"$2a$05$J/dgZmXIN23mEZtvkxDYeOtRsNEY4xMU9HHkcBVMpiUlFSFBuhtxy"
})
{
clientMutationId,
accessToken,
oauthToken{
accessToken,
refreshToken
}
}
}
Exemplo da resposta da API:
{
"data": {
"login": {
"clientMutationId": "0123456789",
"accessToken": "b64a0e34-24c5-39eb-b457-0c7331d176f0",
"oauthToken": {
"accessToken": "b64a0e34-24c5-39eb-b457-0c7331d176f0",
"refreshToken": "4a474832-1b48-4ae3-9ad9-1d767a48ebe6"
}
}
}
}
Caso o usuário queira utilizar uma rede social para se autenticar na API da Elo, ele deverá fazer uso da chamada socialNetworkOAuthLogin
. Assim como no fluxo descrito anteriormente, no retorno da função também é disponibilizado o access_token
que identifica o usuário de forma única.
Exemplo do corpo da requisição:
mutation {
socialNetworkOAuthLogin(input:{
clientMutationId: "0123456789",
provider: "FACEBOOK",
username: "user.name@gmail.com",
accessToken:"AAECEdEose0cBANynsVcZChZBxB3ysAuxDeZC3ZB4eIzkUKJnvoaTO1Vf4gyj8sl9bFFNPlnGU0Qsnh2fys7gcymWE7lKL64ygGLCJAtgyJtNq4YSGBkdDZBcgnAGZBKaGiI6emZCap8WJYO8ex06ZAZB75IdWnDtPoGCF8yPQnW4JZALHgeL1A1o6ZC5nz5uLD2lnVoUpkxAr1CNQABCD"
})
{
clientMutationId,
accessToken
}
}
Exemplo da resposta da API:
{
"data": {
"login": {
"clientMutationId": "0123456789",
"accessToken": "120faef6-5f31-3e74-afb2-864151c52880"
}
}
}
Já para atualizar o access_token
, é preciso utilizar a mutation refreshAccessToken
, descrita ao final desta sessão.
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
.
Através da mutation refreshAccessToken
, é possível realizar o fluxo de Atualização do accessToken. Esse fluxo consiste no envio para a API do refreshToken
que, após validar junto com o Authorization
enviado no header da requisição, retornará um novo accessToken
, e um novo refreshToken
, como exemplificado a seguir:
mutation {
refreshAccessToken(input: {
clientMutationId: "860e72f2-d58f-4bee-ad3a-532085f6f3eb",
refreshToken: "ccc0fba7-fa8d-3e85-a19e-2dc725bbb33d"
}) {
clientMutationId,
oauthToken{
accessToken,
refreshToken
}
}
}
Exemplo da resposta da API:
{
"data": {
"refreshAccessToken": {
"clientMutationId": "860e72f2-d58f-4bee-ad3a-532085f6f3eb",
"oauthToken": {
"accessToken": "ffd2b5cf-be8b-3a8a-802d-41983dea5872",
"refreshToken": "88803449-7c41-3c3f-adb2-3b32ef1a85ff"
}
}
}
}
Atenção!
Após a chamada desta mutation, o accessToken
e o refreshToken
enviados na requisição serão revogados - passando a valer apenas os tokens do retorno da mutation.
Caso um usuário não lembre sua senha e precise fazer o reset, existe um fluxo de Reset de Senha que pode ser feito. O primeiro passo é solicitar o envio de um pedido de reset de senha. Isso é feito através da mutation requestPasswordReset
.
Após a execução da mutation de solicitação, será enviado um e-mail ou um SMS para o contato especificado, com um token
que será usado para realizar o reset da senha, através da mutation passwordReset
.
Todos os casos de reset de senha são válidos apenas para contatos do tipo e-mail
e phone
.
Através da mutation requestPasswordReset
é possível solicitar o reset de duas formas:
Enviando o campo email
ou phone
(mas nunca ambos), sendo os mesmos contatos enviados no momento do cadastro, e que receberão o token para o reset da senha
Enviando o enum type
, que quando indicado EMAIL
ou PHONE
, enviará o token ao respectivo contato salvo no momento do cadastro do usuário
Abaixo, temos a primeira forma:
mutation {
requestPasswordReset(input: {
clientMutationId: "123456",
legalId: {
cpf: "12345678900"
},
email: "seu.email@provedor.com"
}) {
clientMutationId
maskedEmail
}
}
E a seguir, temos a solicitação de reset de senha através do enum type
:
mutation {
requestPasswordReset(input: {
clientMutationId: "123456",
legalId: {
cpf: "12345678900"
},
type: EMAIL
}) {
clientMutationId
maskedEmail
}
}
Após a chamada anterior e após o envio do token
através do e-mail/SMS para o contato especificado, é preciso utilizá-lo através da mutation passwordReset
, para fazer o reset da senha.
Da mesma forma, como na mutation anterior, é possível realizar de duas formas o reset de senha: ou enviando os campos de e-mail
/telefone
, ou informando o type
- e, assim, refenciar o contato salvo na criação do usuário.
Abaixo, temos um exemplo com o envio do campo e-mail
:
mutation {
passwordReset(input: {
clientMutationId: "1234567",
legalId: {
cpf: "12345678900"
},
email: "seu.email@provedor.com",
bcryptPassword: "$2a$12$yOCCL/0cbkvc5Lj/.EfnKeHm3oBPq28rGYbs8ayG8tbRYw4qtXflW",
token: "C68M59"
}) {
clientMutationId
user {
id
verified
username
name
firstName
}
}
}
Obs.: Lembrando que caso o token tenha sido solicitado usando phone
(SMS), é preciso enviar o phone
na requisição passwordReset
; caso requestPasswordReset
tenha sido solicitado usando email, se envia o campo email
na passwordReset
.
O bcryptPassword
enviado nessa mutation precisa ser gerado com o mesmo username
do usuário cadastrado e com a nova senha. Para saber como gerar esse campo, ver a seção BcryptPassword.
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.
Para consultar cartões utilizando filtros utiliza-se a query cards
, abaixo segue um exemplo de utilização.
query {
cards(filter:{
status:ACTIVE
}) {
edges{
node{
id
last4
expiry{
month
year
}
}
}
}
}
Neste exemplo estamos buscandos todos os cartões ativos. Outros filtros podem ser aplicados para esta consulta, como também pode ser solicitado outros retornos.
Para consultar cartão por identificador global único é utilizado a consulta node
. Abaixo segue um exemplo de utilização.
query {
node(id: "b63dcf70-08ae-423f-9459-db580b3d6e95") {
... on Card {
id
last4
status {
status
}
bin {
number
}
}
}
}
Neste exemplo estamos solicitando uma consulta de nó (node
) onde o identificador global único refere-se a um cartão. Outras informações de retorno podem ser solicitadas nesta requisição.
Também é possível listar os cartões pela consulta de usuário, como no exemplo abaixo.
query {
user {
cardHolders{
cards{
edges{
node{
id
last4
expiry{
month
year
}
}
}
}
}
}
}
Nesta requisição estamos listando os cartões de um portador utilizando a query de usuário. Outras informações podem ser solicitadas no retorno desta consulta.
Para atualizar um cartão é utilizado a função updateCard
. Abaixo segue um exemplo de utilização.
mutation {
updateCard(input:{
holderId: "d6f9605c-8da9-484a-bdb4-3e483db232ee",
billingAddress:{
country: "coutnry changed",
city: "city changed",
state: "SP changed",
number: 32,
place: "place changed"
}
status:SUSPENDED,
sensitive: "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway..."
}) {
card {
id
last4
expiry{
month
year
}
}
}
}
Neste exemplo estamos atualizando algumas informações do cartão - identificado pelo campo holderId
. Além de alterarmos o endereço de cobrança do cartão (campo billingAddress
) e seu status
, será atualizado a data de validade e o nome impresso no cartão.
Atenção: Para ser válida a atualização, é preciso que o PAN do cartão seja igual ao do cartão criado previamente.
Para deletar um cartão é utilizado a função deleteCard
. Abaixo segue um exemplo de utilização.
mutation {
deleteCard(input:{
cardId: "c049ac20-084b-46f1-ac03-817e855b5811"
}) {
cardId
last4
bin {
number
}
}
}
Neste exemplo estamos deletando o cartão identificado pelo campo cardId
, e solictando algumas informações do mesmo.
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
ouauthCode
e seus respectivos horários de entrada. Apenas um deles deve ser especificado.
Exemplo completo do JSON de sensitive
:
{
"pan": "1234567890123456",
"expiry": {
"month": 2,
"year": 2020
},
"name": "João da Silva",
"csc": "222",
"cscEntryTime": "2017-06-01T12:00:00-03:00"
}
Ou se preenchido por authCode
:
{
"pan": "1234567890123456",
"expiry": {
"month": 2,
"year": 2020
},
"name": "João da Silva",
"authCode": "AB123Z1Y",
"authCodeEntryTime": "2017-06-01T12:00:00-03:00"
}
O segundo passo é assinar os dados utilizando JSON Web Signature (JWS
) em formato compacto, e utilizando Elliptic Curve (EC
) como algoritmo de assinatura.
O terceiro passo é criptografar os dados do passo anterior utilizando a chave pública do servidor, que pode ser obtida a partir da query:
query {
serverPublicKey {
key
}
}
Tal criptografia será realizada utilizando JSON Web Encryption (JWE
) em formato compacto, e EC
como algoritmo de criptografia.
A estrutura de assinatura e criptografia segue a seguinte ideia:
JWE.Encrypt(recipient=ServerKey, format=compact,
JWS.Sign(issuer=UserKey, format=compact,
JSON.Stringify(CardSensitiveInput)
)
)
O quarto passo é cadastrar a chave pública do cliente a qual foi utilizada para assinar os dados sensíveis. Desta forma o servidor poderá validar a assinatura do cliente no processo de descriptografia do campo sensitive
. Abaixo segue um exemplo da mutation de cadastro de chave pública.
mutation {
addPublicKeyToUser(input:{
clientMutationId:"012",
userId:"bdc89491-f1f4-32f7-bad2-f44ae3b88aa6",
key:"{\"kty\":\"EC\", \"kid\":\"my-public-key-id-1\", \"x\":\"g_Sr4WwVDt5Qy3KonZyXqFwWykTR9KVMCt8Sx-dXSB8\",\"y\":\"ydSE-mUMtuhBTI_txDpd2ivb7e6FNzxq4e_18iHFZ2U\",\"crv\":\"P-256\"}",
format:JWK
}) {
clientMutationId,
user{
id,
firstName
,lastName
},
publicKey{
key
}
}
}
NOTA: o quarto passo só é necessário caso a chave pública que assinou os dados sensíveis não tenha sido cadastrada anteriormente.
A carteira é uma forma do usuário organizar seus cartões. Para criar uma carteira utilizando a API da ELO basta que o usuário seja um portador (CardHolder
) e faça uso da função CreateWallet
. Um exemplo de utilização dessa função pode ser vista abaixo:
mutation {
createWallet(
input: {
clientMutationId: "123",
cardHolderId: "fdf9f98e-a6ac-4878-ad45-cc133e4ca168",
name: "Carteira"
}
) {
clientMutationId,
wallet{
id,
name,
holder{
name,
firstName,
displayName
}
}
}
}
Após a criação da carteira serão retornados seus dados e a partir deles é possível fazer seu gerenciamento adicionando ou removendo cartões. Abaixo temos um exemplo de cada operação possível com a carteira criada.
Adicionar um cartão à carteira:
mutation {
addCardToWallet(
input:{
clientMutationId:"123",
walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51",
cardId: "2fde85bf-6935-4e9b-8262-94d82e08e4bd"
}
) {
clientMutationId,
wallet{
id,
name
},
card{
id
}
}
}
Remover cartão de uma carteira:
mutation{
removeCardFromWallet(
input:{
clientMutationId: "012",
walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51",
cardId: "2fde85bf-6935-4e9b-8262-94d82e08e4bd"}
) {
clientMutationId,
wallet{
name
},
card{
id
}
}
}
Atualizar a carteira:
mutation{
updateWallet(
input: {
clientMutationId: "123",
walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51",
name: "Carteira Principal"
}
) {
wallet {
id,
name
}
}
}
NOTA: Só é possível atualizar o nome da carteira.
Remover a carteira:
mutation{
deleteWallet(
input:{
clientMutationId: "012",
walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51"
}
) {
clientMutationId,
walletId,
name
}
}
Termos de Uso podem ser adicionados ao usuário, isso siginifica que o mesmo aceitou tal termo. Para listar os termos de uso basta utilizar a query agreementTerms
.
query{
agreementTerms(filter:{
nameContains: "",
agreementTermIds: [
"",
""
]
})
{
pageInfo{
hasPreviousPage
hasNextPage
}
totalCount
edges{
cursor
node{
id
title
description
url
}
}
}
}
Obs: Filtros podem ser aplicados na consulta de termos de uso, mais detalhes podem ser encontrados no argumento filter AgreementTermFilterInput
Adicionar Termo de Uso ao usuário:
Para adicionar um termo de uso ao usuário utiliza-se a mutation addAgreementToUser
.
mutation {
addAgreementToUser(input: {
clientMutationId: "012",
userId: "b1ca0944-7822-3538-920d-58b233154608",
agreementTermId: "e32a7918-eef5-41af-909b-f4c93cee2e22"
}) {
clientMutationId
user {
id
username
firstName
lastName
displayName
}
agreement {
agreementTerm {
id
title
description
url
}
}
}
}
Remover Termo de uso do usuário:
Para remover um termo de uso do usuário utiliza-se a mutation removeAgreementFromUser
mutation {
removeAgreementFromUser(input: {
clientMutationId: "013",
userId: "b1ca0944-7822-3538-920d-58b233154608",
agreementTermId: "e32a7918-eef5-41af-909b-f4c93cee2e22"
}) {
user {
id
firstName
lastName
}
agreementTerm {
id
description
url
}
}
}
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 aoaccess_token
do usuário.
Consultar o nome, CPF, RG e data de nascimento de um portador dado o identificador global único:
query {
node(id: "B8B1582B-1C2C-406B-9FC3-ACA842049207") {
... on CardHolder {
firstName
lastName
legalIds {
cpf {
number
}
rg {
number
issuerOrganization
issuerState
issueDate
}
}
birthday
}
}
}
NOTA: o parâmetro
id
se refere ao identificador global único do portador (CardHolder
).
Access_token:: Código de acesso disponibilizado pela API após a realização do login e que deve ser utilizado pelo desenvolvedor ao realizar as chamadas aos recursos disponibilizados. Ele é utilizado para validação do acesso e identificação do usuário que está realizando as operações na API.
Bcrypt: Algoritmo de criptografia do tipo hash utilizado para segurança de senhas (Wikipedia). No contexto desta API é o resultado do algoritmo bcrypt sobre o nome de usuário e senha.
BIN: Número de Identificação do Banco (Bank Identification Number). O BIN é relativo aos números iniciais de um cartão e identifica o emissor e produtos associados ao mesmo.
CardIssuer: Um usuário do tipo pessoa jurídica que emite cartões. Também conhecido como Emissor.
CardHolder: Um usuário do tipo pessoa física ou jurídica que possui cartões. Também conhecido como Portador.
Challenge: Resultado do algoritmo bcrypt aplicado sobre um salt gerado e o bcrypt do nome do usuário e senha.
Client_id: Identificador utilizado pela API para verificar e validar qual a aplicação está fazendo uso dos recursos disponibilizados. Sua geração é feita no momento que o desenvolvedor cria uma nova aplicação no portal de desenvolvedores.
Merchant: Um usuário do tipo pessoa jurídica que é um estabelecimento comercial e realiza transações com cartões.
PAN: Número da conta primária (Primary Account Number), também conhecido como "número do cartão".
Salt: Dado gerado de forma aleatório que é usado no algoritmo de criptografia junto da senha como uma forma de proteção evitando que o hash de dois dados iguais gerem o mesmo resultado.
Sensitive: Conteúdo sensível (Número do cartão, Nome do portador, Vencimento, etc) gerado a partir de um processo de assinatura e criptografia, cujo payload foi assinado a partir do uso de uma a chave privada do usuário e na sequência criptografado fazendo uso de uma chave pública do servidor.
Wallet: Carteira virtual utilizada para organizar cartões criados pelo portador dentro da API da ELO.
Query (consulta) compatível com a identificação de objetos do Relay
IDs são protegidos por permissões de contexto. Um node apenas pode ser buscado por seu identificador caso seja autorizado pelas permissões do usuário.
O retorno especifica a interface Node
que contém apenas o campo
id
, o qual já é designado como parâmetro. Portanto para utilizar
essa chamada utilize fragment
para especificar quais campos
retornar para cada tipo que implementa esta interface.
Fragmentos inline:
node(id: "identificador-global-123") {
__typename
... on Card {
last4
}
}
Fragmentos reusáveis:
fragment CardLast4Fragment on Card {
last4
}
node(id: "identificador-global-123") {
__typename
...CardLast4Fragment
}
Especificação de identificador global de objetos (Relay Global Object Identification Specification).
Argumentos:
id: ID
obrigatório
Identificador global único do nó (objeto) a ser consultado.
Query (consulta) cartões Card
Se executado por um portador de cartão, serão retornados todos os cartões que este possui. O mesmo que consultar os cartões deste portador.
Se executado por um emissor de cartão, serão retornados todos os cartões emitidos por este. O mesmo que consultar cartões emitidos por este emissor.
Em outros casos, como ao ser executado por um comerciante, um erro será produzido.
Argumentos:
first: Int
Limita a lista às primeiras entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para frente.
after: String
Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.
last: Int
Limita a lista às últimas entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para trás.
before: String
Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.
filter: CardFilterInput
Aplica filtro, se provido.
Query (consulta) portadores de cartões CardHolder
Argumentos:
first: Int
Limita a lista às primeiras entradas, caso definido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para frente.
after: String
Inicia após o cursor opaco, se definido. Utilizado em navegação para frente.
last: Int
Limita a lista às últimas entradas, caso definido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para trás.
before: String
Inicia antes do cursor opaco, se definido. Utilizado em navegação para trás.
filter: SearchFilterInput
Aplica filtro, se definido.
Query (consulta) de usuário por vários meios de entrada.
Esta consulta deve ser feita com apenas um parâmetro não-null
para designar o método de procura. Utilizar mais de um pode
resultar em resultados distintos em cada chamada.
Argumentos:
id: String
Procura o usuário pelo identificador global único
username: String
Procura o usuário pelo seu username
legalId: LegalIdsInput
Procura o usuário pelo seu documento
socialNetwork: SocialNetworkInput
Procura o usuário pelo seu username
na rede social especificada.
cardHolderId: String
Procura pelo usuário associado ao portador de cartões com o identificador global único especificado.
merchantId: String
Procura pelo usuário associado ao comerciante com o identificador global único especificado.
Caso o comerciante tenha mais de um usuário responsável, retorna o mais antigo.
Lista todos os Termos de uso conhecidos no sistema.
Argumentos:
first: Int
Limita a lista às primeiras entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para frente.
after: String
Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.
last: Int
Limita a lista às últimas entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para trás.
before: String
Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.
filter: AgreementTermFilterInput
Aplica filtro, se provido.
adiciona um cartão existente à uma carteira digital
Usável por:
Portadores de cartão
Argumentos:
input: AddCardToWalletInput
obrigatório
remove um cartão existente de uma carteira digital
Usável por:
Portadores de cartão
Argumentos:
input: RemoveCardFromWalletInput
obrigatório
Cria Carteira Digital para um portador.
Usável por:
Portadores de cartão
Argumentos:
input: CreateWalletInput
obrigatório
Apaga uma Carteira Digital.
As informações associadas à carteira serão automaticamente apagadas.
Informações que estão sendo utilizadas por outras entidades, como
Card
ou CardToken
ficarão vivas até que não tenham mais
referências, sendo coletadas automaticamente.
Usável por:
Portadores de cartão (o dono da carteira)
Argumentos:
input: DeleteWalletInput
obrigatório
Atualiza (Edita) informações de uma carteira digital.
Cartões e tokens não são manipulados por esta mutação, mas por mutações específicas:
addCardToWallet()
removeCardFromWallet()
createCardToken()
suspendCardToken()
Argumentos:
input: UpdateWalletInput
obrigatório
Cria um salt
para ser utilizado no desafio (challenge) de login()
.
Com a finalidade de evitar tráfego de senha utilizamos um desafio
(challenge) que é baseado em um salt
retornado por esta mutação.
O salt
retornado será associado ao username
e terá validade
especificada em expiry
.
Argumentos:
input: CreateLoginSaltInput
obrigatório
Realiza um novo acesso ao sistema utilizando nome do usuário e senha.
Em caso de sucesso esta chamada retorna a chave de acesso
(accessToken
), a qual deve ser armazenada e enviada em toda
requisição HTTP no cabeçalho access_token
. Exemplo (XXXYYYZZZ
é o valor retornado neste campo):
GET /graphql HTTP/1.1
...
access_token: XXXYYYZZZ
...
Um novo acesso não desfaz outros acessos existentes, para isto
utilize logout()
passando a chave de acesso retornada.
Para acesso utilizando redes sociais, utilize socialNetworkOAuthLogin()
.
NOTA: com a finalidade de evitar tráfego de senha utilizamos um desafio (challenge) que é baseado em um
salt
obtido com a mutaçãocreateLoginSalt()
. Logo é necessário iniciar o processo delogin()
com aquela mutação.
Argumentos:
input: LoginInput
obrigatório
Realiza um novo acesso ao sistema utilizando redes sociais (OAuth).
Um novo acesso não desfaz outros acessos existentes, para isto
utilize logout()
passando a chave de acesso retornada.
Para acesso utilizando usuário e senha, utilize login()
.
Argumentos:
input: SocialNetworkOAuthLoginInput
obrigatório
Cria um usuário.
As informações poderão ser posteriormente alteradas com
updateUser()
e a imagem com setImage()
.
Argumentos:
input: CreateUserInput
obrigatório
Cadastra um Cartão para um Portador.
O cadastro de um cartão deve ser feito pelo portador ou pelo emissor do cartão, sendo verificado:
Portador: se o usuário do sistema é associado ao portador
(CardHolder
), seja o seu pessoal ou um dos empresariais
associados.
Emissor: se o emissor é responsável pelo BIN do cartão, obtido
à partir do número do cartão (pan
) nos campos cifrados
sensitive
. O emissor deve ter permissão de criar cartões para
o portador, conseguindo assim o seu holderId
(CardHolder {
id }
).
Os dados do cartão são inferidos à partir do BIN, ou seja, do
prefixo do número do cartão (pan
) descrito em sensitive
.
Argumentos:
input: CreateCardInput
obrigatório
Apaga um cartão
Todas as informações associadas serão automaticamente apagadas.
Informações que estão sendo utilizadas por outras entidades, como
CardToken
ficarão vivas até que não tenham mais referências,
sendo coletadas automaticamente.
Argumentos:
input: DeleteCardInput
obrigatório
Atualiza um Cartão de um Portador.
A atualização de um cartão deve ser feita pelo portador ou pelo emissor do cartão, sendo verificado:
Portador: se o usuário do sistema é associado ao portador
(CardHolder
), seja o seu pessoal ou um dos empresariais
associados.
Emissor: se o emissor é responsável pelo BIN do cartão.
Argumentos:
input: UpdateCardInput
obrigatório
Inicia o processo de recuperação de senha para um usuário.
A recuperação de senha é um processo no qual um código de recuperação de senha é enviado para o email ou telefone do usuário, conforme registrado no sistema.
O usuário então acessa um link que apresenta um formulário
contendo o código enviado e pedindo a nova senha. Ambos devem ser
repassados para a mutação passwordReset()
.
O processo de recuperação de senha tradicional exige um documento legal, como por exemplo o CPF, e então envia um email com um link que leva para formulário de alteração de senha em nosso sistema.
Porém muitos usuários esquecem do email ou telefone que foram
cadastrados e ficam sem saber em qual procurar. Para isso é
retornado o meio de contato de forma mascarada, isso é,
parcialmente visível de forma a lembrar o usuário sem revelar
informações confidenciais e previne utilização do sistema de
recuperação de senha para mineração de dados dos usuários. Um
email `user@gmail.comficaria mascarado como
uxxx@gmail.com, já
first.last@company.comficaria
fxxxx.lxxx@company.com. De
maneira similar, um telefone celular
+55 (11) 99123-4567seria
apresentado como
+55 (11) 9xxx3-xx67`.
Outro caso que tratamos é de usuários associados a múltiplos emails e telefones e perderam acesso a eles. Por exemplo uma pessoa tinha cadastrado seu email corporativo e pessoal, porém deixou a empresa e consequentemente perdeu acesso ao email corporativo. Neste caso é oferecida a opção de especificar outro meio de contato, com a restrição que este deverá estar previamente cadastrado no sistema, evitando fraudes.
Adicionalmente, ao invés de utilizar o link para formulário em
nosso sistema, pode criar um formulário próprio, pedir a entrada
manual da chave de recuperação enviada e realizar a chamada
passwordReset()
.
Argumentos:
input: RequestPasswordResetInput
obrigatório
Finaliza o processo de recuperação de senha para um usuário, redefinindo-a.
A recuperação de senha é um processo iniciado pela mutação
requestPasswordReset()
no qual um código de recuperação de senha
é enviado para o email ou telefone do usuário, conforme registrado
no sistema.
O usuário então acessa um link que apresenta um formulário contendo o código enviado e pedindo a nova senha. Ambos devem ser repassados para esta mutação, a qual irá alterar a senha salva no sistema.
Em geral essa chama é realizada à partir do formulário em nosso sistema, o qual foi enviado na forma de link para o contato do usuário que deseja recuperar a senha.
Argumentos:
input: PasswordResetInput
obrigatório
Apaga um usuário
Todas as informações associadas como portadores, carteiras, contatos, redes sociais, termos aceitos e outros serão automaticamente apagadas.
Informações que estão sendo utilizadas por outras entidades, como
Card
ou CardToken
ficarão vivas até que não tenham mais
referências, sendo coletadas automaticamente.
Associações com CardIssuer
e Merchant
serão automaticamente
desfeitas.
Argumentos:
input: DeleteUserInput
obrigatório
Configura (altera) os campos do usuário
Para a imagem veja setImage()
Argumentos:
input: UpdateUserInput
obrigatório
Adiciona um portador de cartões ao usuário
Um usuário pode ter apenas um portador de cartões para sua pessoa
física (campos companyName
, companyLegalName
sendo null
) e
os demais deverão conter dados das pessoas jurídicas (companhias).
Argumentos:
input: CreateCardHolderForUserInput
obrigatório
Adiciona um emissor de cartões ao usuário
Um emissor pode ser gerenciado por múltiplos usuários e um usuário pode gerenciar vários emissores.
Caso o emissor já esteja associado, retorna erro.
Argumentos:
input: AddCardIssuerToUserInput
obrigatório
Adiciona um comerciante ao usuário
Um comerciante pode ser gerenciado por múltiplos usuários e um usuário pode gerenciar vários comerciantes.
Caso o comerciante já esteja associado, retorna erro.
Argumentos:
input: AddMerchantToUserInput
obrigatório
Adiciona uma chave pública ao usuário
Em geral cada dispositivo ou servidor associado ao usuário deverá
exportar uma chave pública a fim de poder enviar ou receber dados
sensíveis, tais como CardInterface { sensitive(keyId: "X") }
As chaves devem possuir um identificador id
único para o usuário
e será fornecido como keyId
para consultas ou mutações que
utilizem a chave pública, por exemplo para assinaturas (JSON Web
Signature - JWS) ou cifras (JSON Web Encryption - JWE).
As chaves associadas a um usuário estão disponíveis em
publicKeys
.
Argumentos:
input: AddPublicKeyToUserInput
obrigatório
Adiciona um termo aceito pelo usuário
Caso o termo já tenha sido aceito anteriormente, retorna erro.
Argumentos:
input: AddAgreementToUserInput
obrigatório
Remove um termo aceito pelo usuário
Indica que o usuário não aceita mais os termos. Pode retornar erro caso o termo não possa ser removido.
Argumentos:
input: RemoveAgreementFromUserInput
obrigatório
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.
Entrada para filtragens de busca com informações textuais.
Campos:
filter
:
String
Entrada para RG
Campos:
number
:
String
obrigatórionúmero do RG (dígitos) sem hífen ou pontos.
issuerOrganization
:
String
organização emissora do documento (exemplo: SSP
)
issuerState
:
String
estado de emissão do documento (exemplo: SP
)
issueDate
:
Date
data de emissão do documento
Entrada para LegalIds
Campos:
cpf
:
String
Número CPF sem hífen ou pontos
cnpj
:
String
Número CNPJ sem hífen ou pontos
Entrada com dados básicos para redes sociais.
Campos:
provider
:
String
obrigatórioNome do provedor da rede social, ex: Facebook, Twitter...
username
:
String
obrigatórioNome do usuário na rede social
Entrada para filtragens de busca por termo de uso.
Todos os campos especificados (não-null
) são aplicados
(comportamento AND
), para obter comportamento OR
, utilize várias
consultas.
Campos:
nameContains
:
String
Se null
ou vazio, não realiza filtragem.
Caso contrário, define texto que deve estar contido no nome do termo de uso.
agreementTermIds
:
ID
obrigatórioLista de identificadores globais únicos de termos (AgreementTerm
)
Se null
ou vazio, não realiza filtragem.
isWalletDigital
:
Boolean
Realiza o filtro pelos termos de uso, que são referentes a carteira digital. Se o valor informado for "true", somente os termos que forem de carteira digital, serão retornados. Se o valor informado for "false", somente os termos que não forem de carteira digital, serão retornados. Se o atributo não for informado na consulta, serão retornados todos os termos de uso, idenpendente se forem ou não de carteira digital.
Entrada para mutação addCardToWallet()
.
Informações sigilosas precisam ser transmitidas de forma criptografada utilizando-se a forma compacta JSON Web Encryption (JWE).
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
walletId
:
ID
obrigatórioO 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"
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órioO identificador global da carteira de onde se quer remover o cartão.
cardId
:
ID
obrigatórioO identificador global do cartão a ser removido. Deve ter sido previamente adicionado a carteira.
Entrada para mutação createWallet()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
name
:
String
obrigatórioEspecifica novo nome da carteira.
Entrada para mutação deleteWallet()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
walletId
:
ID
obrigatórioO identificador global da carteira a ser apagada.
O usuário do sistema deve ter permissão para apagar carteiras
do portador da carteira a ser apagada (Wallet { holder }
).
Entrada para mutação updateWallet()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
walletId
:
ID
obrigatórioO identificador global da carteira em que se quer editar informação.
name
:
String
obrigatórioSe provido, especifica novo nome da carteira.
Entrada para mutação createLoginSalt()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
username
:
String
obrigatórioNome do usuário para acesso ao sistema
Note que o salt
sempre será retornado, mesmo que o usuário não
exista.
Entrada para mutação login()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
username
:
String
obrigatórioNome do usuário para acesso ao sistema
challenge
:
String
obrigatórioResultado do desafio (challenge) de login()
.
Hash utilizando o algoritmo
bcrypt com salt
fornecido por createLoginSalt()
e conteúdo sendo o
bcryptPassword
especificado em createUser()
ou
updateUser()
. Código utilizando as bibliotecas
crypto e
bcrypt com
Node.js:
var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs
function sha256AsBase64(data) {
return crypto.createHash('sha256')
.update(data)
.digest('base64');
}
function bcryptSaltFromUsername(username) {
var hash = crypto.createHash('sha256').update(username).digest();
return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}
function bcryptUserPassword(username, password) {
var userSalt = bcryptSaltFromUsername(username);
return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}
var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);
var challengeSalt = createLoginSalt(username);
var challenge = bcrypt.hashSync(bcryptPassword, challengeSalt);
A String
final deve estar no formato padrão, com prefixo, custo,
salt
e por fim o valor computado em Base64, totalizando 60
caracteres. Por exemplo:
$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
Entrada para mutação socialNetworkOAuthLogin()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
provider
:
String
obrigatórioNome do provedor da rede social, ex: Facebook, Twitter...
username
:
String
obrigatórioNome 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
porlogin()
ousocialNetworkOAuthLogin()
.
Entrada com dados extras para redes sociais baseadas em OAuth
Campos:
accessToken
:
String
obrigatórioCaso 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
:
String
obrigatórioCaso o processo OAuth foi executado com sucesso, contém os escopos autorizados.
expiryTimestamp
:
DateTime
Caso o processo OAuth foi executado com sucesso, contém a data e
horário que o código de acesso (accessToken
) expira.
Entrada para renda anual de uma pessoa física.
Campos:
personal
:
Float
obrigatórioRenda anual pessoal (individual) da pessoa física.
family
:
Float
obrigatórioRenda anual total da família da pessoa física.
currency
:
String
obrigatórioMoeda associada aos valores informados.
Código da moeda com 3 letras
ISO4217
Exemplo: EUR
, USD
, BRL
...
Entrada para ítem de contato com o portador de cartão, como email ou telefone...
Campos:
type
:
PersonContactType
obrigatórioTipo 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órioValor do contato. Exemplos: +12345678
para telefone,
`user@server.com` para email, etc.
Entrada de Endereço Físico Mundial, que pode ser usado para envios ou contas
Campos:
context
:
String
Contexto do endereço, por exemplo: Casa, Trabalho, Matriz, Filial
Análogo a campo de mesmo nome em PersonContact
e CompanyContact
.
city
:
String
obrigatórioNome da cidade em UTF-8
state
:
String
obrigatórioNome 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
Número da construção
place
:
String
obrigatórioNome da via, para ser usado em conjunto com kind
e number
, compondo
a primeira linha de endereço.
complement
:
String
Complemento opcional, como número de apartamento.
reference
:
String
Ponto de referência (exemplo: próximo ao posto)
instructions
:
String
Instruções (exemplo: autorização do receptor)
lon
:
Float
Longitude, opcional: em graus.
Contém a longitude caso seja manualmente provido ou automaticamente
descoberto à partir do endereço. Caso não seja possível prover, será
null
.
lat
:
Float
Latitude, opcional: em graus.
Contém a latitude caso seja manualmente provido ou automaticamente
descoberto à partir do endereço. Caso não seja possível prover, será
null
.
Entrada para mutação createUser()
.
Nota: não existe um campo
image
a ser enviado, para tal utilize a mutaçãosetImage()
.
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órioNome 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...)
birthday
:
Date
Data de nascimento
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
:
Contatos do usuário.
São permitidos múltiplos contatos do tipo OTHER
desde que eles não se repitam. Para os demais tipos são
permitidos apenas um contato por tipo.
verifyContact
:
TypeContactVerification
Indica se o contato será verificado ou não no momento da criação do usuário.
Se enviada, informa qual o tipo de contato escolhido para a verificação.
originId
:
ID
Identificador único da origem da campanha
origin
:
String
Identifica a origem(campanha) do cadastro do usuário.
originUrl
:
String
Url de origem de cadastro do usuário
originChannelRaw
:
String
Parametros de web analytics brutos
originChannel
:
String
Campo tratado com os paramentros de mídia
localEvent
:
String
Cidade que estará recebendo o Show ou Evento
motherName
:
String
Nome da mãe do usuário.
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
.
city
:
String
obrigatórioNome da cidade em UTF-8
state
:
String
obrigatórioNome 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órioNúmero da construção
place
:
String
obrigatórioNome da via, para ser usado em conjunto com kind
e number
, compondo
a primeira linha de endereço.
complement
:
String
Complemento opcional, como número de apartamento.
reference
:
String
Ponto de referência (exemplo: próximo ao posto)
instructions
:
String
Instruções (exemplo: autorização do receptor)
lon
:
Float
Longitude, opcional: em graus.
Contém a longitude caso seja manualmente provido ou automaticamente
descoberto à partir do endereço. Caso não seja possível prover, será
null
.
lat
:
Float
Latitude, opcional: em graus.
Contém a latitude caso seja manualmente provido ou automaticamente
descoberto à partir do endereço. Caso não seja possível prover, será
null
.
Entrada para mutação 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órioConteúdo sensível (número do cartão, código de verificação e validade) o qual foi assinado e então cifrado conforme a estrutura a seguir.
Estrutura de assinatura e criptografia:
JWE.Encrypt(recipient=ServerKey, format=compact,
JWS.Sign(issuer=UserKey, format=compact,
JSON.Stringify(CardSensitiveInput)
)
)
Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.
O esquema define as seguintes chaves para o objeto de entrada
(CardSensitiveInput
):
pan
: O número da conta primária (Primary Account Number),
também conhecido como \"número do cartão\" físico. Exemplo:
"1234567890123456"
expiry
: Data de validade do cartão, ou seja, quando ele
expira. É um objeto composto pelas chaves month
e year
descritas a seguir. Exemplo: {"month": 2, "year": 2020}
month
: Mês da validade do cartão. Número inteiro entre 1
(Janeiro) e 12 (Dezembro).
year
: Ano da validade do cartão. Número inteiro com 4
dígitos (2017, não 17).
name
: Nome do portador do cartão. Exemplo: "João da Silva"
.
A autorização é feita com os campos csc
ou authCode
e seus
respectivos horários de entrada. Note que apenas um deles deve ser
especificado:
csc
: Código de segurança do cartão (Card Security Code),
usualmente impresso na parte de trás do cartão físico.
cscEntryTime
: Data e horário quando o CSC (Código de
Segurança do Cartão) foi digitado. É necessário quando o CSC é
gerado por um chaveiro/token baseado em tempo. Deve estar no
formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"
authCode
: Código de autorização. Este código não é o CSC
(Código de Segurança do Cartão) pois não está impresso no
cartão. Exemplo: "AB123Z1Y"
authCodeEntryTime
: Data e horário quando o código de
autorização (authCode
) foi digitado. Deve estar no formato
ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"
O número do cartão (pan
) será utilizado para descoberta dos
demais campos do cartão, como availableServices
, bin
,
funding
, product
, isInternational
, isCompany
, isToken
,
brand
, allowedCaptures
, usages
, network
, issuer
e
metadata
.
holderId
:
ID
obrigatórioIdentificador 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.
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órioIdentificador global único do cartão a apagar
Entrada para mutação updateCard()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
holderId
:
ID
obrigatórioIdentificador 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.
sensitive
:
String
Conteúdo sensível o qual foi assinado e então cifrado conforme a
estrutura a seguir. Deve ser utilizado apenas se não tiver acesso
ao identificador global único do cartão, neste caso deverá ser
utilizado cardId
.
Estrutura de assinatura e criptografia:
JWE.Encrypt(recipient=ServerKey, format=compact,
JWS.Sign(issuer=UserKey, format=compact,
JSON.Stringify(CardSensitiveInput)
)
)
Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.
O esquema define as seguintes chaves para o objeto de entrada
(CardSensitiveInput
):
pan
: (esse campo é obrigatório)
O número da conta primária (Primary Account Number), também conhecido
como "número do cartão" físico. Exemplo: "1234567890123456"
expiry
: (esse campo é obrigatório)
Data de validade do cartão, ou seja, quando ele expira. É um objeto composto
pelas chaves month
e year
descritas a seguir. Exemplo:
{"month": 2, "year": 2020}
month
: Mês da validade do cartão. Número inteiro entre 1
(Janeiro) e 12 (Dezembro).
year
: Ano da validade do cartão. Número inteiro com 4
dígitos (2017, não 17).
name
: Nome do portador do cartão. Exemplo: "Joao da Silva"
.
(não utilizar caracteres especiais ou acentos)
A autorização é feita com os campos csc
ou authCode
e seus
respectivos horários de entrada. Note que apenas um deles deve ser
especificado:
csc
: Código de segurança do cartão (Card Security Code),
usualmente impresso na parte de trás do cartão físico.
cscEntryTime
: Data e horário quando o CSC (Código de
Segurança do Cartão) foi digitado. É necessário quando o CSC é
gerado por um chaveiro/token baseado em tempo. Deve estar no
formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"
authCode
: Código de autorização. Este código não é o CSC
(Código de Segurança do Cartão) pois não está impresso no
cartão. Exemplo: "AB123Z1Y"
authCodeEntryTime
: Data e horário quando o código de
autorização (authCode
) foi digitado. Deve estar no formato
ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00"
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órioDocumento do usuário o qual deseja recuperar a senha
Pode-se especificar apenas um documento, por exemplo apenas o CPF ou CNPJ.
:
String
Email do usuário o qual deseja recuperar a senha.
Caso seja fornecido e esteja cadastrado no sistema será o meio
utilizado para envio da chave para recuperação de senha, conforme
exigido em passwordReset()
.
phone
:
String
Telefone do usuário o qual deseja recuperar a senha.
Caso seja fornecido e esteja cadastrado no sistema será o meio
utilizado para envio da chave para recuperação de senha, conforme
exigido em passwordReset()
.
type
:
PersonContactType
Tipo do contato no qual será enviado o TOKEN para realizar o reset da senha.
NOTA: apenas os tipos de contatos
PHONE
e
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órioDocumento do usuário o qual deseja recuperar a senha.
Este campo deve conter os mesmos valores passados por
RequestPasswordResetInput
para requestPasswordReset()
.
:
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órioA chave de recuperação de senha enviada por email ou telefone
após o processo iniciado com requestPasswordReset()
.
type
:
PersonContactType
Tipo do contato do usuário o qual deseja recuperar a senha.
NOTA: apenas os tipos de contatos
PHONE
e
bcryptPassword
:
String
obrigatórioHash utilizando o algoritmo bcrypt da nova senha do usuário.
Os parâmetros para cálculo do hash são:
cost
: 12
salt
: os 16 primeiros bytes do Hash utilizando o algoritmo
SHA256
do nome do usuário, codificados como base64
utilizando o alfabeto particular do bcrypt
.
data
: a representação Base64 do Hash utilizando SHA256
da
senha do usuário. Isto é necessário pois bcrypt
tem um limite
de 72 caracteres.
Ou seja:
var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs
function sha256AsBase64(data) {
return crypto.createHash('sha256')
.update(data)
.digest('base64');
}
function bcryptSaltFromUsername(username) {
var hash = crypto.createHash('sha256').update(username).digest();
return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}
function bcryptUserPassword(username, password) {
var userSalt = bcryptSaltFromUsername(username);
return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}
var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);
A String
deve ser serializada no formato padrão bcrypt
contendo o prefixo, custo, salt
e o hash serializado em Base64,
totalizando 60 caracteres. Por exemplo:
$2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
Entrada para mutação deleteUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
userId
:
ID
obrigatórioIdentificador global único do usuário a apagar
Entrada para mutação updateUser()
.
Nota: não existe um campo
image
a ser alterado, para tal utilize a mutaçãosetImage()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
id
:
ID
obrigatórioIdentificador 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
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
:
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.
São permitidos múltiplos contatos do tipo OTHER
desde que eles não se repitam. Para os demais tipos são
permitidos apenas um contato por tipo.
addresses
:
AddressUserInput
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.
motherName
:
String
Nome da mãe do usuário.
Entrada para CompanyLegalIds
Campos:
cnpj
:
String
Número CNPJ sem hífen ou pontos
Entrada para mutação createCardHolderForUser()
.
Um usuário pode ter apenas um portador de cartões para sua pessoa
física (campos companyName
, companyLegalName
sendo null
) e
os demais deverão conter dados das pessoas jurídicas (companhias).
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
userId
:
ID
obrigatórioIdentificador global único do Usuário que terá um portador associado
companyName
:
String
Nome da empresa, caso portador de cartões corporativos.
Para cartões corporativos (pessoa jurídica), este campo informa o
nome fantasia da empresa. Para a razão social, veja
companyLegalName
.
Para cartões de pessoa física será sempre null
. Note que apenas
um portador de cartões pessoa física existirá para o usuário.
companyLegalName
:
String
Nome legal da empresa, como escrito em documentos.
Para cartões corporativos (pessoa jurídica), este campo informa a
razão social da empresa. Para nome fantasia, veja companyName
Para cartões de pessoa física será sempre null
. Note que apenas
um portador de cartões pessoa física existirá para o usuário.
companylegalIds
:
CompanyLegalIdsInput
Documentos legais de identificação da empresa.
Para cartões de pessoa física será sempre null
. Note que apenas
um portador de cartões pessoa física existirá para o usuário.
Entrada para mutação addCardIssuerToUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
userId
:
ID
obrigatórioIdentificador global único do Usuário que será associado ao emissor
cardIssuerId
:
ID
obrigatórioIdentificador global único do emissor de cartões
Entrada para mutação addMerchantToUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
userId
:
ID
obrigatórioIdentificador global único do Usuário que será associado ao comerciante
merchantId
:
ID
obrigatórioIdentificador global único do comerciante
Entrada para mutação addPublicKeyToUser()
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
userId
:
ID
obrigatórioIdentificador global único do Usuário a adicionar chave pública
key
:
String
obrigatórioConteú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
.
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órioIdentificador global único do Usuário que aceitou o termo
agreementTermId
:
ID
obrigatórioIdentificador global único do termo aceito
timestamp
:
DateTime
Quando o termo foi aceito. Se null
então gerado automaticamente.
Entrada para mutação removeAgreementFromUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
userId
:
ID
obrigatórioIdentificador global único do Usuário o qual não aceita mais o termo.
agreementTermId
:
ID
obrigatórioIdentificador global único do termo previamente aceito
PageInfo
compatível com Relay.
Campos:
hasPreviousPage
:
Boolean
obrigatóriohasNextPage
:
Boolean
obrigatóriostartCursor
:
String
endCursor
:
String
Aresta de conexão contendo um Card
em conformidade com o
Relay.
Campos:
cursor
:
String
obrigatórioCursor opaco para ser usado com queries (consultas) after
ou
before
.
Conexão de Card
em conformidade com o
Relay.
Campos:
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.
Aresta de conexão contendo um CardHolder
em conformidade com o
Relay.
Campos:
cursor
:
String
obrigatórioCursor opaco para ser usado com queries (consultas) after
ou
before
.
Conexão de CardHolder
em conformidade com o
Relay.
Campos:
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.
Toda a possível identificação legal de uma pessoa ou empresa
Campos:
cnpj
:
CNPJ
cpf
:
CPF
rg
:
RG
Renda anual de uma pessoa física (individual e familiar).
Campos:
personal
:
Float
Renda anual pessoal (individual) da pessoa física.
family
:
Float
Renda anual total da família da pessoa física.
currency
:
String
Moeda associada aos valores informados.
Código da moeda com 3 letras
ISO4217
Exemplo: EUR
, USD
, BRL
...
Profissão (ocupação) de uma pessoa física.
Campos:
id
:
ID
obrigatórioIdentificador opaco da Profissão
Deve ser informado como entrada em mutações que precisam de profissão.
display
:
String
obrigatórioTexto a ser exibido ao usuário em formulários e consultas.
Este texto é localizado (traduzido) para a linguagem informada na consulta.
URL de imagem com tamanho e mimeType
.
Campos:
url
:
String
obrigatórioURL para acessar a imagem
width
:
Int
obrigatóriolargura em pixels
height
:
Int
obrigatórioaltura em pixels
mimeType
:
String
obrigatórioTipo do arquivo na convenção (MIME - Multipurpose Internet Mail
Extensions), como image/png
, image/jpeg
Ítem de contato com pessoa física, como email ou telefone...
Com o intuito de manter a privacidade, o campo value
pode ser
mascarado.
Campos:
type
:
PersonContactType
obrigatórioTipo 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órioValor 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
eNOT_APPLICABLE
.
Endereço Físico Mundial, que pode ser usado para envios ou contas
Campos:
context
:
String
Contexto do endereço, por exemplo: Casa, Trabalho, Matriz, Filial
Análogo a campo de mesmo nome em PersonContact
e CompanyContact
.
city
:
String
obrigatórioNome 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órioNome 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
.
Portador de cartão
Usualmente uma pessoa
Campos:
id
:
ID
obrigatórioIdentificador 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
.
birthday
:
Date
Data de nascimento
age
:
Int
Idade em anos
income
:
PersonYearlyIncome
Renda anual do portador (individual e familiar).
Este campo é informacional e pode ser utilizado no preenchimento de formulários de outros serviços, por exemplo para emissão de seguros.
occupation
(
language:
String
Língua a ser utilizada no retorno da consulta.
Por padrão adota-se a língua de quem faz a requisição, porém uma
diferente pode ser requisitada e está será utilizada, ou a mais
próxima disponível. O formato é: en_US
(Inglês dos EUA), en
(Inglês genérico), pt_BR
(Português do Brasil), pt
(Português genérico). O formato é o mesmo de IETF language
tag.
)
:
PersonOccupation
Profissão do portador.
Este campo é informacional e pode ser utilizado no preenchimento de formulários de outros serviços, por exemplo para emissão de seguros.
Por padrão adota-se a língua de quem faz a requisição, porém uma
diferente pode ser requisitada e está será utilizada, ou a mais
próxima disponível. O formato é: en_US
(Inglês dos EUA), en
(Inglês genérico), pt_BR
(Português do Brasil), pt
(Português
genérico). O formato é o mesmo de IETF language
tag.
image
(
width:
Int
Caso fornecido, largura da imagem, em pixels.
height:
Int
Caso fornecido, altura da imagem, em pixels.
mimeType:
String
Caso fornecido, o tipo de arquivo desejado (mime-type
).
)
:
ImageUrl
URL para foto de perfil.
Caso sejam providos sugestões de altura e largura (opcionais) para
o tamanho a ser mostrado, o servidor irá retornar a URL para a imagem
com o tamanho mais próximo ao requisitado.
Caso seja provido o mimeType
, a este será dada preferência, o que
é muito útil em dispositivos que lidam com um único formato de imagens.
Tanto o tamanho quanto o mimeType
da imagem apontada pela URL
são retornados.
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.
)
:
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
rewards
(
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:
RewardFilterInput
Aplica filtro, se provido.
)
:
RewardsConnection
Um estabelecimento comercial que realiza transações com cartões Elo.
Campos:
id
:
ID
obrigatórioname
:
String
obrigatóriolegalName
:
String
obrigatóriodescription
:
String
legalIds
:
CompanyLegalIds
obrigatóriocontacts
:
CompanyContact
obrigatóriourl
:
String
categories
:
MerchantCategory
obrigatórioCategorias de comerciantes (Código ISO, nome)
transactionFees
:
MerchantTransactionFees
obrigatórioPreç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.
Entidade do Emissor de Cartão
Campos:
id
:
ID
obrigatóriocode
:
Int
name
:
String
obrigatóriolegalName
:
String
obrigatóriodescription
:
String
legalIds
:
CompanyLegalIds
obrigatóriocontacts
:
CompanyContact
obrigatóriourl
:
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.
)
:
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.
Redes Social
Campos:
provider
:
String
obrigatórioNome do provedor da rede social, ex: Facebook, Twitter...
username
:
String
obrigatórioNome de usuário na rede social
Termo de uso aceito pelo usuário
Campos:
timestamp
:
DateTime
obrigatórioQuando o termo foi aceito
Chave de acesso (accessToken
) e informações sobre sua origem.
Campos:
accessToken
:
String
obrigatórioA chave de acesso (accessToken
) ativa para este usuário
timestamp
:
DateTime
obrigatórioQuando a chave de acesso (accessToken
) foi criada
ip
(
ipv6Mapped:
Boolean
)
:
String
Endereços de rede IPv4 ou IPv6 de onde partiu a solicitação de criação.
Se for IPv6, deve estar entre colchetes. Exemplo: [::1]
Se for IPv4, deve seguir a notação com pontos: 127.0.0.1
O opcional ipv6Mapped
estabelece que os endereços IPv4 sempre serão
codificados como IPv6 usando regras de mapeamento: [::ffff:127.0.0.1]
Pode ser null
se o endereço IP era desconhecido no momento de criação
da chave de acesso.
geolocation
:
Geolocation
Localização geográfica de onde partiu a solicitação de criação da
chave de acesso (accessToken
). Pode ser aproximada à partir do IP.
Pode ser null
.
device
:
Device
Dispositivo utilizado para a criação da chave de acesso
(accessToken
). Pode ser aproximado, por exemplo, usando o Agente
de Usuário (User-Agent) para identificar sistema operacional,
marca e modelo...
Campos:
id
:
String
obrigatórioIdentificador da chave para este usuário.
Em operações que retornem dados cifrados este será o identificador
da chave a ser especificado, como na consulta CardInterface {
sensitive(keyId: "X") }
Este identificador é gerado no momento que a chave é adicionada,
vide addPublicKeyToUser()
NOTA: tem escopo do usuário, não é global do sistema.
key
:
String
obrigatórioA chave serializada no formato requerido.
Se nenhum formato for especificado, será retornada como JSON Web Key - JWK
Entidade do Credenciador
Campos:
id
:
ID
obrigatórioname
:
String
obrigatóriolegalName
:
String
obrigatóriodescription
:
String
code
:
String
obrigatórioIdentificador Global Único do Credenciador junto a Elo.
Este campo identifica unicamente os números designados pela Elo para Estabelecimentos/Credenciador.
countryCode
:
String
obrigatórioIdentificador Global Único do país onde está localizado o Credenciador. Transações nacionais utiliza-se o código 076 (Brasil). ISO 3166-1 numeric
legalIds
:
CompanyLegalIds
obrigatóriocontacts
:
CompanyContact
obrigatóriourl
:
String
fraudTransactions
(
first:
Int
Limita a lista às primeiras entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para frente.
after:
String
Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.
last:
Int
Limita a lista às últimas entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para trás.
before:
String
Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.
filter:
CardFraudTransactionFilterInput
Aplica filtro, se provido.
Consulta as transações fraudulentas que já foram processadas.
Apenas CardIssuer
pode realizar essas consulta.
)
:
CardFraudTransactionsConnection
Lista de transações fraudulentas
Campos:
status
:
UserValidationStatus
obrigatórioStatus da validação dos dados do usuário
detail
:
String
Detalhes da validação. Retornado quando necessário validação adicional.
Campos:
items
:
UserPromotion
Lista de items que compõem esta página.
totalCount
:
Int
Contagem total de items nesta página.
totalPages
:
Int
Total de páginas disponíveis para consultas seguintes.
Usuário do Sistema
O usuário pode ser associado a um comerciante, emissor de cartões ou pode ser um portador de cartões.
Também são listadas as redes sociais que o usuário relacionou e autorizou, por exemplo via OAuth.
API Privada
Campos:
id
:
ID
obrigatórioIdentificador 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...)
birthday
:
Date
Data de nascimento
age
:
Int
Idade em anos
occupation
(
language:
String
Língua a ser utilizada no retorno da consulta.
Por padrão adota-se a língua de quem faz a requisição, porém uma
diferente pode ser requisitada e está será utilizada, ou a mais
próxima disponível. O formato é: en_US
(Inglês dos EUA), en
(Inglês genérico), pt_BR
(Português do Brasil), pt
(Português genérico). O formato é o mesmo de IETF language
tag.
)
:
PersonOccupation
Profissão do usuário.
Por padrão adota-se a língua de quem faz a requisição, porém uma
diferente pode ser requisitada e está será utilizada, ou a mais
próxima disponível. O formato é: en_US
(Inglês dos EUA), en
(Inglês genérico), pt_BR
(Português do Brasil), pt
(Português
genérico). O formato é o mesmo de IETF language
tag.
image
(
width:
Int
Caso fornecido, largura da imagem, em pixels.
height:
Int
Caso fornecido, altura da imagem, em pixels.
mimeType:
String
Caso fornecido, o tipo de arquivo desejado (mime-type
).
)
:
ImageUrl
URL para foto de perfil.
Caso sejam providos sugestões de altura e largura (opcionais) para
o tamanho a ser mostrado, o servidor irá retornar a URL para a imagem
com o tamanho mais próximo ao requisitado.
Caso seja provido o mimeType
, a este será dada preferência, o que
é muito útil em dispositivos que lidam com um único formato de imagens.
Tanto o tamanho quanto o mimeType
da imagem apontada pela URL
são retornados.
cardHolders
:
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
:
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
:
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
originId
:
ID
Identificador único da origem da campanha
origin
:
String
Identifica a origem(campanha) do cadastro do usuário.
analyticsId
:
ID
obrigatórioIdentificador Global Único para este objeto
motherName
:
String
Nome da mãe do usuário.
promotions
(
limit:
Int
obrigatórioLimita o número de items a serem retornados nesta query.
offset:
Int
obrigatórioRetorna os items a partir da posição definida.
filter:
UserPromotionsFilterInput
Aplica filtro, se provido.
)
:
UserPromotionsPage
communicationChannels
:
String
obrigatórioCanais de comunicação escolhidos pelo usuário.
Aresta de conexão contendo um AgreementTerms
em conformidade com o
Relay.
Campos:
cursor
:
String
obrigatórioCursor opaco para ser usado com queries (consultas) after
ou
before
.
Conexão de AgreementTerms
em conformidade com o
Relay.
Campos:
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.
Carteira digital (Digital Wallet)
Campos:
id
:
ID
obrigatórioIdentificador Global Único para este objeto
name
:
String
obrigatórioNome da carteira
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.
)
:
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.
Um cartão de crédito ou débito.
Campos:
id
:
ID
obrigatóriosensitive
(
keyId:
String
)
:
String
last4
:
String
status
:
CardStatusInterface
obrigatórioavailableServices
:
CardHolderService
obrigatóriousedServices
:
CardHolderService
obrigatórioproduct
:
CardProduct
isInternational
:
Boolean
isCompany
:
Boolean
isToken
:
Boolean
cardTokens
:
CardTokensConnection
Retorna uma conexão para os tokens relacionados a esse cartão
brand
:
CardBrand
allowedCaptures
:
CardCapture
obrigatóriousages
:
CardUsage
obrigatórionetwork
:
CardNetwork
metadata
:
CardMetadata
trackings
:
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.
)
:
CardTransactionCategorySummary
obrigatóriofraudTransactions
(
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
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.
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.
rewards
(
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:
RewardFilterInput
Aplica filtro, se provido.
)
:
RewardsConnection
Retorno da mutação removeCardFromWallet()
.
Compatível com Relay.
Campos:
Retorno da mutação createWallet()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
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.
Retorno da mutação updateWallet()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Retorno da mutação createLoginSalt()
Compatível com Relay.
Campos:
clientMutationId
:
String
username
:
String
obrigatórioNome do usuário para acesso ao sistema.
Mesmo que fornecido para createLoginSalt()
.
salt
:
String
obrigatórioValor 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órioData e horário de validade do salt
.
Retorno da mutação logout()
.
Compatível com Relay.
Campos:
accessToken
:
String
obrigatórioA chave de acesso expirada (accessToken
) de identificação do
usuário.
refreshToken
:
String
obrigatórioInformação que deve ser utilizada para gerar uma nova chave de accesso do usuário.
Retorno das mutações login()
ou socialNetworkOAuthLogin()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
accessToken
:
String
A chave de acesso (accessToken
) de identificação do
usuário. Deve ser armazenada e enviada em toda requisição HTTP
no cabeçalho access_token
. Exemplo (XXXYYYZZZ
é o valor
retornado neste campo):
GET /graphql HTTP/1.1
...
access_token: XXXYYYZZZ
...
@deprecated(reason: "Esse campo está sendo retornado dentro do campo oauthToken.")
Retorno da mutação createUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
id
:
ID
obrigatórioIdentificador Global Único para este usuário
name
:
String
Nome completo do portador como nos documentos oficiais (RG, CPF)
Retorno da mutação createCard()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
card
:
Card
O cartão criado e associado ao portador.
Note que o portador pode ser consultado em Card { holder }
.
Validade do cartão: Mês e Ano
Campos:
month
:
Int
obrigatórioMês - Janeiro é 1, Dezembro é 12
year
:
Int
obrigatórioAno - 4 dígitos, exemplo: 2017, não 17.
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óriopanSizeRange
:
IntRange
obrigatórioproduct
:
CardProduct
obrigatóriocountry
:
String
obrigatórioisInternational
:
Boolean
obrigatórioregexp
:
String
obrigatórioisP2PEligible
:
Boolean
Se true
, então o cartão poderá ser utilizado em transações P2P.
Se false
, então o cartão NÃO poderá ser utilizado em transações P2P.
isCompany
:
Boolean
obrigatórioSe 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órioDiz 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órioBandeira do Cartão
A bandeira responsável pelo Cartão. Para cartões da Elo,
sempre será Elo
.
allowedCaptures
:
CardCapture
obrigatórioModos de captura permitidos para o cartão.
Esta lista diz quais os modos de captura são permitidos para o
cartão, por exemplo se POS
então pode ser utilizado num ponto de
venda (Point Of Sale), caso contrário ao tentar utilizá-lo com
tal irá resultar em transação rejeitada.
usages
:
CardUsage
obrigatórioUsos 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órioRede 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órioEmissor 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órioMetadados 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
:
CardHolderService
obrigatórioServiç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.
changeableServices
:
CardHolderService
obrigatórioServiços (benefícios) disponíveis para troca, para o portador do cartão.
isMigrated
:
Boolean
Identificada se um BIN que não teve origem no FLEX, foi migrado para FLEX.
Se true
, identifica que foi migrado para o FLEX.
Se false
, identifica que ainda não foi migrado para o FLEX.
isFlex
:
Boolean
Identificada se um BIN é FLEX ou não.
Se true
, identifica que é um bin FLEX.
Se false
, identifica que ainda não é um BIN Flex.
authorizationDebit
:
binAuthorization
Informações de autorização e liquidação do cartão, para Débito.
authorizationCredit
:
binAuthorization
Informações de autorização do cartão, para Crédito.
is3DS
:
Boolean
Identifica se o BIN está habilitado para o processo de autenticação ELO (3DS Elo).
Se true
, está habilitado.
Se false
, não está habilitado.
creditSettlementBankNumber
:
Int
Número do Banco liquidante da operação de Débito
Indica qual o código do banco deverá ser utilizado para liquidar operações de crédito.
API Privada
debitSettlementBankNumber
:
Int
Número do Banco liquidante da operação de Débito
Indica qual o código do banco deverá ser utilizado para liquidar operações de crédito.
API Privada
Retorno da mutação deleteCard()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
cardId
:
ID
obrigatórioIdentificador 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.
holder
:
CardHolder
Nome e contato do portador do cartão
Pode ser nulo dependendo de permissões e acesso.
bin
:
BIN
Informações do BIN do cartão.
BIN (Bank Identification Number ou Número de Identificação do Banco) elucida várias propriedades do cartão, por exemplo banco emissor, uso, metadados (imagens) e afins.
Pode ser null
em caso de falta de permissão.
Retorno da mutação updateCard()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Retorno da mutação requestPasswordReset()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
maskedEmail
:
String
Retorna versão mascarada do email que receberá a chave de recuperação de acesso.
Esta informação permite ao usuário distinguir dentre vários emails que podem estar cadastrados no sistema e identificar qual deverá verificar a chave. Por exemplo um usuário tem cadastrado os seguintes emails:
O mascaramento de emails permitirá identificar qual foi enviado:
Pode ser nulo caso o código tenha sido enviado para um telefone, neste caso
verifique maskedPhone
maskedPhone
:
String
Retorna versão mascarada do telefone que receberá a chave de recuperação de acesso.
Esta informação permite ao usuário distinguir dentre vários telefones que podem estar cadastrados no sistema e identificar qual deverá verificar a chave. Por exemplo um usuário tem cadastrado os seguintes telefones:
+55 (11) 99123-4567
+55 (21) 99999-1234
O mascaramento de telefones permitirá identificar qual foi enviado:
+55 (11) 9xxx3-xx67
+55 (21) 9xxx9-xx34
Pode ser nulo caso o código tenha sido enviado para um email, neste caso
verifique maskedEmail
Retorno da mutação passwordReset()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
user
:
User
Em caso de sucesso contém o usuário o qual teve sua senha alterada.
Em caso de falha, como por exemplo um token
inválido ou senha
fora dos padrões determinados, será retornado null
.
Retorno da mutação deleteUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
userId
:
ID
obrigatórioIdentificador global único do usuário apagado
username
:
String
obrigatórioNome do usuário apagado
name
:
String
Nome completo do portador como nos documentos oficiais (RG, CPF)
firstName
:
String
Primeiro nome do usuário apagado
lastName
:
String
Último nome do usuário apagado
displayName
:
String
Nome de exibição do usuário apagado
Retorno da mutação updateUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Retorno da mutação createCardHolderForUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Retorno da mutação addCardIssuerToUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Retorno da mutação addPublicKeyToUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
publicKey
:
PublicKey
A chave adicionada.
Note que o campo publicKey { id }
contém o identificador da
chave a ser utilizado em outras operações como
removePublicKeyFromUser(keyId: "X")
ou
CardInterface { sensistive(keyId: "X") }
Retorno da mutação addAgreementToUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Termo de Uso
Campos:
id
:
ID
obrigatórioIdentificador Global Único para este objeto
title
:
String
obrigatórioTítulo deste termo
description
:
String
Descrição do termo
url
:
String
Endereço da Página com informações sobre o termo
category
:
AgreementTermCategory
Categoria do termo de uso
isWalletDigital
:
Boolean
Identifica se o termo de uso é referente a carteira digital ou não.
Retorno da mutação removeAgreementFromUser()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
agreementTerm
:
AgreementTerm
O termo previamente aceito e que já não consta mais em User { agreements }
Node compatível com Relay.
Campos:
id
:
ID
obrigatórioIdentificador Global Único para este objeto
Estado do cartão
Cada estado possui seu próprio payload em implementações específicas de
CardStatusInterface
. Use fragmentos para consultar seus campos.
Valores possíveis:
INACTIVE
Cartão não foi ativado
ACTIVE
Cartão foi ativado e está pronto para o uso
SUSPENDED
Cartão foi suspenso e não pode ser utilizado
Financiamento do cartão: crédito, débito, múltiplo, Alimentação e Refeição.
Valores possíveis:
CREDIT
Cartão de Crédito
DEBIT
Cartão de Débito
MULTIPLE
Cartão de Crédito e Débito (ambos simultaneamente).
MEAL
Cartão de benefícios (Refeição)
FOOD
Cartão de benefícios (Alimentação)
PREPAID
Cartão pré pago
VOUCHER
Voucher
MULTIPLE_PREPAID
Cartão multiplo pré-pago
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.
Opções de estado civil
Valores possíveis:
DIVORCED
Divorciado
MARRIED
Casado
SINGLE
Solteiro
WIDOWED
Viúvo
COMMON_LAW_MARRIED
União estável
Tipos de contato válidos para a verificação de contato.
Valores possíveis:
PHONE
Telefone
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
IM
aplicativo de mensagens instantâneas O valor é um identificador de usuário com o campo de contexto
OTHER
valor que segue texto livre
Formato de Chave criptográfica a ser serializada ou interpretada.
Valores possíveis: