Reward

A API Reward (Minutrade) possibilita solicitar a geração de bilhetes de promoções por portadores de cartão da Elo.

Feito para:  Portadores de Cartão

Primeiros passos

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

  2. Crie uma conta no portal do desenvolvedor.

  3. Cadastre sua primeira aplicação.

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

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

Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista

O intuito dessa API é oferecer ao portador de cartão facilidade e transparência ao solicitar a geração de vouchers para concorrer a promoções específicas da Elo em APIs de parceiros.

A solicitação do voucher é feita através da mutation requestReward, onde é necessário informar o "cardId" do cartão cadastrado anteriormente e o identificador do benefício "compositionId" que será utilizado para validar o benefício solicitado.

Exemplo:

mutation {
  requestReward(input: {
      cardId: "cdfad9cf-35cd-4d25-b3e3-1e72d665db65"
      compositionId: "b20893a7-5fff-49de-90cb-b7e99ed7e9e8"
    }) {
    id
    status
    compositionId
    description
    requestedDate
    bin{
      number
    }
  }
}

É possível consultar os vouchers solicitados e filtrá-los por status: APPROVED, REQUESTED e ERROR.

As consultas podem ser realizadas, utilizando os exemplos abaixo. O filtro pode ser aplicado para o Card Holder ou para o Card.

Exemplo de query, que traz todos os vouchers com o status APPROVED, do Card Holder.

query{
  user {
    cardHolders {
      rewards(filter: {
        status: APPROVED
      }) {
        edges {
          node {
            id
            bin {
              number
            }
            description
            compositionId
            voucher
            status
          }
        }
      }
    }
  }
}

Exemplo de query, que traz todas as recompensas com o status APPROVED, do Card.

{
  user {
    cardHolders {
      id
      name
      cards {
        edges {
          node {
            rewards(filter: {status: APPROVED}) {
              edges {
                node {
                  id
                  bin {
                    number
                  }
                  description
                  compositionId
                  voucher
                  status
                }
              }
            }
          }
        }
      }
    }
  }
}

É possível solicitar o reenvio das informações do voucher solicitado para o e-mail do portador de cartão através da mutation resendReward.Caso o processo tenha ocorrido com sucesso, será enviado um e-mail com as informações do voucher.

mutation {
  resendReward(input: {
      rewardId: "b50cd0db-b348-4774-9d87-729dfe3e50ee"
    }) {
    maskedEmail
  }
}



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.






Solicita a recompensa de um benefício disponível para o portador.

Argumentos:

input: RequestRewardInput obrigatório



Solicita o reenvio do comprovante da recompensa de um benefício solicitado pelo portador anteriormente.

Argumentos:

input: ResendRewardInput obrigatório






Entrada para RG

Campos:

number

:

String obrigatório

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


issuerOrganization

:

String

organização emissora do documento (exemplo: SSP)


issuerState

:

String

estado de emissão do documento (exemplo: SP)


issueDate

:

Date

data de emissão do documento



Entrada para LegalIds

Campos:

cpf

:

String

Número CPF sem hífen ou pontos


cnpj

:

String

Número CNPJ sem hífen ou pontos


rg

:

RGInput

documento de Registro Geral (RG)



Entrada com dados básicos para redes sociais.

Campos:

provider

:

String obrigatório

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


username

:

String obrigatório

Nome do usuário na rede social



Campos:

compositionId

:

ID obrigatório

Identificador do benefício solicitado.


cardId

:

ID obrigatório

Identificador global único do cartão para o qual o benefício está disponível.



Campos:

rewardId

:

ID obrigatório

Identificador único da recompensa.






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

Campos:

cnpj

:

CNPJ

cpf

:

CPF

rg

:

RG


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

Campos:

personal

:

Float

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


family

:

Float

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


currency

:

String

Moeda associada aos valores informados.

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



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

Campos:

id

:

ID obrigatório

Identificador opaco da Profissão

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


display

:

String obrigatório

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

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



URL de imagem com tamanho e mimeType.

Campos:

url

:

String obrigatório

URL para acessar a imagem


width

:

Int obrigatório

largura em pixels


height

:

Int obrigatório

altura em pixels


mimeType

:

String obrigatório

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



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

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

Campos:

type

:

PersonContactType obrigatório

Tipo designa como interpretar o valor, podendo ser telefone, email, ou aplicativo de mensagens instantâneas.


context

:

String

Contexto do contato, que varia com o tipo:

  • Se o tipo for PHONE ou EMAIL, este poderia ser: vendas, suporte ...

  • Se o tipo for IM, pode ser: skype, whatsapp, facebook messenger...

  • Se for OTHER, pode ser qualquer texto


value

:

String obrigatório

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

Este campo pode ser transformado dependendo de regras de acesso e permissões. Um comerciante pode receber valores mascarados com o intuito de manter a privacidade da pessoa física. Um exemplo seria receber apenas os últimos 4 dígitos do telefone, ou apenas as primeiras letras do email seguida do domínio.


verified

:

VerifiedStatus

O processo de verificação é feito por nosso sistema enviando uma mensagem ao contato e então pedindo que a chave enviada seja reenviada ao sistema.

NOTA: apenas os tipos de contatos PHONE e EMAIL são verificáveis. Os demais retornarão sempre NOT_APPLICABLE.



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

Campos:

context

:

String

Contexto do endereço, por exemplo: Casa, Trabalho, Matriz, Filial

Análogo a campo de mesmo nome em PersonContact e CompanyContact.


country

:

String obrigatório

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


city

:

String obrigatório

Nome da cidade em UTF-8


state

(


abbrev:

Boolean

)

:

String

Nome do estado por completo ou abreviado (opcional).

Abreviações de estados podem não estar disponíveis para alguns países, casos em que o nome por completo é retornado.


zip

:

String

Código postal (opcional)


district

:

String

Distrito opcional


kind

:

String

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


number

:

Int

Número da construção


place

:

String obrigatório

Nome da via, para ser usado em conjunto com kind e number, compondo a primeira linha de endereço.


complement

:

String

Complemento opcional, como número de apartamento.


reference

:

String

Ponto de referência (exemplo: próximo ao posto)


instructions

:

String

Instruções (exemplo: autorização do receptor)


lon

:

Float

Longitude, opcional: em graus.

Contém a longitude caso seja manualmente provido ou automaticamente descoberto à partir do endereço. Caso não seja possível prover, será null.


lat

:

Float

Latitude, opcional: em graus.

Contém a latitude caso seja manualmente provido ou automaticamente descoberto à partir do endereço. Caso não seja possível prover, será null.



Portador de cartão

Usualmente uma pessoa

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


name

:

String

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


firstName

:

String

Primeiro nome do portador


lastName

:

String

Último nome do portador


displayName

:

String

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


companyName

:

String

Nome da empresa.

Para cartões corporativos (pessoa jurídica), este campo informa o nome fantasia da empresa. Para a razão social, veja companyLegalName.

Para cartões de pessoa física será sempre null.


companyLegalName

:

String

Nome legal da empresa, como escrito em documentos.

Para cartões corporativos (pessoa jurídica), este campo informa a razão social da empresa. Para nome fantasia, veja companyName

Para cartões de pessoa física será sempre null.


legalIds

:

LegalIds

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


birthday

:

Date

Data de nascimento


age

:

Int

Idade em anos


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncome

Renda anual do portador (individual e familiar).

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


occupation

(


language:

String

Língua a ser utilizada no retorno da consulta.

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

)

:

PersonOccupation

Profissão do portador.

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

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


image

(


width:

Int

Caso fornecido, largura da imagem, em pixels.

height:

Int

Caso fornecido, altura da imagem, em pixels.

mimeType:

String

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

)

:

ImageUrl

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


contacts

:

list de PersonContact obrigatório

Contatos do portador de cartão


addresses

:

list de Address obrigatório

Endereço postal


wallets

:

list de Wallet obrigatório

Carteiras em posse deste portador de cartão.


cards

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

CardFilterInput

Aplica filtro, se provido.

)

:

CardsConnection

Cartões em posse.

Lista todos os cartões de um portador utilizando paginação e um filtro opcional.

Note que nem todos os campos de um cartão serão retornados pois estes têm privacidade restrita ao portador, emissor ou demais entidades autorizadas pela plataforma.

Opcionalmente pode-se utilizar o filter para selecionar apenas cartões de um certo emissor, produto, que oferece algum serviço ou que tenha alguma restrição de uso.


cardTokens

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

CardTokenFilterInput

Aplica filtro, se provido.

)

:

CardTokensConnection

Query (consulta) tokens CardToken


travelInsurances

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

TravelInsuranceFilter

Aplica filtro, se provido.

)

:

TravelInsurancesConnection

Seguros Viagem relacionados ao portador.

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

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

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


extendedWarrantyInsurances

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

ExtendedWarrantyInsuranceFilter

Aplica filtro, se provido.

)

:

ExtendedWarrantyInsurancesConnection

Seguros de Garantia Estendida relacionados ao portador.

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

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

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


purchaseProtectionInsurances

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

PurchaseProtectionInsuranceFilter

Aplica filtro, se provido.

)

:

PurchaseProtectionInsurancesConnection

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

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

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

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


homeAssistences

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

HomeAssistenceFilter

Aplica filtro, se provido.

)

:

HomeAssistencesConnection

Assistência residencial solicitadas pelo portador.

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

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

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


documents

(


first:

Int

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

after:

String

, se provido. Utilizado em navegação para frente.

last:

Int

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

before:

String

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

filter:

DocumentsFilterInput

Aplica filtro, se provido.

)

:

DocumentConnection

Query (consulta) documentos enviados para verificação


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

name

:

String

legalName

:

String

legalIds

:

MerchantEcLegalIds

address

:

MerchantEcAddress

categories

:

list de MerchantCategory

Categorias de comerciantes (Código ISO, nome)


transactionFees

:

list de MerchantTransactionFees

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

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

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

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

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



Entidade do Emissor de Cartão

Campos:

id

:

ID obrigatório

code

:

Int

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

image

(


width:

Int

height:

Int

mimeType:

String

)

:

ImageUrl

legalIds

:

CompanyLegalIds obrigatório

contacts

:

lista obrigatória de CompanyContact obrigatório

addresses

:

lista obrigatória de Address obrigatório

url

:

String

cards

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

CardFilterInput

Aplica filtro, se provido.

)

:

CardsConnection

Consulta todos os objetos de cartão (Card) disponíveis no contexto.

Se executado por um portador de cartão, serão retornados todos os cartões que este possui e foram emitidos por este emissor.

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

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



Redes Social

Campos:

provider

:

String obrigatório

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


username

:

String obrigatório

Nome de usuário na rede social



Termo de uso aceito pelo usuário

Campos:

agreementTerm

:

AgreementTerm obrigatório

O termo que foi aceito


timestamp

:

DateTime obrigatório

Quando o termo foi aceito



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

Campos:

accessToken

:

String obrigatório

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


timestamp

:

DateTime obrigatório

Quando a chave de acesso (accessToken) foi criada


ip

(


ipv6Mapped:

Boolean

)

:

String

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

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

O opcional ipv6Mapped estabelece que os endereços IPv4 sempre serão codificados como IPv6 usando regras de mapeamento: [::ffff:127.0.0.1]

Pode ser null se o endereço IP era desconhecido no momento de criação da chave de acesso.


geolocation

:

Geolocation

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

Pode ser null.


device

:

Device

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



Campos:

id

:

String obrigatório

Identificador da chave para este usuário.

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

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

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


key

:

String obrigatório

A chave serializada no formato requerido.

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



Entidade do Credenciador

Campos:

id

:

ID obrigatório

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

code

:

String obrigatório

Identificador Global Único do Credenciador junto a Elo.

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


countryCode

:

String obrigatório

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


image

(


width:

Int

height:

Int

mimeType:

String

)

:

ImageUrl

legalIds

:

CompanyLegalIds obrigatório

contacts

:

lista obrigatória de CompanyContact obrigatório

addresses

:

lista obrigatória de Address obrigatório

url

:

String

fraudTransactions

(


first:

Int

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

after:

String

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

last:

Int

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

before:

String

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

filter:

CardFraudTransactionFilterInput

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

)

:

CardFraudTransactionsConnection

Lista de transações fraudulentas



Campos:

status

:

UserValidationStatus obrigatório

Status da validação dos dados do usuário



Campos:

items

:

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



Assunto de interesse

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


title

:

String obrigatório

Título deste interesse de usuário


description

:

String

Descrição do interesse de usuário



Campos:

id

:

ID obrigatório

cpf

:

String obrigatório

status

:

CommunicationChannelBlockStatus obrigatório

begin

:

Date obrigatório

end

:

Date obrigatório


Usuário do Sistema

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

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

API Privada

Campos:

id

:

ID obrigatório

Identificador Global Único para este objeto


verified

:

VerifiedStatus

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

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


username

:

String

Nome do usuário para acesso ao sistema


name

:

String

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


firstName

:

String

Primeiro nome do usuário


lastName

:

String

Último nome do usuário


displayName

:

String

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


legalIds

:

LegalIds

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


birthday

:

Date

Data de nascimento


age

:

Int

Idade em anos


gender

:

Gender

Masculino ou Feminino, conforme documentos oficiais


maritalStatus

:

MaritalStatus

Estado civil


income

:

PersonYearlyIncome

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


occupation

(


language:

String

Língua a ser utilizada no retorno da consulta.

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

)

:

PersonOccupation

Profissão do usuário.

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


image

(


width:

Int

Caso fornecido, largura da imagem, em pixels.

height:

Int

Caso fornecido, altura da imagem, em pixels.

mimeType:

String

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

)

:

ImageUrl

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


contacts

:

list de PersonContact obrigatório

Contatos do usuário


addresses

:

list de Address obrigatório

Endereços postais


cardHolders

:

list de CardHolder obrigatório

Portadores de cartões associados ao usuário

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

Relação: 1:n


merchants

:

list de MerchantEC obrigatório

Comerciantes associados ao usuário

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

Relação: n:n


cardIssuers

:

list de CardIssuer obrigatório

Emissores de cartões associados ao usuário

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

Relação: n:n


socialNetworks

:

list de SocialNetwork obrigatório

Redes sociais relacionadas ao usuário


agreements

:

list de UserAgreement obrigatório

Termos de uso aceitos pelo usuário


accessTokens

:

list de AccessTokenInfo obrigatório

Lista de chaves de acesso ativas para este usuário


publicKeys

:

list de PublicKey obrigatório

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


originId

:

ID

Identificador único da origem da campanha


origin

:

String

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


analyticsId

:

ID obrigatório

Identificador Global Único para este objeto


acquirer

:

Acquirer

validation

:

UserValidation obrigatório

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


motherName

:

String

Nome da mãe do usuário.


userIdSha256

:

String

Sha256 do id do usuário


createdDate

:

DateTime

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


updatedDate

:

DateTime

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


promotions

(


limit:

Int obrigatório

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

offset:

Int obrigatório

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

filter:

UserPromotionsFilterInput

Aplica filtro, se provido.

)

:

UserPromotionsPage

communicationChannels

:

list de String obrigatório

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


interests

:

list de UserInterest obrigatório

Assuntos de interesse do usuário


communicationChannelBlocks

:



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

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

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

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

A tabela de BIN é dinâmica:

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

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

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

Campos:

number

:

String obrigatório

panSizeRange

:

IntRange obrigatório

funding

:

CardFunding obrigatório

product

:

CardProduct obrigatório

country

:

String obrigatório

isInternational

:

Boolean obrigatório

regexp

:

String obrigatório

isP2PEligible

:

Boolean

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


isCompany

:

Boolean obrigatório

Se true, então o cartão é corporativo, ou seja, pessoa jurídica. Se false, então o cartão é para pessoas físicas.


isToken

:

Boolean obrigatório

Diz se o cartão é virtual (token, vide CardToken).

Tokens são muitas vezes compreendidos como "cartões virtuais" (VCN - Virtual Card Numbers), eles são associados a um cartão real e podem ter maior controle, como restrição de moeda, número de compras, valor das compras, categoria de comerciante e outros.

O maior uso de tokens é para reduzir problemas com segurança, seja de um comerciante ou portador.

Se true, então este BIN é utilizado para tokens ao invés de cartões físicos (plástico). Se false então este BIN é utilizado para cartões tradicionais, físicos (plástico).


brand

:

CardBrand obrigatório

Bandeira do Cartão

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


allowedCaptures

:

lista obrigatória de CardCapture obrigatório

Modos de captura permitidos para o cartão.

Esta lista diz quais os modos de captura são permitidos para o cartão, por exemplo se POS então pode ser utilizado num ponto de venda (Point Of Sale), caso contrário ao tentar utilizá-lo com tal irá resultar em transação rejeitada.


usages

:

lista obrigatória de CardUsage obrigatório

Usos permitidos permitidos para o cartão.

Esta lista diz se o cartão pode ser utilizado para débito, para crédito à vista, crédito parcelado pela loja, dentre outros.


network

:

CardNetwork obrigatório

Rede para uso do Cartão.

Cada cartão deve ser utilizado em uma rede, a qual é listada neste campo. Por exemplo os cartões Elo utilizam as redes:

  • Elo: uso doméstico (isInternational = false);

  • Elo-Discovery: uso internacional.


issuer

:

CardIssuer obrigatório

Emissor do cartão.

Todo BIN está associado a um e apenas um emissor, o qual pode ser consultado com este campo para obtenção do identificador global único, razão social, nome fantasia, CNPJ, endereço, contatos e afins.


metadata

:

CardMetadata obrigatório

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

Metadados tais como:

  • imagem

  • cores Estes deverão ser utilizados para apresentação de um cartão ao usuário de modo a esclarecer a informação e evitar erros.


services

:

lista obrigatória de CardHolderService obrigatório

Serviços (benefícios) disponíveis ao portador do cartão.

Os serviços, também conhecidos como benefícios, ao portador. Por exemplo:

  • Seguro Viagem, para compra de passagens aéreas;

  • Proteção de Compra, para compra de bens;

  • Garantia Estendida, para compra de bens;

  • Acesso ao WiFi.


changeableServices

:

list de CardHolderService obrigatório

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


currency

:

String

Moeda


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



Campos:

id

:

ID obrigatório

Identificador único da recompensa.


bin

:

BIN obrigatório

BIN do cartão para o qual a recompensa está associada.


cardId

:

ID obrigatório

Identificador global único do cartão para o qual a recompensa está associada.


description

:

String

Descrição da recompensa.


compositionId

:

ID obrigatório

Identificador da composição.


status

:

RewardStatus obrigatório

Status da recompensa.


requestedDate

:

DateTime obrigatório

Data de solicitação da recompensa.



Campos:

maskedEmail

:

String

E-mail(descaracterizado) do portador utilizado para o reenvio do comprovante da recompensa.





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 gênero


Valores possíveis:


FEMALE


MALE




Opções de estado civil


Valores possíveis:


DIVORCED

Divorciado


MARRIED

Casado


SINGLE

Solteiro


WIDOWED

Viúvo


COMMON_LAW_MARRIED

União estável




Status da recompensa


Valores possíveis:


REQUESTED


APPROVED


ERROR