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
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.
Jaydson GomesDeveloper
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 }
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 |
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.
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.
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.
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.
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.
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órioMinimum number (initial), included in the range.
max
:
Int
obrigatórioMaximum number (final), included in the range.
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órioUnique Global Identifier for this object
code
:
String
obrigatórioCode that identifies product.
name
:
String
obrigatórioProduct'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
Card Brand
The Card Brand currently returns Elo.
Campos:
id
:
ID
obrigatórioUnique Global Identifier for this object
name
:
String
obrigatórioBrand 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
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órioUnique Global Identifier for this object
name
:
String
obrigatórioNetwork 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
Card Issuer Entity
Campos:
id
:
ID
obrigatóriocode
:
Int
name
:
String
obrigatóriolegalName
:
String
obrigatóriodescription
:
String
image
(
width:
Int
height:
Int
mimeType:
String
)
:
ImageUrl
legalIds
:
CompanyLegalIds
obrigatóriocontacts
:
CompanyContact
obrigatórioaddresses
:
Address
obrigatóriourl
:
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.
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 } }
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.
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óriocountry
:
String
obrigatórioisInternational
:
Boolean
obrigatórioregexp
:
String
obrigatórioisP2PEligible
:
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órioIftrue
, then the card is a corporate, used for legal companies.
If false
, then the card is for a person.".
isToken
:
Boolean
obrigatórioIt 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órioThe scheme of the Card
The scheme responsible for the Card. For Elo cards, it will always be Elo
.
allowedCaptures
:
CardCapture
obrigatórioCapture 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
:
CardUsage
obrigatórioCase 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órioNetwork 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órioCard 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órioMetadata 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
:
CardHolderService
obrigatórioServices (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
:
CardHolderService
obrigatórioServiç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.
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
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órioKnown 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.
reserved
:
ReservedBIN
obrigatórioList of reserved, but unused BINs.
binsRegexp
:
String
obrigatórioRegular 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órioRegular 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órioRegular 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.
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