Tabela de bins

API de Tabela de BINs permite com que o estabelecimento comercial identifique uma transação Elo e realize o roteamento adequado de autorização, possibilitando ainda utilização destas informações para fins de prevenção de fraudes.

Feito para:  Estabelecimentos ComerciaisAdquirentesFacilitadores

Como funciona

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

O número do cartão (PAN - Primary Account Number) é segmentado por prefixos chamados "BIN", sigla em inglês para Bank Identification Number ou Número de Identificação do Banco.

O tamanho do prefixo, também conhecido como "tamanho do BIN", diz quantos dígitos à esquerda do número do cartão são utilizados. Originalmente já foi de apenas 4 dígitos, hoje são 6 e espera-se que chegue até 9 dígitos. Logo o tamanho é parametrizado como uma faixa, informada na consulta binTable { sizeRange } (veja mais a seguir).

Como o tamanho do BIN impacta no tamanho do número do cartão (PAN), cada BIN parametriza os tamanhos de PAN que ele espera, também como uma faixa na consulta BIN { panSizeRange }.

Uma vez reconhecido o BIN, pode-se então consultar o sistema por diversos atributos, tais como:

  • Qual o país de origem (domicílio) do cartão? BIN { country }

  • O cartão pode ser utilizado internacionalmente? BIN { isInternational }

  • Qual o financiamento do cartão? crédito, débito, múltiplo (ambos)? BIN { funding }

  • É um cartão corporativo ou de pessoas físicas? BIN { isCompany }

  • É um cartão real ou virtual (CardToken)? BIN { isToken }

  • Onde posso capturar o cartão? (Ex. Caixa Eletrônico, Ponto de Venda, Internet...) BIN { allowedCaptures }

  • Quais tipo de uso? (Ex. Crédito à Vista, Crédito Parcelado pela Loja, Débito...) BIN { usage }

  • Qual é a bandeira do cartão? BIN { brand }

  • Qual rede o cartão pode ser utilizado? (Ex. Elo, Elo-Discovery...) BIN { cardNetwork }

  • Qual o emissor (banco) do cartão? BIN { issuer }

  • Quais serviços ao portador o cartão oferece? (Ex. Seguro Viagem) BIN { services }

Um BIN pode ser consultado com a consulta bin(id):

query OneBin {
  bin(number: "509069") { # Banco do Brasil - Grafite

    # Deverá retornar Banco do Brasil
    issuer {
      name
    }

    # Deverá retornar Grafite
    product {
      name
    }

    # Capturas permitidas (i.e: ponto de venda `POS`, Internet,
    # Telemarketing...)
    allowedCaptures {
      name
      code
    }

    # Usos permitidos (i.e: Crédito à Vista, Débito, Parcelado pela
    # Loja...)
    usages {
      name
      code
    }

    # Serviços (benefícios) ao portador (i.e: Seguro de Viagem,
    # Proteção de Compra, Garantia Estendida, WiFi)
    services {
      name
    }
  }
}

Tais parâmetros podem ser utilizados por terceiros, por exemplo um comerciante, para validação do cartão e até prevenção à fraude. No entanto consultar um BIN por vez pode não ser eficiente, já que os BINs não mudam com tanta frequência. Seria melhor baixar uma cópia de toda a tabela.

Para isso utilizamos a consulta binTable, a qual retorna uma lista de todos os BINs e cada um pode ser consultado do mesmo modo que utilizamos individualmente no exemplo anterior:

query TableOfBins {
  binTable {
    # Faixa de tamanho (em dígitos) do BIN
    #
    # Indica quais os tamanhos de BIN estão presentes na tabela, por
    # exemplo `{ min: 6, max: 9 }` indica que deve-se conferir os
    # prefixos do número do cartão (PAN) de tamanhos 6, 7, 8 e 9.
    #
    # Caso os valores sejam idênticos, apenas um tamanho é suportado,
    # por exemplo `{ min: 6, max: 6 }`, somente o tamanho 6 está
    # presente.
    sizeRange {
      min
      max
    }

    # BINs em uso (alocados).
    #
    # Nesta consulta iremos extrair muitos dados como exemplo, caso
    # nem todos sejam de seu interesse, pode simplesmente apagar as
    # linhas.
    #
    # Caso mais informações sejam necessárias, como `ID` de algum
    # subcampo, endereço de um emissor ou afins, basta incluí-los
    # conforme os campos listados para cada subtipo.
    bins {
      # Número do BIN
      #
      # O tamanho em caracteres define o número de dígitos (tamanho)
      # do BIN.
      number

      # Faixa de tamanhos do número do cartão (PAN).
      #
      #
      # O número do cartão (PAN - Primary Account Number) tem em
      # geral tamanho de 16 dígitos, sendo retornado como `min: 16,
      # max: 16`. Porém devido à necessidade de mais cartões
      # disponíveis, o mercado está gradualmente migrando para mais
      # dígitos -- espera-se que num futuro próximo chegue até a 19.
      #
      # Ao pedir e validar entrada do usuário, encontre um BIN válido
      # para o prefixo e então verifique este campo para saber se o
      # número de dígitos está correto.
      panSizeRange {
        min
        max
      }

      # Se o cartão é `CREDIT`, `DEBIT` ou `MULTIPLE` (ambos).
      funding

      # Se o cartão permite uso internacional ou apenas doméstico
      isInternational

      # Se o cartão é corporativo ou pessoa física
      isCompany

      # Se o cartão é virtual, ou seja, um _token_
      isToken

      # Produto do cartão, ex: Nanquim, Grafite, Viagem...
      product {
        name
      }

      # Capturas permitidas (i.e: ponto de venda `POS`, Internet,
      # Telemarketing...)
      allowedCaptures {
        name
        code
      }

      # Usos permitidos (i.e: Crédito à Vista, Débito, Parcelado pela
      # Loja...)
      usages {
        name
        code
      }
    }
  }
}

No entanto estes parâmetros não são frequentemente modificados, geralmente uma vez na semana. Para isso devemos anotar a última atualização e utilizá-la na próxima consulta, caso ela não tenha sido modificada, nada será retornado.

Para isso utilizamos a consulta binTable com o parâmetro ifNoneMatch passando o último etag retornado, ou null caso a tabela nunca tenha sido baixada. Os nomes e uso são exatamente iguais ao If-None-Match e ETag do HTTP, utilizado para evitar baixar recursos inalterados.

Poucas mudanças sobre o exemplo anterior:

query TableOfBins {
  binTable(ifNoneMatch: "algo-retornado-no-etag-anteriormente-ou-null") {

    # salve este valor em conjunto com a tabela,  
    # e use-o como ifNoneMatch na próxima consulta
    etag  
    # ... demais campos consultados, como feito antes
  }
}