01
First steps
02
Introduction
03
Consulting a single BIN
04
Downloading the entire BIN Table
05
Downloading the enentire BIN table, only if it has changed
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

Read Introduction to GraphQL, with real examples of our API.
Create a user in the developer portal.
Register your first application.
Use the dashboard to access your access settings.
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 }



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.



Downloading the enentire BIN table, only if it has changed

For this we use the binTable query with the ifNoneMatch parameter passing the last etag returned, or null if the table has never been downloaded. The names and usage are exactly the same as If-None-Match and HTTP ETag, used to avoid downloading unchanged resources.

Few changes on the previous example:

query TableOfBins {
  binTable(ifNoneMatch: "something-returned-in-etag-earlier-or-null") 
{

    # save this value in  
    # conjunction with the table,       
    # and use it as ifNoneMatch at the next query
    etag  
    # ... fields consulted, as done before
  }
}



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 is different from the last ETag. In this case all data in the range is returned, not just the data that has changed.



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

Unique Global Identifier for this object

code

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

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

String

Network URL



CardIssuer

Card Issuer Entity

Campos:

ID obrigatório

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

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



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

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.

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

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

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

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