01
Primeiros passos
02
Introdução
03
Verificação
04
Consultas
05
Referências
Queries
Mutations
Tipos de Entrada
Tipos
Enumerações
Leia Introdução ao GraphQL, com exemplos reais da nossa API.
Crie uma conta no portal do desenvolvedor.
Cadastre sua primeira aplicação.
Utilize o dashboard para acessar suas configurações de acesso.
Para explorar rapidamente as APIs aqui na página de documentação, use o console de GraphQL, na seção de referências. Nele, você pode ver as consultas de exemplo, executá-las e alterá-las.
Jaydson GomesDesenvolvedor Evangelista
A API de Verificação de Conta Credenciador tem como principal objetivo oferecer serviços de verificação do status da conta cartão de um portador em compras de cartão não presente (Online).
O mecanismo mais comum para essa verificação é realizar uma transação conhecida como transação Zero Dólar. Onde consiste na verificação da existÊncia e condições de uso do cartão através de uma transação de baixo valor, que posteriormente será estornada pelo solicitante. Com o uso da API, é possível realizar essa verificação com uma única transação e sem sensibilizar o limite desta conta.
Existem muitas outras utilidades para o uso da API, como a validação do portador antes de realizar uma transação de transferência de fundo, ou até mesmo validar a conta cartão antes de armazená-la em uma carteira digital ou em um repositório seguro.
Para fazer uso da API, é necessário ter no cabeçalho das requisições o client_id fornecido ao criar uma aplicação no Portal e um access_token fornecido ao realizar login na plataforma de APIs, como descrito em cadastro do portador.
Para realizar a verificação de conta do cartão, é preciso utilizar a mutation verifyPaymentAccount
(demonstrada abaixo), informando um sensitive
- campo que referencia todos os dados sensíveis de um cartão, como descrito na documentação de cartão.
mutation{
verifyPaymentAccount(
input:{
clientMutationId: "1234"
legalIds: { #Campo opcional
cpf: "11684158613"
}
sensitive: "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway..."
type: CREDIT #CREDIT ou DEBIT
acquirer: {
id: 123
code: "123"
countryCode: "076"
}
merchant: {
idCode: "123"
name: "Teste"
legalName: "Teste LTDA"
legalIds:{
cnpj: "121212121212121"
}
contact:{
type: PHONE
context: "Trabalho"
value: "+5511999991111"
}
address:{
country: "Brasil"
city: "São Paulo"
state: "São Paulo"
zip: "123456788"
number: 1234
place: "Paulista"
}
iso: 1111
countryCode: "076"
}
}
)
{
verifyPaymentAccount{
status
verifiedAt
}
}
}
clientMutationId
: Identificador de cliente opaco usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões;
verifyPaymentAccount
: Objeto que devolve o status da conta, sendo esse valor VALID, INVALID, NOT_SUPPORTED e ERROR e o valor verifiedAt, contendo a data que a validação de conta foi realizada.
Você também pode executar consultas para verificações já efetuadas anteriormente utilizando a query verifyPaymentsAccounts:
query {
verifyPaymentAccounts
{
pageInfo {
hasPreviousPage
hasNextPage
startCursor
endCursor
}
totalCount
edges {
cursor
node {
status,
verifiedAt
}
}
}
}
verifyPaymentAccountId
: Identificador Global Único;
legalIds
: Objeto contendo o documento legal de identificação CPF ou CNPJ, sendo cpf ou cnpj;
status
: Estado da validação de conta, sendo esse valor VALID, INVALID, NOT_SUPPORTED e ERROR;
bin
: BIN do cartão, contendo entre 6 e 9 dígitos;
type
: Objeto contendo o tipo de transação socilitada, sendo esse valor CREDIT e DEBIT;
idCode
: Identificador do Estabelecimento Comercial;
startTimestamp
: validações realizadas a partir de certa data e horário;
endTimestamp
: validações realizadas até certa data e horário;
Query (consulta) de verificação de conta de um cartão junto ao Emissor CardIssuer
Argumentos:
first: Int
Limita a lista às primeiras entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para frente.
after: String
Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.
last: Int
Limita a lista às últimas entradas, caso provido.
Se for null
, a listagem é ilimitada.
Utilizado em navegação para trás.
before: String
Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.
filter: VerifyPaymentAccountFilterInput
Aplica filtro, se provido.
Mutation responsável por realizar a verificação de conta de um cartão junto ao Emissor(CardIssuer).
Argumentos:
input: VerifyPaymentAccountInput
obrigatório
Entrada para LegalIds
, somente CPF ou CNPJ
Campos:
cpf
:
String
Número CPF sem hífen ou pontos
cnpj
:
String
Número CNPJ sem hífen ou pontos
Critério de filtro para keyLabel
Campos:
verifyPaymentAccountId
:
ID
Identificador Global Único para objeto VerifyPaymentAccount
bin
:
String
BIN (Bank Identification Number) do cartão.
O BIN é um prefixo de tamanho variável (em geral entre 6 e 9 dígitos)
idCode
:
String
Identificação do Estabelecimento Comercial cadastrado junto à Elo pelo Credenciador ou pelo Facilitador no momento do ajuste cadastral do Estabelecimento Comercial.
startTimestamp
:
DateTime
Se não-nula, retorna apenas informações à partir (inclusive) da
data e horário dados.
Se null
, retorna todos os Registros.
endTimestamp
:
DateTime
Se não-nula, retorna apenas informações até (inclusive) a data e
horário dados.
Se null
, retorna todos os registros até o momento atual.
Entrada para as informações do Credenciador
Campos:
id
:
ID
obrigatórioIdentificador Global Único do adquirente que submeteu a transação do estabelecimento comercial. Este campo ajuda no tratamento de problemas fazendo um de/para para o estabelecimento comercial, especialmente no caso aonde a descrição do estabelecimento comercial não esta clara. No futuro pode ser utilizado como uma alternativa para descrição do estabelecimento comercial.
code
:
String
obrigatórioIdentificador Global Único do Credenciador junto a Elo.
Este campo identifica unicamente os números designados pela Elo para Estabelecimentos/Credenciador.
countryCode
:
String
obrigatórioIdentificador Global Único do país onde está localizado o Credenciador. Transações nacionais utiliza-se o código 076 (Brasil). ISO 3166-1 numeric
Entrada para os dados do comerciante.
Campos:
name
:
String
obrigatórioNome visível publicamente. Normalmente nome bem conhecido, marca, etc.
legalName
:
String
obrigatórioNome legal, como escrito em documentos.
description
:
String
Descrição da empresa para ser apresentado a usuários.
legalIds
:
LegalIdsInput
obrigatórioTodos os documentos legais de identificação da empresa.
contact
:
PersonContactInput
obrigatórioContato do comerciante
address
:
AddressInput
obrigatórioEndereço postal
O campo zip deve ser sempre preenchido.
url
:
String
Endereço Virtual (Uniform Resource Locator).
iso
:
Int
obrigatórioCódigo ISO18245.
Também conhecido como MCC (Merchant Category Code), tem 4 dígitos.
countryCode
:
String
obrigatórioIdentificador Global Único do país onde está localizado o Merchant, código 076 (Brasil). ISO 3166-1 numeric
idCode
:
String
obrigatórioIdentificação do Estabelecimento Comercial cadastrado junto à Elo pelo Credenciador ou pelo Facilitador no momento do ajuste cadastral do Estabelecimento Comercial.
Campos:
clientMutationId
:
String
Identificador de cliente opaco, normalmente em formato UUIDv4.
Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.
Compatível com Relay.
sensitive
:
String
obrigatórioConteúdo sensível (número do cartão, código de verificação e validade) o qual foi assinado e então cifrado conforme a estrutura a seguir.
Estrutura de assinatura e criptografia:
JWE.Encrypt(recipient=ServerKey, format=compact,
JWS.Sign(issuer=UserKey, format=compact,
JSON.Stringify(CardSensitiveInput)
)
)
Ou seja, os dados conforme o esquema JSON CardSensitiveInput devem ser serializados e então assinados utilizando JSON Web Signature (JWS) em formato compacto e então cifrados utilizando JSON Web Encryption (JWE) também em formato compacto. O resultado final deve ser utilizado como valor deste parâmetro.
O esquema define as seguintes chaves para o objeto de entrada
(CardSensitiveInput
):
pan
: O número da conta primária (Primary Account Number),
também conhecido como \"número do cartão\" físico. Exemplo:
"1234567890123456"
expiry
: Data de validade do cartão, ou seja, quando ele
expira. É um objeto composto pelas chaves month
e year
descritas a seguir. Exemplo: {"month": 2, "year": 2020}
month
: Mês da validade do cartão. Número inteiro entre 1
(Janeiro) e 12 (Dezembro).
year
: Ano da validade do cartão. Número inteiro com 4
dígitos (2017, não 17).
name
: Nome do portador do cartão. Exemplo: "João da Silva"
.
A autorização é feita com os campos csc
ou authCode
e seus
respectivos horários de entrada. Note que apenas um deles deve ser
especificado:
O número do cartão (pan
) será utilizado para descoberta dos
demais campos do cartão, como availableServices
, bin
,
funding
, product
, isInternational
, isCompany
, isToken
,
brand
, allowedCaptures
, usages
, network
, issuer
e
metadata
.
merchant
:
MerchantInput
obrigatórioInformações do Comerciante. Possui campos como razão social, nome fantasia, documentos legais (CNPJ) e categorias (MCC).
PageInfo
compatível com Relay.
Campos:
hasPreviousPage
:
Boolean
obrigatóriohasNextPage
:
Boolean
obrigatóriostartCursor
:
String
endCursor
:
String
Aresta de conexão contendo dados de verificação de conta em conformidade com o Relay.
Campos:
cursor
:
String
obrigatórioCursor opaco para ser usado com queries (consultas) after
ou
before
.
Conexão de verificação de conta em conformidade com o Relay.
Campos:
totalCount
:
Int
Contagem total de objetos nesta conexão.
Arestas são limitadas a cursores before
e after
, assim como
primeiras e últimas contagens. Assim o tamanho de arestas é possivelmente
menor que a conexão como um todo.
totalCount
, se não for null
, indica o número total de itens na conexão
considerando-se o filtro.
Dado da solicitação de validação de conta.
Campos:
verifiedAt
:
DateTime
obrigatórioData que a validação de conta foi realizada.
Retorno da mutação verifyPaymentAccount()
.
Compatível com Relay.
Campos:
clientMutationId
:
String
Estado da validação de conta.
Valores possíveis:
VALID
Conta valida
INVALID
Conta invalida
NOT_SUPPORTED
Conta não suporta validação
ERROR
Erro no processamento
Tipo de transação solicitada para a validação de conta.
Valores possíveis:
CREDIT
Crédito
DEBIT
Débito