pt-BR|en

  • 01

    First steps

  • 02

    Introduction

    • HTTP Headers

  • 03

    Consulting a single BIN

  • 04

    Downloading the entire BIN Table

  • 05

    Erros Comuns

  • 06

    Referências

    • Queries

    • Tipos

    • Enumerações

BIN Table

BIN Table API allows the merchant to identify an Elo transaction and perform proper routing of authorization, also making it possible to use this information for fraud prevention purposes.

Feito para:  MerchantsAcquirersPayment Service Providers

Como funciona

First steps

  1. Read Introduction to GraphQL, with real examples of our API.

  2. Create a user in the developer portal.

  3. Register your first application.

  4. Use the dashboard to access your access settings.

  5. To quickly explore the APIs here on the documentation page, use the GraphQL console in the References section. In it, you can view the sample queries, run them, and change them.

Getting Started on the Elo Developer Platform

Jaydson GomesDeveloper

Introduction

The Primary Account Number (PAN) is segmented by prefixes called "BIN", or Bank Identification Number.

The prefix size, also known as "BIN size", tells you how many digits on the left of the card number are used. Originally it was only 4 digits, today is 6 and is expected to reach 9 digits. The size is then parameterized as a range, reported in the binTable { sizeRange } query (see below).

Because the size of the BIN impacts the size of the card number (PAN), each BIN parameterizes the PAN sizes it expects, as well as a range in the BIN { panSizeRange } query.

Once the BIN is recognized, the system can be queried for several attributes, such as:

  • What is the country of origin of the card? BIN { country }

  • Can the card be used internationally? BIN { isInternational }

  • What is the financing of the card? credit, debit, multiple (both)? BIN { funding }

  • Is it a corporate or personal card? BIN { isCompany }

  • Is it a real or virtual card (CardToken)? BIN { isToken }

  • Where can I capture the card? (E.g ATM, Point of Sale, Internet ...) BIN { allowedCaptures }

  • What are the types of use? (Eg. Credit, Credit in installment by the Store, Debit...) BIN { usage }

  • Which is the card scheme? BIN { brand }

  • Which network can the card be used for? (Eg Elo, Elo-Discovery ...) BIN { cardNetwork }

  • What is the issuer (bank) of the card? BIN { issuer }

  • What cardholder services does the card offer? (Eg Travel Insurance) BIN { services }

HTTP Headers

Todas as chamadas desta API exigem que o client_id e o Content-Type: application/json estejam presentes nos cabeçalhos da requsição. Cabeçalhos necessários para as chamadas:

Chave Obrigatório Descrição
Content-Type Sim Define o tipo de dado transferido na chamada
client_id Sim Identificador da aplicação cliente obtida no portal

Consulting a single BIN

A BIN can be queried with the bin(id) query:

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

    # Should return Banco do Brasil
    issuer {
      name
    }

    # Should return Grafite
    product {
      name
    }

    # Captures allowed (e.g.: point of sale `POS`, Internet,
    # Telemarketing...)
    allowedCaptures {
      name
      code
    }

    # Uses allowed (e.g.: Sight Credit, Debit, In installment by
    # Store...)
    usages {
      name
      code
    }

    # Cardholder services (benefits) (i.e.: Travel Insurance,
    # Purchase Protection, Extended Warranty, Wi-Fi)
    services {
      name
    }
  }
}

Such parameters can be used by third parties users, for example a merchant, for card validation and even fraud prevention. However, querying a BIN at a time may not be efficient, since BINs do not change as often. It would be better to download a copy of the entire table.

Downloading the entire BIN Table

For this we use the ‘binTable’ query, which returns a list of all the BINs and each one can be queried in the same way that we used individually in the previous example:

query TableOfBins {
  binTable {
    # BIN size range (in digits)
    #
    # Indicates which BIN sizes are
    # present in the table, for
    # exemple `{ min: 6, max: 9 }` indicates that you should
    # check the
    # 


Card number (PAN) prefixes 
    of sizes 6, 7, 8 and 9.
    #
    # In case the values are
    # identical, only one size is supported,
    # for example `{ min: 6, max: 6 }`, only size 6 is
    # present.
    sizeRange {
      min
      max
    }

    # BINs in use (allocated).
    #
    # In this query we will
    # extract a lot of data as an example, if
    # not all are of interest to you, you can simply delete
    # the lines.
    #
    # If more information is
    # needed such as some subfield ‘ID’,
    # address of an Issuer or something similar, just include them
    # according to the fields
    # listed for each subtype.
    bins {
      # BIN Number
      #
      # The number of characters
      # defines the number of digits (size)
      # of the BIN.
      number

      # Range of card number sizes
      # (PAN).
      #
      #
      # The PAN (Primary Account
      # Number) number is 
      # usually 16-digit, being    


      # returned
      # as `min: 16, max: 16`. However, due to need for
      # more cards
      # available, the Market is
      # gradually migrating to more
      # digits -- it is expected to soon it will reach 19.
      #
      # When requesting and
      # validating user input, find a valid BIN
      # for the prefix and then check this field to
    # see if the number of digits is correct.
      panSizeRange {
        min
        max
      }

      # If the card is `CREDIT`, `DEBIT` ou `MULTIPLE` (both).
      funding

      # If the card allows
      # international or domestic use only
      isInternational

      # If the card is corporate or individual
      isCompany

      # If the card is virtual, that is, a _token_
      isToken

      # Card product, e.g.: Nanquim, Grafite, Viagem...
      product {
        name
      }

      # Allowed captures (i.e.: point
    # of sale `POS`, Internet,
      # Telemarketing...)
      allowedCaptures {
        name
        code
      }

      # Uses allowed (e.g.: Credit,
      # Debit, In installment by Store...)
      usages {
        name
        code
      }
    }
  }
}

However, these parameters are not often modified, usually once a week. For this we must write it down the last update and use it in the next query, if it has not been modified, nothing will be returned.

Erros Comuns

Abaixo, você verá uma lista de erros comuns e suas descrições.

  • 200 OK - POST body missing. Did you forget use body-parser middleware?: O header Content-Type não foi passado nos cabeçalhos da requisição ou está inválido.

  • 200 OK - POST Cannot return null for non-nullable field BIN.issuer: número do bin inválido.

  • 401 Unauthorized - Could not find a required APP in the request, identified by HEADER client_id.: O client_id não foi passado nos cabeçalhos da requsição ou ele não existe.

  • 400 Bad Request - Syntax Error: Expected Name, found } : Erro de sintaxe no body que foi enviado no corpo requisição.

Referências


Queries



bin

Query BIN information for a given number

If the number is not associated with an allocated BIN, then it returns null.

Usually only used in tests or demonstrations since users download the entire table with binTable () and do local queries. Since the frequency of updates is low (1 time per week).

Argumentos:

number: String obrigatório

The BIN number, which in turn is a prefix of the card number (PAN - Primary Account Number), that is, the first digits are taken (on the left). The number of digits is parameterized in binTable {sizeRange}, for example {min: 6, max: 9} indicates that the system supports BIN of sizes 6, 7, 8 and 9.



binTable

Download the entire table if the table has been modified after a certain date or version.

ifModifiedSince and ifNoneMatch are equivalent to use in HTTP (If-Modified-Since to Last-Modified, If-None-Match to ETag) and can be used to search for updates in a single request.

In case ifModifiedSince and ifNoneMatch are specified and the table has not been changed, null is returned indicating that the table has not changed.

Argumentos:

ifModifiedSince: DateTime

If provided, it only returns the table if it was updated after the date. In this case all data in the range is returned, not just the data that has changed.

ifNoneMatch: String

If provided, it only returns the table if it was updated after the date. In this case all data in the range is returned, not just the data that has changed.

cardIssuerName: String

Nome do emissor do cartão Se null ou vazio, não realiza filtragem.

code: String

Código que identifica produto Se null ou vazio, não realiza filtragem.




Tipos



IntRange

Sets a range of integers.

Both min and max are included in the range. That is:

  • min: 10, max: 12 defines the numbers: 10, 11 and 12;

  • min: 100, max: 100 defines only the number 100.

Campos:

min

:

Int obrigatório

Minimum number (initial), included in the range.


max

:

Int obrigatório

Maximum number (final), included in the range.



CardProduct

Product information associated with the card

Each card is related to a product. In the case of Elo, product examples are:

  • Basic

  • Classic

  • Corporate

  • Graphite

  • Nanjing

  • Travel

  • Prepaid

Campos:

id

:

ID obrigatório

Unique Global Identifier for this object


code

:

String obrigatório

Code that identifies product.


name

:

String obrigatório

Product's name.

Examples of products Elo:

  • Basic

  • Classic

  • Corporate

  • Graphite

  • Nanjing

  • Travel

  • Prepaid


image

(


width:

Int

If provided, width of the image in pixels.

height:

Int

If provided, image height, in pixels.

mimeType:

String

If provided, the type of file you want (mime-type).

)

:

ImageUrl

URL of the image. If height and width (optional) suggestions are provided for the size to be displayed, the server will return the URL to the image with the size closest to the requested one. If mimeType is provided, preference will be given to this, which is very useful on devices that deal with a single image format. Both the size and the mimeType of the image pointed to by the URL are returned.


url

:

String

Product URL



CardBrand

Card Brand

The Card Brand currently returns Elo.

Campos:

id

:

ID obrigatório

Unique Global Identifier for this object


name

:

String obrigatório

Brand name


image

(


width:

Int

If provided, width of the image in pixels.

height:

Int

If provided, image height, in pixels.

mimeType:

String

If provided, the type of file you want (mime-type).

)

:

ImageUrl

URL of the image. If height and width (optional) suggestions are provided for the size to be displayed, the server will return the URL to the image with the size closest to the requested one. If mimeType is provided, preference will be given to this, which is very useful on devices that deal with a single image format. Both the size and the mimeType of the image pointed to by the URL are returned.


url

:

String

Brand URL



CardNetwork

Network for use of the Card

Each card must be used in a network, for example for Elo cards:

  • Elo for domestic cards;

  • Elo-Discovery for international cards.

Campos:

id

:

ID obrigatório

Unique Global Identifier for this object


name

:

String obrigatório

Network name

Examples for Elo:

  • Elo for domestic cards;

  • Elo-Discovery for international cards.


image

(


width:

Int

If provided, width of the image in pixels.

height:

Int

If provided, image height, in pixels.

mimeType:

String

If provided, the type of file you want (mime-type).

)

:

ImageUrl

URL of the image. If height and width (optional) suggestions are provided for the size to be displayed, the server will return the URL to the image with the size closest to the requested one. If mimeType is provided, preference will be given to this, which is very useful on devices that deal with a single image format. Both the size and the mimeType of the image pointed to by the URL are returned.


url

:

String

Network URL



CardIssuer

Card Issuer Entity

Campos:

id

:

ID obrigatório

code

:

Int

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

image

(


width:

Int

height:

Int

mimeType:

String

)

:

ImageUrl

legalIds

:

CompanyLegalIds obrigatório

contacts

:

lista obrigatória de CompanyContact obrigatório

addresses

:

lista obrigatória de Address obrigatório

url

:

String

cards

(


first:

Int

Limit the list to the first entries, if provided. If it is null, the listing is unlimited. Used in forward navigation.

after:

String

Starts after the opaque cursor, if provided. Used in forward navigation.

last:

Int

Limits the list to the last entries, if provided. If null, the listing is unlimited. Used in back navigation.

before:

String

Starts before the opaque cursor, if provided. Used in backward navigation.

filter:

CardFilterInput

Apply filter, if provided.

)

:

CardsConnection

Queries all card objects (Card) available in the context.

If executed by a cardholder, all cards that the cardholder has issued and issued by this issuer will be returned.

If executed by a cardissuer, all issued cards will be returned.

In other cases, such as when executed by a merchant, an error is produced.



CardMetadata

Card Metadata: how to represent the card visually

Campos:

image

(


width:

Int

height:

Int

mimeType:

String

)

:

ImageUrl

URL of the image. If height and width (optional) suggestions are provided for the size to be displayed, the server will return the URL to the image with the size closest to the requested one. If mimeType is provided, preference will be given to this, which is very useful on devices that deal with a single image format. Both the size and the mimeType of the image pointed to by the URL are returned.


backgroundColor

:

String

Background color (background) in standard web notation: ffffff (white), ff0000 (red), 00ff00 (green), 0000ff (blue). Must be used with foregroundColor when is not possible to use image.


foregroundColor

:

String

Foreground color (foreground) in standard web notation: ffffff (white), ff0000 (red), 00ff00 (green), 0000ff (blue). Must be used with backgroundColor when it is not possible to use image.


issuer

:

String

Card issuer, ie: "A Bank" Must be used when it is not possible to use image.

Is the same that querying BIN { issuer { name } }


brand

:

String

Card brand, ie: Elo It must be used when it is not possible to use an image.

Is the same that querying BIN { brand { name } }


product

:

String

Product name associated with the card, ie: Nanjing, Graphite.

Is the same that querying BIN { product { name } }



binAuthorization

Dados de autorização e liquitação do Cartão.

Campos:

processorId

:

String

Identificador da processadora de autorização do Bin.


processorSettlementId

:

String

Identificador da processadora de liquidação do Bin.


settlementBankNumber

:

Int

Identificador do banco de liquidação deste do Bin.


isP2PEligible

:

Boolean

Se true, então o cartão poderá ser utilizado em transações P2P. Se false, então o cartão NÃO poderá ser utilizado em transações P2P.



BIN

Represents a BIN (Bank Identification Number or Bank Identification Number) in the system.

The BIN is relative to the initial numbers of a card and identifies \in the issuer and associated products.

Each banner has tracks BINs reserved for their use, these are vailable as reserved in thebinTable query.

But the greatest interest is for BIN in use (allocated), which will load information about the sender (bank), financing (payment, debit or both), products (term payments, prepaid, Card for construction - Construcard ...) and even services such as insurance ninety or access to WiFi.

The BIN table is dynamic:

  • As cards from the same prefix (BIN) are unusable and run out of users, the BIN can then be recycled for a new use.

  • As new products are inserted, a previously reserved BIN without users will then be allocated, entering into use.

For i So it's important to keep the BIN table up to date, see binTable. To find out if the table has been updated use \in the name fields similar to HTTP lastModified (date and time the last modification) and etag (entity tag or label of think), which offers a unique identifier on the table , if he changeed then the table change as well.

Campos:

number

:

String obrigatório

panSizeRange

:

IntRange obrigatório

funding

:

CardFunding obrigatório

product

:

CardProduct obrigatório

country

:

String obrigatório

isInternational

:

Boolean obrigatório

regexp

:

String obrigatório

isP2PEligible

:

Boolean

Se true, então o cartão poderá ser utilizado em transações P2P. Se false, então o cartão NÃO poderá ser utilizado em transações P2P.


isCompany

:

Boolean obrigatório

Iftrue, then the card is a corporate, used for legal companies. If false, then the card is for a person.".


isToken

:

Boolean obrigatório

It says if the card is virtual (token, see CardToken). \ n Tokens are often understood as " virtual cards \ "(VCN - Virtual Card Numbers), they are associated with a real card and can have greater control such as currency restriction, purchase number, purchase value, merchant category, and others.

The largest use of tokens is to reduce security problems, before a merchant or cardholder.

If true, then this BIN is used for tokens instead of physical (plastic) cards. Iffalse then this BIN is used for traditional, physical (plastic) cards.


brand

:

CardBrand obrigatório

The scheme of the Card

The scheme responsible for the Card. For Elo cards, it will always be Elo.


allowedCaptures

:

lista obrigatória de CardCapture obrigatório

Capture modes allowed for the card.

This list tells you which capture modes are allowed for the card, for example if POS can then be used at a point of sale (Point Of Sale), otherwise attempting to use it with this will result on a rejected transaction.


usages

:

lista obrigatória de CardUsage obrigatório

Case use allowed for the card.

This list tells you if the card can be used for debit, for credited cash, credit installment by store, among others.


network

:

CardNetwork obrigatório

Network for Card use.

Each card should be used on a network, which is listed in this field. For example the Elo cards use the networks:

  • Elo: home use (isInternational = false);

  • Elo-Discovery: international use.


issuer

:

CardIssuer obrigatório

Card issuer.

All BINs are associated with one and only one issuer, which can be referred to this field to obtain the global identifier Unique, social name, fantasy name, CNPJ, address, contacts, and finals..


metadata

:

CardMetadata obrigatório

Metadata for the presentation of the card to the user

Measures such as:

  • image

  • colors These should be used to present a card to the user in order to clarify the information and avoid errors.


services

:

lista obrigatória de CardHolderService obrigatório

Services (benefits) available to the cardholder.

Services, also known as benefits, cardholder. For example:

  • Travel Insurance, to purchase air tickets;

  • Purchase Protection, to purchase goods;

  • Extended Warranty, to purchase goods;

  • WiFi access.


changeableServices

:

list de CardHolderService obrigatório

Serviços (benefícios) disponíveis para troca, para o portador do cartão.


isMigrated

:

Boolean

Identificada se um BIN que não teve origem no FLEX, foi migrado para FLEX. Se true, identifica que foi migrado para o FLEX. Se false, identifica que ainda não foi migrado para o FLEX.


isFlex

:

Boolean

Identificada se um BIN é FLEX ou não. Se true, identifica que é um bin FLEX. Se false, identifica que ainda não é um BIN Flex.


authorizationDebit

:

binAuthorization

Informações de autorização e liquidação do cartão, para Débito.


authorizationCredit

:

binAuthorization

Informações de autorização do cartão, para Crédito.


is3DS

:

Boolean

Identifica se o BIN está habilitado para o processo de autenticação ELO (3DS Elo). Se true, está habilitado. Se false, não está habilitado.


currency

:

String

Moeda


creditSettlementBankNumber

:

Int

Bank Settlement Bank Number

Indicates which bank code should be used to settle the credit transactions.

Private API


debitSettlementBankNumber

:

Int

Bank Settlement Bank Number

Indicates which bank code should be used to settle the credit transactions.

Private API



BINTable

BIN Table.

Table of all BINs (Bank Identification Number) in the system, both allocated (bins) and reserved (reserved).

Table users are systems that often check\card numbers and their attributes, for example virtual stores (e-commerce).

The table has "version" (etag), as well as the date and time of the last modification, allowing the user to identify changes. In general, the tables are modified weekly.

Campos:

lastModified

:

DateTime

Date and time of last table change.

Can be used to identify that the table has changed. Either by making a query by date and time, either by doing binTable query and passing the date and time of the last known version -- if the table has not changed, nothing will be returned.


etag

:

String

Entity Tag (Entity Tag).

Similar to use in HTTP headers, ETag serves as an identifier that changes when the contents of the table changes.

Like lastModified, it can be used to identify changes in the table. Whether it is querying for the new etag, whether by querying binTable and passing the previous etag -- if the table has not changed, nothing will be returned.


sizeRange

:

IntRange obrigatório

Known BIN Sizes.

The range of sizes of the digit numbers that make up BINs. That is, when querying BINs don't should do with a fixed size (i.e: 6) but all sizes defined in this range.

In the past the BINs were only 4, today they are 6 digits, however the market is migrating to up to 9 digits in the next few years. Then use the number of digits parameterized in your code!

Example: sizeRange { min: 6, max: 9 } informs that you must get size prefixe 6, 7, 8 and 9 from the card number and then fetch them on the table.


bins

:

lista obrigatória de BIN obrigatório

Listing of BINs in use (allocated).


reserved

:

lista obrigatória de ReservedBIN obrigatório

List of reserved, but unused BINs.


binsRegexp

:

String obrigatório

Regular expression that identifies BINs in use (allocated).

The regular expression returned will identify the BIN (number) and the number of digits relative to the panSizeRange of each entry.

For user convenience of regular expression, a group will be returned to the found BIN. The group number is undefined because several are used and built automatically. However one and only one group is returned on success. See the examples below for more details.

For example, consider a BIN table with only two inputs in use (allocated):

  • number: "509069" with panSizeRange: { min: 16, max: 16 };

  • number: "12345678" with panSizeRange: { min: 17, max: 19}.

The regular expression will be: ^(?:(12345678)\d{9,11}|(509069)\d{10})$. If you identify BIN 12345678, for example the 12345678123456789 card, then group 1 will be returned with the value 12345678 (BIN). If you identify BIN 509069, for example the 5090691234567890 card, then group 2 will be returned with the value 509069 (BIN). If another BIN is passed, or the number of digits of a card does not match the panSizeRange of the BIN, then no group is returned and the regular expression will find nothing.


reservedRegexp

:

String obrigatório

Regular Expression that identifies reserved but unused BINs.

The regular expression returned will identify the BIN (number) and the number of digits relative to the panSizeRange of each entry.

For user convenience of regular expression, a group will be returned to the BIN found. The group number is undefined because several are used and built automatically. However one and only one group is returned on success. See the examples below for more details.

For example, consider a BIN table with only two reserved (unused) entries:

  • number: "509069" with panSizeRange: { min: 16, max: 16 };

  • number: "12345678" with panSizeRange: { min: 17, max: 19}.

The regular expression will be: ^(?:(12345678)\d{9,11}|(509069)\d{10})$. If you identify BIN 12345678, for example the 12345678123456789 card, then group 1 will be returned with the value 12345678 (BIN). If you identify BIN 509069, for example the 5090691234567890 card, then group 2 will be returned with the value 509069 (BIN). If another BIN is passed, or the number of digits of a card does not match the panSizeRange of the BIN, then no group is returned and the regular expression will find nothing.


allBinsRegexp

:

String obrigatório

Regular expression that identifies all BINs (allocated and reserved).

The regular expression returned will identify the BIN (number) and the number of digits relative to the panSizeRange of each entry.

For user convenience of regular expression, a group will be returned to the found BIN. The group number is undefined because several are used and built automatically. However one and only one group is returned on success. See the examples below for more details.

For example, consider a BIN table with only two reserved (unused) entries:

  • number: "509069" with panSizeRange: { min: 16, max: 16 };

  • number: "12345678" with panSizeRange: { min: 17, max: 19}.

The regular expression will be: ^(?:(12345678)\d{9,11}|(509069)\d{10})$. If you identify the BIN 12345678, for example the 12345678123456789 card, then group 1 will be returned with the value 12345678 (BIN). If you identify BIN 509069, for example the 5090691234567890 card, then group 2 will be returned with the value 509069 (BIN). If another BIN is passed, or the number of digits of a card does not match the panSizeRange of the BIN, then no group is returned and the regular expression will find nothing.




Enumerações


CardFunding

Card Funding: credit, debit, multiple, Food and Meal.


Valores possíveis:


CREDIT

Credit Card


DEBIT

Debit Card


MULTIPLE

Credit and Debit Card (both simultaneously).


MEAL

Benefit Card (Meal)


FOOD

Benefit Card (Food)


PREPAID

Cartão pré pago


VOUCHER

Voucher


MULTIPLE_PREPAID

Cartão multiplo pré-pago