BinDB Web Portal Documentation
API Technical Documentation
Contents of this document:1.Introduction to BIN Identification
2.What is the Web Portal?
3.Features
4.API Usage
5.API XML Response Structure
6 API JSON Response Structure
7.API Errors
8.Conclusion
1. Introduction to BIN Identification
In some ways the Bank Identification Number (BIN) is similar to a vehicle's license plate. The BIN/IIN Number carry encoded details about a bank payment card’s origins and type. The first six digits of any bank card number carry information about the type, country, bank and level of the card. With the Web Portal our clients gain valuable insight on online payments and their potential customers. Being able to determine the issuing bank and credit level information about a credit card used in an online payment gives our clients a great opportunity to assess the risk of any online transaction. The client can build their payment processing logic based on the checks performed using the BIN Database.2. What is the BinDB Web Portal?
BinDB Web Portal is an online system which provides businesses with an online interface where they can perform real-time BIN identification. A manual search engine allows you to look up any BIN number in the database and the API helps integrate our service in your company software. A multi-user support allows you to create sub-users for your employees and keep a historical records of all queries performed through the manual search or the API. The portal can be linked to either the Premium Database or the Ultimate Database depending on the types of transaction and level of coverage you need.3. Features
BinDB's Premium Database License allows our clients do the following using only the first six digits of any credit card number.- Determine if a card is a VISA, MASTERCARD, AMERICAN EXPRESS or any other card brand.
- Determine if a card is a Debit card or a Credit card.
- Find the level of the card such as Business, Platinum, Gold etc.
- Detect Prepaid, Gift and Virtual Cards.
- Find which bank has issued the card.
- Find from which country the card was issued.
- Find the issuing contact phone and website of the bank which issued the card.
4. API Request Usage
The API system allows you to automate BIN identification via a simple HTTP GET request. Inside your Online Portal you can find your API key which is used to secure the search requests. An example of the the API request can be found below:https://apiserver/api.php?api_key=[API_KEY]&bin=[BIN]
Example
https://apiserver/api.php?api_key=68Y6NV485VY4596BN4856Y&bin=546616An XML Schema of the API’s response can be found in the documentation archive. A detailed description of the fields returned can be seen in the table below:
Input Parameters
Field Name | Type | Description | Example |
---|---|---|---|
API_KEY | String | The key to use to authenticate to the service. | 68Y6NV485VY4596BN4856Y |
BIN | String | The first six digits of a card number are known as the issuer identification number | 546616 |
API-Response XML Schema.xsd - A XSD Schema file containing description of the fields returned in the API XML response.
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="result"> <xs:complexType> <xs:sequence> <xs:element type="xs:int" name="bin"/> <xs:element type="xs:string" name="brand"/> <xs:element type="xs:string" name="bank"/> <xs:element type="xs:string" name="type"/> <xs:element type="xs:string" name="level"/> <xs:element type="xs:string" name="isocountry"/> <xs:element type="xs:string" name="country_iso"/> <xs:element type="xs:string" name="country2_iso"/> <xs:element type="xs:short" name="country3_iso"/> <xs:element type="xs:anyURI" name="www"/> <xs:element type="xs:string" name="phone"/> <xs:element type="xs:string" name="info"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Download Schema.xsd
5. API XML Response Result Structure
The API system returns results in XML format which is easy to parse in a variety of programming languages and platforms. A sample XML reply from the API would be:<?xml version="1.0" encoding="utf-8" ?> <result> <bin>546616</bin> <brand>MASTERCARD</brand> <bank>CITIBANK N.A.</bank> <type>CREDIT</type> <level>WORLD ELITE</level> <isocountry>UNITED STATES</isocountry> <info>AADVANTAGE EXECUTIVE</info> <country_iso>US</country_iso> <country2_iso>USA</country2_iso> <country3_iso>840</country3_iso> <www>WWW.CITI.COM</www> <phone>1-888-776-2484</phone> </result>
6. API JSON Response Result Structure
The API system also can return results in JSON format. A sample JSON reply from the API would be:{ "bin": "543210", "brand": "MASTERCARD", "bank": "NATIONAL PENN BANK", "type": "", "level": "", "isocountry": "UNITED STATES", "info": "877-866-7827 OR 800-822-3321", "country_iso": "US", "country2_iso": "USA", "country3_iso": "840", "www": "www.natpennbank.com", "phone": "+1 610 369 6128" }
Result Fields
Field Name | Length | Type | Description | Example |
---|---|---|---|---|
BIN | 6 | Numeric | The first six digits of a card number are known as the issuer identification number (IIN) aka Bank Identification Number (BIN) | 546616 |
BRAND | 128 | String | Card brand specifies the card company/vendor which issued the card i.e. Visa/MasterCard/AMEX etc. | MASTERCARD |
BANK NAME | 128 | String | Name of the bank or financial institution which issued the card. | CITIBANK N.A. |
TYPE | 32 | String | Type of card. i.e. CREDIT/DEBIT | CREDIT |
LEVEL | 32 | String | The level field specifies of a card is PREPAID/GOLD/GIFT/BUSINESS/ELECTRON etc. | WORLD ELITE |
ISOCOUNTRY | 64 | String | Full name of the country of origin e.g. “United States” | UNITED STATES |
INFO | 128 | String | Additional information if available. Usually contact or alternative contact information about the issuing bank. | AADVANTAGE EXECUTIVE |
COUNTRY_ISO | 2 | Char | Two letter ISO country code. | US |
COUNTRY2_ISO | 3 | Char | Three letter ISO country code. | USA |
COUNTRY3_ISO | 3 | Numeric | Numeric ISO country code. | 840 |
WWW | 128 | String | URL Address of the issuing bank's main website. | WWW.CITI.COM |
PHONE | 128 | String | Contact phone number of the issuing bank. Usually the main branch phone. | 1-888-776-2484 |
7. API Response Errors
In case of an error the API returns an XML response containing the error message. The <error></error> XML tags are returned without any other fields in the XML response. Below you can find a description of all possible error messages that could be returned:Result Errors
ID | Cause | Resolution | 100 | API key required | You need to submit the API key to our API for each request. API key can be found in your Web Portal -> API -> API Access section. |
---|---|---|
101 | BIN not specified | BIN field is required for successful search. |
102 | Invalid API key | Please check that you are submitting your API key exactly as in your account. |
103 | IP Address is not allowed | You need to allow access to your server or computer's IP address in your Web Portal -> API Access section. |
104 | Unspecified Error | If you experience this error, please contact our support for further investigation. |
105 | BIN Not Valid | BIN must be exactly six digits long for correct idenfitication. |
106 | BIN Not Found | The submitted BIN has not been found in our database. Please report to support for investigation. |
107 | Subscription Expired | Your membership has expired, please go to Membership section for instructions how to renew your membership. |
8. Conclusion
Other technical questions can be directed to sales@bindb.com. If you are interested in purchasing Premium License, please contact our order page.