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:  CredenciadoresSubcredenciadores

Primeiros passos

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

  2. Crie um usuário 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

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.

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
    }
  }
}

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
      }
    }
  }
}



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


legalIds

:

LegalIdsInputCpfCnpjInput

Documento legal de identificação CPF ou CNPJ.


status

:

PaymentAccountStatus

Estado da validação de conta.


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)


type

:

TransactionType

Tipo de transação solicitada para a validação de conta.


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ório

Identificador 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ó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



Entrada para os dados do comerciante.

Campos:

name

:

String obrigatório

Nome visível publicamente. Normalmente nome bem conhecido, marca, etc.


legalName

:

String obrigatório

Nome legal, como escrito em documentos.


description

:

String

Descrição da empresa para ser apresentado a usuários.


legalIds

:

LegalIdsInput obrigatório

Todos os documentos legais de identificação da empresa.


contact

:

PersonContactInput obrigatório

Contato do comerciante


address

:

AddressInput obrigatório

Endereço postal

  • O campo zip deve ser sempre preenchido.


url

:

String

Endereço Virtual (Uniform Resource Locator).


iso

:

Int obrigatório

Código ISO18245.

Também conhecido como MCC (Merchant Category Code), tem 4 dígitos.


countryCode

:

String obrigatório

Identificador Global Único do país onde está localizado o Merchant, código 076 (Brasil). ISO 3166-1 numeric


idCode

:

String obrigatório

Identificaçã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.


legalIds

:

LegalIdsInputCpfCnpjInput

Documento legal de identificação CPF ou CNPJ


sensitive

:

String obrigatório

Conteú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.


type

:

TransactionType obrigatório

Tipo de transação solicitada para a validação de conta.


acquirer

:

AcquirerInput obrigatório

Informação do Credenciador


merchant

:

MerchantInput obrigatório

Informaçõ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ório

hasNextPage

:

Boolean obrigatório

startCursor

:

String

endCursor

:

String


Aresta de conexão contendo dados de verificação de conta em conformidade com o Relay.

Campos:

cursor

:

String obrigatório

Cursor opaco para ser usado com queries (consultas) after ou before.


node

:

VerifyPaymentAccount

O objeto de verificação de conta que compõe essa aresta de conexão.



Conexão de verificação de conta em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

Cursor opaco para ser usado com queries (consultas) after ou before.


edges

:

Lista de arestas que compõem esta conexão.


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:

status

:

PaymentAccountStatus obrigatório

Estado da validação de conta.


verifiedAt

:

DateTime obrigatório

Data que a validação de conta foi realizada.



Retorno da mutação verifyPaymentAccount().

Compatível com Relay.

Campos:

clientMutationId

:

String

verifyPaymentAccount

:

VerifyPaymentAccount

Verificação de conta realizada.





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