pt-BR|en

  • 01

    Primeiros passos

  • 02

    Introdução

  • 03

    Verificação

  • 04

    Consultas

  • 05

    Referências

    • Queries

    • Mutations

    • Tipos de Entrada

    • Tipos

    • Enumerações

Verificação de Conta Credenciador

A API de Verificação de Conta Credenciadores habilita 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 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

Introdução

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.

Verificação

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


Resposta


  • 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.

Consultas

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


Resposta


  • 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;

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


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.



AcquirerInput

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



MerchantInput

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.



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.


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).




Tipos



PageInfo

PageInfo compatível com Relay.

Campos:

hasPreviousPage

:

Boolean obrigatório

hasNextPage

:

Boolean obrigatório

startCursor

:

String

endCursor

:

String


VerifyPaymentAccountsEdge

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.



VerifyPaymentAccountsConnection

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.



VerifyPaymentAccount

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.



VerifyPaymentAccountPayload

Retorno da mutação verifyPaymentAccount().

Compatível com Relay.

Campos:

clientMutationId

:

String

verifyPaymentAccount

:

VerifyPaymentAccount

Verificação de conta realizada.




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