Verificação de Conta
A API de Verificação de Conta habilita para credenciadores um mecanismo facilitado e seguro para validar a existência de uma conta cartão do portador ELO.
Feito para: CredenciadoresSubcredenciadoresPrimeiros passos
Leia Introdução ao GraphQL, com exemplos reais da nossa API.
Crie um usuário no portal do desenvolvedor.
Cadastre sua primeira aplicação.
Utilize o dashboard para acessar suas configurações de acesso.
Para explorar rapidamente as APIs aqui na página de documentação, use o console de GraphQL, na seção de referências. Nele, você pode ver as consultas de exemplo, executá-las e alterá-las.
Introdução
A API de Verificação de Conta tem como principal objetivo oferecer serviços para verificação do status da conta cartão de um portador em compras de cartão não presente. Existem muitas 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.
O mecanismo mais comum para a verificação de conta é realizar uma transação conhecida como transação Zero Dólar. Utilizada em transações e-commerce, esta verificação da existência e condições de uso do cartão é feita através de uma transação tradicional, porém, com um valor baixo, que posteriormente precisa ser estornado pelo solicitante. A API vem para resolver esse problema, fornecendo uma forma de verificar a conta cartão com uma única transação e sem sensibilizar o limite desta conta.
Verificação
Para realizar a verificação de conta do cartão, é preciso utilizar a mutation verifyPaymentAccount (demonstrada abaixo), informando um client_id válido, e também 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: {
cpf: "11684158613"
}
sensitive: "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImVway..."
type: CREDIT
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
}
}
}
Consultas
Você pode executar consultas para verificações já efetuadas anteriormente utilizando a seguinte query, e passando novamente o client_id no cabeçalho da requisição:
query {
verifyPaymentAccounts
{
pageInfo {
hasPreviousPage
hasNextPage
startCursor
endCursor
}
totalCount
edges {
cursor
node {
status,
verifiedAt
}
}
}
}
Referências
Queries
verifyPaymentAccounts
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.
Mutations
verifyPaymentAccount
Mutation responsável por realizar a verificação de conta de um cartão junto ao Emissor(CardIssuer).
Argumentos:
input: VerifyPaymentAccountInput obrigatório
Tipos de Entrada
LegalIdsInputCpfCnpjInput
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
VerifyPaymentAccountFilterInput
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.
AcquirerInput
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
MerchantInput
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.
VerifyPaymentAccountInput
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 chavesmontheyeardescritas 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).
Tipos
PageInfo
PageInfo compatível com Relay.
Campos:
hasPreviousPage
:
Boolean obrigatóriohasNextPage
:
Boolean obrigatóriostartCursor
:
String endCursor
:
String VerifyPaymentAccountsEdge
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.
VerifyPaymentAccountsConnection
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.
VerifyPaymentAccount
Dado da solicitação de validação de conta.
Campos:
verifiedAt
:
DateTime obrigatórioData que a validação de conta foi realizada.
VerifyPaymentAccountPayload
Retorno da mutação verifyPaymentAccount().
Compatível com Relay.
Campos:
clientMutationId
:
String Enumerações
PaymentAccountStatus
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
TransactionType
Tipo de transação solicitada para a validação de conta.
Valores possíveis:
CREDIT
Crédito
DEBIT
Débito