Cadastro do Portador
A interface de programação referente ao Cadastro do Portador é primariamente composta por consultas que retornam o tipo `CardHolder` e destes consultam-se os campos como nome, documentos, endereços, contatos e demais informações.
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.
cardHolders {
companyLegalName,
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 }],
pageInfo { hasPreviousPage },
isInternational,
capture { id, name },
Essa seção tem como objetivo detalhar alguns processos e trazer o passo-a-passo para integração com itens da API de Cadastro de Portador ELO.
A plataforma ELO de API foi construída pensando em expor as mais diversas informações para os mais diversos clientes de API possíveis, sejam eles bancos, estabelecimentos comerciais, pessoas físicas ou qualquer outro consumidor.
Dado esse cenário, houve a necessidade de se utilizar um protocolo que pudesse ser flexível e ao mesmo tempo seguro para autenticar e autorizar acessos ao recursos e dados contidos e expostos via API.
O OAuth 2.0 é um protocolo de autorização que habilita aplicações terceiras a obter acesso limitado a um serviço web / HTTP.
O OAuth, sendo uma especificação, descreve de forma detalhada uma maneira de tratar cenários simples e complexos de segurança de API. Ele estabelece definições como:
Resource Owner: a entidade que é capaz de controlar o acesso a um recurso protegido. É o "dono do recurso", mas nem sempre é uma pessoa. Quando ele é uma pessoa ele é o usuário final.
Resource Server: o servidor que possui os recursos protegidos e recebe as requisições para acessar esses recursos.
Authorization Server: é um servidor que gera tokens de acesso para permitir que o consumidor acesse os recursos que o resource owner permitiu com o nível de acesso que o resource owner especificou.
Client: é a aplicação que acessa os recursos no resource server em nome do usuário. O client pode ser qualquer tipo de aplicação que faça isso. É o consumidor da API.
Com essas definições, o OAuth estabelece que quando uma aplicação precisa acessar um recurso protegido ela deve obter primeiro um token de acesso (Access Token). Este é um token contendo as informações que caracterizam o acesso que o dono do recurso permitiu aos dados protegidos.
Todas as requisições realizadas junto à API da ELO deverão utilizar o protocolo HTTPS, e deverão ter em seus cabeçalhos os dados necessários para o acesso ao serviço. São eles:
client_id: Identificador gerado quando o desenvolvedor cria uma aplicação no portal e que pode ser encontrado nas configurações da dashboard da aplicação.
Authorization ou access_token: Aqui é um ponto importante que deve ter bastante atenção do desenvolvedor. Enquanto o usuário não realizou o login na API é obrigatório o envio do Authorization. Após o login o desenvolvedor deve enviar apenas o access_token obtido.
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:
Para que seja possível iniciar a jornada dentro da plataforma de APIs da Elo, é necessário que um usuário seja criado. Para esse processo o desenvolvedor deverá usar a função createUser disponibilizada pela API. Esta função pode ser utilizada de duas maneiras:
O usuário utilizará o nome de usuário e senha como meio de autenticação.
O usuário utilizará uma rede social suportada pela plataforma da ELO como meio de autenticação.
A seguir é demonstrado uma visão geral desse processo.
Fluxo de criação de um usuário
Um exemplo da utilização da função createUser usando o nome de usuário e senha como autenticação é demonstrado a seguir.
Exemplo do corpo da requisição:
createUser(input:{
clientMutationId: "123",
bcryptPassword: "$2a$12$oumE.pnRbsdi.c4KYsyNWOJoVyfi2jMKDe102Er5uGCdzd49SvE1Y",
context: "CASA"
value: "19 123456789"
cpf: "1234567890",
rg:{
number: "234567890",
issuerOrganization: "SSP",
issueDate: "2020-12-03"
Exemplo da resposta da API:
"id": "89bd51d6-8eaf-31a5-bd2c-1fve81d17db4",
No exemplo acima o campo id é o access_token que deve ser utilizado caso o usuário faça alguma requisição a algum recurso da API. Nesse cenário não é necessário que o usuário faça login após a criação pois o mesmo já foi feito implicitamente pela função createUser e o token de acesso pode ser utilizado até sua expiração.
Um exemplo da utilização da função createUser usando uma rede social é demonstrado a seguir.
socialNetwork:{
provider: "FACEBOOK",
username: "usernameFacebook@gmail.com"
oauth:{
accessToken: "EAACEdEose0cBAPZAVQLY5qPqEfqPPPviCy5NYbYBX7zLndQWDiUZBOBMC5Ry...",
refreshToken: "",
scopes: "email",
expiryTimestamp: "2018-03-01T00:00:00Z"
A resposta da criação do usuário usando uma rede social é a mesma do exemplo anterior.
Após a criação, um determinado usuário pode assumir 3 tipos distintos na plataforma da Elo, sendo eles:
Card Holder: Um usuário portador de um ou mais cartões Elo;
Card Issuer: Um usuário que emite cartões Elo;
Merchant: Um estabelecimento comercial que realiza transações com cartões Elo;
Cada tipo possui sua forma de ser associado, com informações pertinentes a cada um. Um usuário só pode ter um tipo associado ao mesmo tempo, logo, se um usuário está associado a um CardHolder e tenta se associar a um Merchant um erro será retornado. Neste caso, é necessário remover a associação do CardHolder do usuário e, somente depois, realizar a associação ao novo tipo.
Para associar um CardHolder ao usuário basta utilizar a função createCardHolderForUser, a mutation abaixo é um exemplo de sua utilização. Por questão de segurança o campo userId não se refere ao real id do usuário, e sim ao seu access_token.
createCardHolderForUser(input:{
userId: "33744898-9844-4864-a0ca-046d50fdaf15",
companyLegalName: "companyLegalName",
companylegalIds: {
cnpj: "1234567890"
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.
addCardIssuerToUser(input:{
userId: "97c7fb10-174c-4e23-8feb-926d1d23a035",
cardIssuerId: "1b253372-8215-4567-a54d-4fa78dadf0f6"
cardIssuer{
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.
addMerchantToUser(input:{
userId: "14991673-f5b9-43b8-8cb3-8da353b9b70c",
merchantId: "b86eb0ef-0c21-4ea5-b407-9f113a229190"
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 consultar um usuário basta utilizar uma query de usuário, como no exemplo abaixo.
user(id: "70fa9e70-1b41-3f68-8df9-b207d76929f6") {
cardHolders{
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.
updateUser(input:{
id: "0c9cd95a-365e-40d3-89c2-63c35340a0fa",
firstName: "firstName changed"
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.
deleteUser(input:{
userId: "e29e5d4b-c5f6-45c9-90e0-26b21fed43f9"
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:
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.
Para ter acesso às APIs da Elo o usuário deve possuir um access_token válido e para isso ele deve efetuar login na plataforma. O processo de login pode ser realizado de duas formas: utilizando um nome de usuário e senha via createLoginSalt ou utilizando uma rede social via socialNetworkOAuthLogin.
Veja na figura abaixo os dois exemplos:
Caso o usuário queira utilizar o nome de usuário e senha ele primeiro deve fazer uso da chamada createLoginSalt. Essa função retorna um salt que deve ser utilizado para gerar o challenge que será enviado no processo de login (Mais detalhes sobre como obter o challenge seram descritos posteriormente). Um exemplo dessa chamada pode ser vista abaixo.
createLoginSalt(input:{
username: "UserNameToLogin"
"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.
login(input:{
clientMutationId: "0123456789",
username: "UserNameToLogin",
challenge:"$2a$05$J/dgZmXIN23mEZtvkxDYeOtRsNEY4xMU9HHkcBVMpiUlFSFBuhtxy"
"clientMutationId": "0123456789",
"accessToken": "b64a0e34-24c5-39eb-b457-0c7331d176f0"
Caso o usuário queira utilizar uma rede social para se autenticar na API da Elo ele deverá fazer uso da chamada socialNetworkOAuthLogin. Assim como no fluxo descrito anteriormente, no retorno da função também é disponibilizado o access_token que identifica o usuário de forma única.
socialNetworkOAuthLogin(input:{
username: "user.name@gmail.com",
accessToken:"AAECEdEose0cBANynsVcZChZBxB3ysAuxDeZC3ZB4eIzkUKJnvoaTO1Vf4gyj8sl9bFFNPlnGU0Qsnh2fys7gcymWE7lKL64ygGLCJAtgyJtNq4YSGBkdDZBcgnAGZBKaGiI6emZCap8WJYO8ex06ZAZB75IdWnDtPoGCF8yPQnW4JZALHgeL1A1o6ZC5nz5uLD2lnVoUpkxAr1CNQABCD"
"accessToken": "120faef6-5f31-3e74-afb2-864151c52880"
O campo challenge presente no login de usuário refere-se ao resultado do desafio (challenge) de login. É um hash utilizando o algoritmo bcrypt com salt (fornecido por createLoginSalt) e o conteúdo sendo o bcryptPassword (especificado em User).
Os passos são os mesmos da geração do bcryptPassword (na criação de usuário), porém com dois passos a mais.
Após gerar o bcryptPassword:
Gerar um salt a partir da função createLoginSalt.
Aplicar o algoritmo bcrypt utilizando o bcryptPassword e o salt gerado no item anterior.
NOTA: O resultado final deve estar no formato padrão, com prefixo, custo, salt e por fim o valor computado em Base64, totalizando 60 caracteres.
Exemplo de challenge: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy.
Caso um usuário não lembre sua senha e precise fazer o reset, existe um fluxo de Reset de Senha que pode ser feito. O primeiro passo é solicitar o envio de um pedido de reset de senha. Isso é feito através da mutation requestPasswordReset:
requestPasswordReset(input: {
cpf: "12345678900"
email: "seu.email@provedor.com"
maskedEmail
Essa mutation pode ser realizada enviando o campo email ou o campo phone, mas nunca ambos. Eles também precisam ser os mesmos contatos enviados no momento do cadastro.
Após isso, será enviado um e-mail ou um SMS para o contato especificado, com um token que será usado para fazer o reset da senha, através da mutation passwordReset:
passwordReset(input: {
clientMutationId: "1234567",
email: "seu.email@provedor.com",
bcryptPassword: "$2a$12$yOCCL/0cbkvc5Lj/.EfnKeHm3oBPq28rGYbs8ayG8tbRYw4qtXflW",
token: "C68M59"
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.
createCard(input: {
holderId: "9e5d64e4-409f-4900-b3b6-28319950fe5b",
country: "BRA",
city: "Campinas",
state: "São Paulo",
zip: "1234",
place: "via"
last4,
billingAddress{
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.
cards(filter:{
expiry{
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.
node(id: "b63dcf70-08ae-423f-9459-db580b3d6e95") {
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.
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.
updateCard(input:{
holderId: "d6f9605c-8da9-484a-bdb4-3e483db232ee",
billingAddress:{
country: "coutnry changed",
city: "city changed",
state: "SP changed",
place: "place changed"
Neste exemplo estamos atualizando algumas informações do endereço de cobrança do cartão e o seu status. O cartão é identificado pelo campo holderId. Outras informações podem ser atualizadas além do endereço e status.
Para deletar um cartão é utilizado a função deleteCard. Abaixo segue um exemplo de utilização.
deleteCard(input:{
cardId: "c049ac20-084b-46f1-ac03-817e855b5811"
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}.
name: Nome do portador do cartão. Exemplo: "João da Silva".
cscEntryTime: Data e horário quando o CSC (Código de Segurança do Cartão) foi digitado. É necessário quando o CSC é gerado por um chaveiro/token baseado em tempo. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00".
authCode: Código de autorização. Este código não é o CSC (Código de Segurança do Cartão) pois não está impresso no cartão. Exemplo: "AB123Z1Y".
authCodeEntryTime: Data e horário quando o código de autorização (authCode) foi digitado. Deve estar no formato ISO 8601. Exemplo: "2017-06-01T12:00:00-03:00".
NOTA: a autorização é feita com os campos csc ou authCode e seus respectivos horários de entrada. Apenas um deles deve ser especificado.
O segundo passo é assinar os dados utilizando JSON Web Signature (JWS) em formato compacto, e utilizando Elliptic Curve (EC) como algoritmo de assinatura.
O terceiro passo é criptografar os dados do passo anterior utilizando a chave pública do servidor, que pode ser obtida a partir da query:
serverPublicKey {
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:
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.
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
publicKey{
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:
createWallet(
cardHolderId: "fdf9f98e-a6ac-4878-ad45-cc133e4ca168",
name: "Carteira"
wallet{
holder{
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:
addCardToWallet(
clientMutationId:"123",
walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51",
cardId: "2fde85bf-6935-4e9b-8262-94d82e08e4bd"
Remover cartão de uma carteira:
removeCardFromWallet(
clientMutationId: "012",
cardId: "2fde85bf-6935-4e9b-8262-94d82e08e4bd"}
Atualizar a carteira:
updateWallet(
name: "Carteira Principal"
NOTA: Só é possível atualizar o nome da carteira.
Remover a carteira:
deleteWallet(
walletId: "770d83de-f022-4c4e-b12d-e62f3d2d1d51"
walletId,
Consultar dados de portador utilizando a consulta de usuário:
NOTA: o parâmetro id se refere ao access_token do usuário.
Dados de um portador via ID
Consultar o nome, CPF, RG e data de nascimento de um portador dado o identificador global único:
node(id: "B8B1582B-1C2C-406B-9FC3-ACA842049207") {
... on CardHolder {
cpf {
rg {
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") {
Fragmentos reusáveis:
fragment CardLast4Fragment on Card {
...CardLast4Fragment
Especificação de identificador global de objetos (Relay Global Object Identification Specification).
ID não-nulo
Identificador global único do nó (objeto) a ser consultado.
Query (consulta) portadores de cartões CardHolder
Limita a lista às primeiras entradas, caso definido. Se for null, a listagem é ilimitada. Utilizado em navegação para frente.
Inicia após o cursor opaco, se definido. Utilizado em navegação para frente.
Limita a lista às últimas entradas, caso definido. Se for null, a listagem é ilimitada. Utilizado em navegação para trás.
Inicia antes do cursor opaco, se definido. Utilizado em navegação para trás.
SearchFilterInput
Aplica filtro, se definido.
Entrada para filtragens de busca com informações textuais.
TODO: document filter language, something like Google or GMail
PageInfo compatível com Relay.
Boolean não-nulo
CNPJ: Cadastro Nacional Pessoas Jurídicas
String não-nulo
número do CNPJ (dígitos) sem hífen ou pontos.
CPF: Cadastro Pessoa Física
RG: documento de Registro Geral
número do RG (dígitos) sem hífen ou pontos.
organização emissora do documento (exemplo: SSP)
estado de emissão do documento (exemplo: SP)
Toda a possível identificação legal de uma pessoa ou empresa
Renda anual de uma pessoa física (individual e familiar).
Renda anual pessoal (individual) da pessoa física.
Renda anual total da família da pessoa física.
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.
Identificador opaco da Profissão
Deve ser informado como entrada em mutações que precisam de profissão.
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.
URL para acessar a imagem
Int não-nulo
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.
PersonContactType não-nulo
Tipo designa como interpretar o valor, podendo ser telefone, email, ou aplicativo de mensagens instantâneas.
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
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.
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
Contexto do endereço, por exemplo: Casa, Trabalho, Matriz, Filial
Análogo a campo de mesmo nome em PersonContact e CompanyContact.
Código do país com 3 letras (ISO3166-alpha3). Exemplos: USA, BRA...
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.
Distrito opcional
O tipo deve ser Av. (Avenida), R. (Rua), Rd. (Rodovia)...
Nome da via, para ser usado em conjunto com kind e number, compondo a primeira linha de endereço.
Complemento opcional, como número de apartamento.
Ponto de referência (exemplo: próximo ao posto)
Instruções (exemplo: autorização do receptor)
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.
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.
lista de PersonContact não-nulo
lista de Address não-nulo
lista de Wallet não-nulo
Conexão de Card em conformidade com o Relay.
PageInfo não-nulo
lista de CardsEdge
Carteira digital (Digital Wallet)
CardHolder não-nulo
Nome e contato do portador
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.
CardsEdge
Aresta de conexão contendo um Card em conformidade com o Relay.
O objeto Card que compõe essa aresta conexão.
TravelInsurancesEdge
Aresta de conexão contendo um TravelInsurance em conformidade com o Relay.
O objeto TravelInsurance que compõe esta aresta de conexão.
Conexão de TravelInsurance em conformidade com o Relay.
lista de TravelInsurancesEdge
ExtendedWarrantyInsurancesEdge
_("ExtendedWarrantyInsurancesEdge")
_("ExtendedWarrantyInsurancesEdge.cursor")
ExtendedWarrantyInsurance
_("ExtendedWarrantyInsurancesEdge.node")
_("ExtendedWarrantyInsurancesConnection")
_("ExtendedWarrantyInsurancesConnection.pageInfo")
lista de ExtendedWarrantyInsurancesEdge
_("ExtendedWarrantyInsurancesConnection.edges")
_("ExtendedWarrantyInsurancesConnection.totalCount")
PurchaseProtectionInsurancesEdge
Aresta de conexão contendo um PurchaseSecurityInsurance em conformidade com o
PurchaseProtectionInsurance
O objeto PurchaseSecurityInsurance que compõe esta aresta de conexão.
Conexão de PurchaseSecurityInsurance em conformidade com o Relay.
lista de PurchaseProtectionInsurancesEdge
HomeAssistencesEdge
_t("HomeAssistencesEdge")
HomeAssistence
O objeto HomeAssistence que compõe essa aresta conexão.
Conexão de HomeAssistence em conformidade com o Relay.
lista de HomeAssistencesEdge
Um cartão de crédito ou débito.
CardExpiry
CardStatusInterface não-nulo
usageConstraints
CardUsageConstraints
lista de CardHolderService não-nulo
usedServices
allowedCaptures
lista de CardCapture não-nulo
lista de CardUsage não-nulo
CardMetadata
lista de Track
Só será retornado os dados caso seja um CardIssuer realizando a consulta, caso outro tipo de usuário faça essa consulta o campo deve retornar vazio.
CardTransactionFilterInput
CardTransactionsConnection
transactionsSummary
CardTransactionSummaryFilterInput
lista de CardTransactionCategorySummary não-nulo
fraudTransactions
CardFraudTransactionFilterInput
Aplica filtro, se provido. Consulta as transações fraudulentas que já foram processadas. Apenas Card Issuer pode realizar essas consulta.
CardFraudTransactionsConnection
queueFraudTransactions
Aplica filtro, se provido. Consulta as transações fraudulentas que estão na fila de processamento. Apenas Card Issuer pode realizar essas consulta.
Validade do cartão: Mês e Ano
Mês - Janeiro é 1, Dezembro é 12
Ano - 4 dígitos, exemplo: 2017, não 17.
Informações sobre como o cartão ou token podem ser usados.
Observe que as restrições do cartão ou token podem ser especificadas no momento de criação usando CardUsageConstraintsInput. Emissores, cartões e produtos podem impor restrições extras.
Número de vezes que o cartão pode ser usado.
-1 significa ilimitado null significa uso não definido.
Uso é permitido até a data e horário de validade
allowedTxAmounts
lista de CardCurrencyRange não-nulo
Quantias permitidas por transações permitidas (TX) como limites por moedas.
Cada moeda será listada no máximo uma vez.
Nenhuma conversão de moedas é executada. Se uma moeda não é listada, é porque não é autorizada.
Se null, é ilimitada.
allowedMerchants
lista de Merchant não-nulo
Lista de comerciantes autorizados.
allowedMerchantCategories
lista de MerchantCategory não-nulo
Categorias de comerciantes autorizadas.
Se não-nula, então é a lista completa de categorias permitidas após aplicar filtros definidos por solicitantes, emissor e restrições de produto.
deniedMerchantCategories
Categorias de comerciantes proibidas.
Se não-nula, então é a lista completa de categorias proibidas após aplicar filtros definidos por solicitantes, emissor e restrições de produto.
CardHolderService
Serviço disponível ao portador do cartão.
A Elo oferece aos portadores serviços como acesso à internet, estes são representados por este tipo.
URL da imagem. Caso sejam providos sugestões de altura e largura (opcionais) para o tamanho a ser mostrado, o servidor irá retornar a URL para a imagem com o tamanho mais próximo ao requisitado. Caso seja provido o mimeType, a este será dada preferência, o que é muito útil em dispositivos que lidam com um único formato de imagens. Tanto o tamanho quanto o mimeType da imagem apontada pela URL são retornados.
Percentual de descontos
Representa um BIN (Bank Identification Number ou Número de Identificação do Banco) no sistema.
O BIN é relativo aos números iniciais de um cartão e identifica o emissor e produtos associados ao mesmo.
Cada bandeira tem faixas de BIN reservadas a seu uso, estas estão disponíveis como reserved na consulta binTable.
Porém o maior interesse é por BIN em uso (alocados), o qual carregará informações sobre o emissor (banco), financiamento (funding, se crédito, débito ou ambos), produtos (pagamentos à prazo, pré-pago, Cartão para construção civil - Construcard...) e mesmo serviços como emissão de seguros ou acesso à WiFi.
A tabela de BIN é dinâmica:
Conforme os cartões de um mesmo prefixo (BIN) vão sendo inutilizados e ficam sem usuários, o BIN pode ser então reciclado para um novo uso.
Conforme novos produtos são inseridos, um BIN previamente reservado e sem usuários será então alocado, entrando em uso.
Por isso é importante manter a tabela de BIN atualizada, vide consulta binTable. Para saber se a tabela foi atualizada utilize os campos de nome similares ao HTTP lastModified (data e horário da última modificação) e etag (entity tag ou etiqueta da entidade), que oferece um identificador único sobre a tabela, se ele mudou então a tabela mudou.
panSizeRange
IntRange não-nulo
CardFunding não-nulo
CardProduct não-nulo
Diz se o cartão é corporativo (pessoa jurídica) ou pessoa física.
Se true, então o cartão é corporativo, ou seja, pessoa jurídica. Se false, então o cartão é para pessoas físicas.
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).
CardBrand não-nulo
A bandeira responsável pelo Cartão. Para cartões da Elo, sempre será Elo.
lista não nula de CardCapture não-nulo
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.
lista não nula de CardUsage não-nulo
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.
CardNetwork não-nulo
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.
CardIssuer não-nulo
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.
CardMetadata não-nulo
Metadados para apresentação do cartão ao usuário.
Metadados tais como:
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.
lista não nula de CardHolderService não-nulo
Serviços (benefícios) disponíveis ao portador do cartão.
Os serviços, também conhecidos como benefícios, ao portador. Por exemplo:
Seguro Viagem, para compra de passagens aéreas;
Proteção de Compra, para compra de bens;
Garantia Estendida, para compra de bens;
Acesso ao WiFi.
creditSettlementBankNumber
Número do Banco liquidante da operação de Crédito
Indica qual o código do banco deverá ser utilizado para liquidar operações de crédito.
debitSettlementBankNumber
Informação de produto associado ao cartão
Cada cartão é relacionado a um produto. No caso da Elo, exemplos de produto são:
CodeProduct não-nulo
Código que identifica produto.
Exemplos de Produtos Elo:
Bandeira (marca) do cartão
A bandeira do cartão atualmente retorna Elo.
Nome da bandeira
URL da bandeira
CardCapture
Modo de captura (entrada) do cartão.
O modo de captura define como o cartão pode ser utilizado, exemplos tradicionais:
POS (Point of Sale, ou Ponto de Venda)
Internet (lojas virtuais, e-commerce)
Telemarketing (centrais de venda por telefone)
ATM (Automated Teller Machine, ou Caixa Eletrônico)
Nome da Captura
Código Bancário da Captura
Nos sistemas tradicionais pode ser necessário transitar o código da captura, que é fornecido por este número.
TEF = 2
Telemarketing = 4
ATM = 5
CardUsage
Uso de um Cartão.
Define como as compras poderão ser realizadas, por exemplo:
Parcelado pela loja
Nome do Uso
Código Bancário do Uso
Nos sistemas tradicionais pode ser necessário transitar o código do uso, que é fornecido por este número.
Parcelado Loja = 72
Rede para utilização do Cartão
Cada cartão deve ser utilizado em uma rede, por exemplo para cartões Elo:
Elo para cartões domésticos;
Elo-Discovery para cartões internacionais.
Exemplos para Elo:
URL da rede
Entidade do Emissor de Cartão
CompanyLegalIds não-nulo
lista não nula de CompanyContact não-nulo
lista não nula de Address não-nulo
Consulta todos os objetos de cartão (Card) disponíveis no contexto.
Se executado por um portador de cartão, serão retornados todos os cartões que este possui e foram emitidos por este emissor.
Se executado por um emissor de cartão, serão retornados todos os cartões emitidos por este.
Em outros casos, como ao ser executado por um comerciante, um erro será produzido.
Metadados de cartão: como representar o cartão visualmente
Cor de fundo (background) em notação web padrão: ffffff (branco), ff0000 (vermelho), 00ff00 (verde), 0000ff (azul). Deve ser usado em conjunto com foregroundColor quando não é possível usar imagem.
Cor de primeiro plano (foreground) em notação web padrão: ffffff (branco), ff0000 (vermelho), 00ff00 (verde), 0000ff (azul). Deve ser usado em conjunto com backgroundColor quando não é possível usar imagem.
Emissor de cartão, i.e.: "Um Banco" Deve ser usado quando não é possível utilizar imagem.
É o mesmo que consultar o BIN { issuer { name } }
Bandeira do cartão, i.e: Elo Deve ser usado quando não é possível utilizar imagem.
É o mesmo que consultar o BIN { brand { name } }
Nome do produto associado ao cartão, i.e.: Nanquim, Grafite.
É o mesmo que consultar o BIN { product { name } }
Dados utilizado no embolssing.
TrackType não-nulo
Conexão de CardTransaction em conformidade com o Relay.
lista de CardTransactionsEdge
CardTransactionCategorySummary
Sumário de Transações de Cartão para uma Categoria de Comerciante
MerchantCategory não-nulo
Categoria deste sumário
Número de transações nesta categoria
Valor total das transações em BRL (R$) nesta categoria
Conexão de CardFraudTransaction em conformidade com o Relay.
lista de CardFraudTransactionsEdge
MerchantInsurance
Dados da viagem.
Companhia responsável pela viagem.
journeyLocator
Número de Confirmação.
lista não nula de Trip não-nulo
Trechos da vigem (Possíveis escalas).
Propósito da viagem (lazer, negócios...)
Seguro de Viagem para portadores de cartão ou dependentes.
Cada instância de seguro viagem é correspondente a uma chamada de createTravelInsurance(), atrelada a um portador de cartões e o BIN que oferece tal serviço (benefício), além de ter um viajante associado (o segurado) e uma lista de beneficiários.
Para viagens com múltiplos viajantes, um seguro de viagem deve ser emitido para cada viajante, ou seja, uma chama de createTravelInsurance() para cada viajante, resultando em um TravelInsurance para cada um.
O Portador, segurado primário da viagem.
O serviço (benefício) de seguro de viagem é oferecido para determinados produtos (i.e: Cartões Elo Nanquim) ao portador do cartão e extensível a demais segurados que viajarão em conjunto.
Em caso de viagem com múltiplos viajantes, o cardHolder será o mesmo, porém os dados do viajante (traveler) listados neste seguro serão referentes ao viajante segurado.
BIN não-nulo
Informações do comerciante.
Journey não-nulo
Date não-nulo
A data inicial da cobertura.
A data inicial é computada automaticamente como a data de emissão do seguro.
A data final da cobertura.
A data final é computada automaticamente à partir da data da nota fiscal (invoiceDate) acrescida dos dias da proteção escolhidos (securityDays).
Seguradora responsável pelo seguro.
ExtendedWarrantyProductCategory
Categoria de Produtos para Seguros de Garantia Estendida
Identificador opaco da categoria de produto.
Deve ser informado como entrada quando a categoria for requisitada.
Este texto é localizado (traduzido) para a linguagem informada na consulta ou mutação
lista não nula de ProductCategory não-nulo
Produto segurado.
Seguro de Garantia Estendida para portadores de cartão.
Identificador Global Único de Seguro contratado, retornado pela seguradora.
CardHolderInsuranceStatus não-nulo
A data final é computada automaticamente à partir da data da nota fiscal (invoiceDate) acrescida dos meses de garantia do fabricante (manufacturerWarrantyMonths) e então dos meses estendidos com este seguro (extendedWarrantyMonths).
extendedWarrantyMonths
Número de meses estendidos por este seguro.
manufacturerWarrantyMonths
Número de meses cobertos pela garantia do fabricante.
PurchaseProtectionProductCategory
_t("PurchaseProtectionProductCategory")
_t("PurchaseProtectionProductCategory.id")
_t("PurchaseProtectionProductCategory.display")
Seguro de Proteção de Compra de Produtos para portadores de cartão.
Float não-nulo
coverageDays
Número de dias o qual o produto será protegido (segurado).
Dados para contato da pessoa responsável em receber o prestador.
Nome de contato no momento do atendimento
lista não nula de PersonContact não-nulo
ProviderAssistence
Dados do Prestador.
Nome do prestador.
Codigo de identificação do prestador.
Contatos do prestador
Dados de geolocalização do prestador.
MerchantAssistence
Dados da assistência residencial solicitada.
Identificador global uníco da assistência.
openedAt
DateTime não-nulo
Data de quando foi realizado a solicitação do atendimento.
Data da ultima atualização na solicitação.
HomeAssistenceStatus não-nulo
HomeAssistenceType não-nulo
Address não-nulo
Endereço para prestar a assistência.
PersonType não-nulo
Dados do contato responsável por atender o prestador.
Dados do prestador de serviço responsável pelo atendimento.
Descrição do atendimento.
CardCurrencyRange
Declara limites operacionais para uma moeda.
Valor mínimo ou null para ilimitado.
Valor máximo ou null para ilimitado.
Um estabelecimento comercial que realiza transações com cartões Elo.
lista não nula de MerchantCategory não-nulo
Categorias de comerciantes (Código ISO, nome)
lista de MerchantTransactionFees não-nulo
Preços de Transações efetivos para o Comerciante
As taxas e custos são associados a um uso (i.e: Crédito à vista, Crédito parcelado pela loja...), quantidade de parcelas e tem uma validade, ou seja, são dinâmicos. Devem ser consultados e posteriormente refrescados para este comerciante.
Alguns comerciantes têm valores negociados individualmente para seu CNPJ, estes são retornados preferencialmente. No entanto a maioria dos comerciantes não tem negociação individual, para estes vale os valores da categoria (MerchantCategory), o qual é retornado na ausência dos valores negociados individualmente.
Note que se o comerciante não estiver na base de dados ou não for possível determinar sua categoria será retornado null. Para estes casos deve-se, então, utilizar os preços estabelecidos para a sua categoria procurando diretamente por merchantCategory(iso: X) { transactionFees }.
Os custos são dinâmicos: foram alterados em MerchantTransactionFees { lastModified } e são vigentes até MerchantTransactionFees { expiry }. O usuário deve usar expiry para invalidar o cache local, refrescando as informações após tal data e horário.
cardTransactions
Consulta transações deste comerciante.
A consulta paginada permite obter transações feitas por este comerciante com um filtro opcional.
Ao ser chamado por um CardHolder (portador), apenas suas transações com este comerciante serão exibidas (filtro implícito).
Para transações de um cartão específico, utilize CardInterface { transactions }, primeiramente obtendo o Card ou CardToken por outras consultas, por exemplo cardInterfaceByHash(hash)
Pode ser null em caso de falta de permissão, por exemplo outro comerciante.
Categoria de comerciantes
A Categoria de Comerciante é associada a um código ISO18245 de 4 dígitos disponível no membro iso.
Nome da categoria de comerciante.
Preços de Transações para a Categoria de Comerciante.
As taxas e custos são associados a um uso (i.e: Crédito à vista, Crédito parcelado pela loja...) e tem uma validade, ou seja, são dinâmicos e podem ser consultados para esta categoria.
Note que alguns comerciantes possuem custos de transação específicos, negociados individualmente. Para estes deve-se consultar o comerciante e então seus preços diretamente via API com merchant(legalIds: {cnpj: X}) { transactionFees }, utilizando os valores da categoria aqui retornados apenas para comerciantes sem preços específicos.
MerchantsConnection
Consulta comerciantes (Merchant) nesta categoria.
Informa o percentual de descontos (ex: 100% de desconto, 50% de desconto, ou se não tem desconto)
holderOrAdditional
Percentual de desconto aplicado para o portador ou adicional.
Percentual de desconto aplicado ao acompanhante.
Define uma faixa de números inteiros.
Tanto min quanto max são inclusos na faixa. Ou seja:
min: 10, max: 12 define os números: 10, 11 e 12;
min: 100, max: 100 define apenas o número 100.
Número mínimo (inicial), incluso na faixa.
Número máximo (final), incluso na faixa.
CompanyLegalIds
Ítem de contato com a empresa, como email ou telefone...
CompanyContactType não-nulo
CardTransactionsEdge
Aresta de conexão contendo um CardTransaction em conformidade com o Relay.
O objeto CardTransaction que compõe essa aresta conexão.
CardFraudTransactionsEdge
Aresta de conexão contendo um CardFraudTransaction em conformidade com o Relay.
CardFraudTransaction
O objeto CardFraudTransaction que compõe essa aresta conexão.
MerchantTransactionFees
Custos de Transação ao Comerciante.
Baseado no tipo de uso (i.e: Crédito à vista, Crédito parcelado pela loja...) e número de parcelas o comerciante terá que pagar uma taxa à bandeira e ao credenciador. Recomenda-se que o usuário sempre considere cardUsage, installmentsRange e expiry em todas as consultas.
Exemplo de listagem:
cardUsage: 70, installmentsRange: null.
cardUsage: 71, installmentsRange: null.
cardUsage: 72, installmentsRange { min: 1, max: 6 }.
cardUsage: 72, installmentsRange { min: 7, max: 12 }.
Os custos são dinâmicos: foram alterados em lastModified e são vigentes até expiry. O usuário deve usar expiry para invalidar o cache local, refrescando as informações após tal data e horário.
O cálculo do valor final a ser pago é feito e esclarecido na consulta calc.
CardUsage não-nulo
Os custos de transação se referem a este uso.
Crédito parcelado pela loja = 72
Note que para produtos parcelados, como 72, serão retornadas diversas entradas com o mesmo cardUsage, porém com faixas de parcelamento diferentes em installmentsRange. Por exemplo se as tarifas para parcelamento de 1 à 6 são diferentes que parcelamentos de 7 à 12, então teríamos duas entradas com o mesmo cardUsage, sendo que cada uma terá installmentsRange diferente:
installmentsRange
A faixa de parcelas a qual estes custos de transação se referem.
Para cardUsage que permite parcelamento, será retornado a faixa de parcelas a qual estes custos se aplicam. Por exemplo se as tarifas para parcelamento de 1 à 6 são diferentes que parcelamentos de 7 à 12, então teríamos duas entradas com o mesmo cardUsage, sendo que cada uma terá installmentsRange diferente:
Para cardUsage que não permite parcelamento, será retornado null.
Data e horário da última modificação.
Data e horário que limitam a vigência do valor, ou seja.
Percentual a ser pago para a tarifa de desenvolvimento da bandeira e marketing.
Caso marketingFeeCeilValue seja não-nulo, então especifica um teto em BRL (R$) pra limitar o valor final a ser pago.
marketingFeeCeilValue
Teto do custo da tarifa de desenvolvimento da bandeira e marketing, em BRL (R$).
Caso seja não-nulo, após aplicar marketingFee ao valor da compra deve-se limitar o valor final em BRL (R$) ao montante especificado.
acquiringServiceFee
Percentual a ser pago para desenvolvimento e suporte de produtos ao credenciador.
Caso acquiringServiceFeeCeilValue seja não-nulo, então especifica um teto em BRL (R$) pra limitar o valor final a ser pago.
acquiringServiceFeeCeilValue
Teto do custo da tarifa de desenvolvimento e suporte de produtos ao credenciador da transação, em BRL (R$).
Caso seja não-nulo, após aplicar acquiringServiceFee ao valor da compra deve-se limitar o valor final em BRL (R$) ao montante especificado.
processingCost
Tarifa de processamento na mensageria de autorizações, em BRL (R$).
Este valor é fixo para este uso (cardUsage), independente do valor ou número de parcelas.
additionalInstallmentCost
Tarifa adicional para cada parcela, em BRL (R$).
Para uso parcelado, por exemplo cardUsage 72 (crédito parcelado pela loja), cada parcela deve pagar este custo adicional.
Ou seja, para uma compra em 3 parcelas, paga-se 2 * additionalInstallmentCost.
transactionValue:
Valor da transação a calcular o custo final, em BRL (R$).
Número de parcelas da transação.
Para pagamentos à vista (cardUsage 70 ou 71), será desconsiderado.
Se omitido, será considerado 1 (pagamento à vista).
MerchantTransactionFeesCalc não-nulo
Calcula o custo final em BRL (R$) a ser pago para uma transação de transactionValue realizada em installments parcelas com o uso retornado no campo cardUsage.
Esta consulta é um utilitário que calcula:
let marketingCost = transactionValue * marketingFee;
if (marketingFeeCeilValue && marketingCost > marketingFeeCeilValue) {
marketingCost = marketingFeeCeilValue;
let acquiringServiceCost = transactionValue * acquiringServiceFee;
if (acquiringServiceFeeCeilValue && acquiringServiceCost > acquiringServiceFeeCeilValue) {
acquiringServiceCost = acquiringServiceFeeCeilValue;
let installmentsCost = 0.0;
if (installments && installments > 1) {
installmentsCost = (installments - 1) * additionalInstallmentCost;
let totalCost = processingCost + installmentsCost + marketingCost + acquiringServiceCost;
Conexão de comerciante (Merchant) em conformidade com o Relay.
lista de MerchantsEdge
Representa uma transação de cartão.
As transações são retornadas em consultas derivadas (enraizadas) em outros tipos mais específicos, tais como:
CardInterface { transactions }: transações de um cartão específico.
Merchant { cardTransactions }: transações de um dado comerciante.
Todas as consultas são sujeitas às permissões de acesso:
Um comerciante (Merchant) não tem permissão para transações de outros comerciantes.
Um portador (CardHolder) não tem permissão para transações de outros portadores.
As consultas também são filtradas implicitamente pelas permissões de acesso, ou seja:
Um comerciante ao consultar as transações de um dado cartão, só receberá em retorno suas próprias transações e não de outros comerciantes.
Um portador ao consultar as transações de um dado comerciante, só receberá em retorno suas próprias transações e não de outros portadores.
O acesso direto via node(id) também é sujeito às mesmas permissões, só entidades relacionadas (comerciante ou portador) podem ter acesso à transação.
Ao Implementador: internamente guarde o hash do cartão (Card) ou token (CardToken) (não os retorne em consulta direta). Ao fazer a busca por CardInterface { transactions }, caia sempre para o mesmo código, à partir do hash (utilizando o valor armazenado internamente).
Para Merchant, sempre faça a o filtro conter a lista merchants com apenas o seu próprio id.
Se utilizar Cassandra ou NoSQL, precisa desnormalizar a tabela em:
Por hash;
Por MerchantId (comerciante);
Por MCC (código da categoria). Como comerciantes têm no mínimo 1 MCC, pode-se fazer como compound key de MCC, MerchantId. Ao listar o comerciante liste todos os seus MCC... em geral vai ser apenas 1. Neste caso não precisa desnormalizar por Merchant, apenas MCC, MerchantId
Para encadear consultas, como no caso de CardHolder descrito acima, cuidado com paginação. Se fizer numa consulta só, a paginação deve vir de "graça".
Campos informativos são altamente repetidos e não precisam estar nas tabelas desnormalizadas. Apenas referencie o id e então mantenha um cache local. Por exemplo CardCapture, CardUsage e BIN.
Caso replique os campos informativos, não os atualize com atualizações no campo original, seria até mais correto manter o snapshot do momento em que a transação foi registrada. Por exemplo o BIN poderia ser associado a um produto naquele momento e o BIN foi reciclado, utilizando outro produto.
CardCapture não-nulo
Merchant não-nulo
Representa uma transação fraudulenta de cartão.
CardTransaction não-nulo
Dados da Transação fraudulenta.
Authorization não-nulo
CardFraudTransactionStatus não-nulo
Estado da transação fraudulenta
Número de referência do Banknet.
Código que identifica o PDV.
LiabilityType
Identifica o responsável pela transação fraudulenta.
codeEic
Identificar o código 3D Secure específico aplicável.
flaggedAt
Data que o cartão foi cancelado após ser confirmado como fraude pelo titular do cartão.
Número de referença do adquirente, são 23 números unicos que marcam a transação do cartão quando ela vai da processadora para o emissor. Somente esta disponivel para transações finalizadas. Esta campo é util para estabelecimentos comerciais para fazer o de-para do alerta como a transação original, especialmente quando existem multiplas transações no mesmo cartão e no mesmo estabelecimento comercial com o mesmo valor e na mesma hora.
InitiatedType não-nulo
Identificar quem detectou a fraude.
Data que a transação foi liquidada (se já liquidada).
Informações da escala.
IATA - Associação Internacional de Transportes Aéreos
Caso o tipo da viagem seja aérea, esse campo deve ser informado.
Exemplo: GRU - Guarulhos/SP
ICAO ou OACI - Organização da Aviação Civil Internacional
Exemplo: SBGR - Guarulhos/SP
País da viagem. Código do país com 3 letras (ISO3166-alpha3). Exemplos: USA, BRA...
Data e hora da escala. Seguindo o formato estendido ISO 8601: Exemplo: "2017-06-01T12:00:00-03:00"
TravelInsuranceTraveler
Viajante do Seguro Viagem
lista de InsuranceTraveler não-nulo
Lista de Seguro viagem contratados.
InsuranceLegalIds não-nulo
Todos os documentos legais de identificação do viajante.
Nome completo do viajante como no documento oficial (CPF).
Gender não-nulo
Masculino ou Feminino, conforme documentos oficiais.
Se feminino e estiver grávida, de quantas semanas.
Se masculino ou não estiver grávida, será null.
MaritalStatus não-nulo
Profissão do viajante.
Renda anual do viajante (individual e familiar).
Endereço do viajante.
Contatos do viajante.
politicalExposure
Pessoa Exposta Politicamente.
Identificador Global Único do trecho da viagem.
Identifica o tipo de viagem.
Informações da saída da escala.
Informações da chegada da escala.
lista não nula de TravelInsuranceTraveler não-nulo
Dados do(s) Viajante(s) a qual este seguro se refere.
Para emissão de seguro informar os dados de todos os viajantes, informe todos os campos obrigatórios.
Propósito (Motivo) da Viagem
Se true, um dos propósitos da viagem é lazer.
Se true, um dos propósitos da viagem é negócios.
Se true, um dos propósitos da viagem é realizar atividades de aventura.
Atividades de aventura ou perigosas, tais como andar a cavalo, jet ski, bungee jump, rafting, canoagem ou ciclismo.