Let’s kick off with a simple example:
Below we find all cards having 12345678
as IIN/BIN.
curl https://api.iinlist.com/cards?iin=12345678
--header "X-API-Key: $API_KEY"
A response will look like this:
|
|
Use our API to get up-to-date metadata about a payment card. Provide the first 6-8 digits (IIN/BIN) of a payment card number to get metadata such as country, account funding (debit or credit), product segment (consumer or business) etc.
The Issuer Identification Number (IIN) and Bank Identification Number (BIN) is the first 6-8 digits of a payment card number. They are two terms for the same thing and used interchangeably. For the remainder of this documentation we use Issuer Identification Number (IIN) for consistency.
The Issuer Identification Number (IIN) can be used to look up the account range of a payment card.
A payment card number belongs to an account range having the associated metadata to be used in the payment ecosystem. An Issuer Identification Number (IIN) can be used to look up what account range a payment card number belongs to in order to get the metadata about the payment card. The account range is created in collabaration between a card scheme and an issuer.
Our API does all the hard work of looking through the account ranges to identify a match with the provided Issuer Identification Number (IIN) and return the associated metadata. The metadata is returned as a card resource like shown in the example above.
We’ve done our best to make it as simple and effortless to use our API. Enjoy :)
The base URL is api.iinlist.com
and functioning as the entry point of the API.
Send a GET
request to the base URL to explore the resources of the API.
curl https://api.iinlist.com
An example response can be seen under the root resource in the API reference.
All URLs (except base url) require an API key specified in the X-API-Key
header.
curl https://api.iinlist.com/cards?iin=12345678
--header "X-API-Key: $API_KEY"
The API key is secret, so think about how you use and store it. Ensure it is not shown as clear text anywhere e.g in code, terminal etc - See recommendation for testing in the terminal. If you suspect somebody knows your API key please reach out to us immediately at [email protected], so we can disable it and issue a new one.
You can get an API key by signing up to one of our subscription plans.
The latest version of the API is Version 1
. All requests not specifying a
version will receive the latest version of the API. We can specify the version
through a media type parameter in the Accept
header to avoid breaking changes
when a new major version is released. An example of this is shown below in the
sub-section Request Accept header.
The following media type and media type parameters are supported:
application/hal+json; charset=utf-8; version=1
By default, all returned responses have the following Content-Type
header:
Content-Type: application/hal+json; charset=utf-8; version=1
To accommodate future media types and maybe changes in the default response
Content-Type
header, we should specify our preferences in the Accept
header
when making a request:
Accept: application/hal+json; charset=utf-8; version=1
In most of the examples in the documentation we’ve left out the Accept
header
for simplicity. However we still recommend it being specified by the client.
Errors will be communicated through the HTTP response status code and (for now)
an empty JSON object as the response. An example of a 401 Unauthorized
:
curl https://api.iinlist.com/cards?iin=12345678
HTTP/2 401
Content-Type: application/hal+json; charset=utf-8; version=1
...
{}
The following recommendations will provide tips on the integration and help make a flexible client for consuming the API.
We should make sure to do not provide a full payment card number as an IIN. The
API will not accept more than 8 digits, but logging mechanisms (maybe yours?)
will often log the URL of a GET
request where the IIN is provided to the API.
Our plan is to continuously add property names and values to the returned resources. The client we build should allow for new property names and values to emerge on e.g. the returned Cards. If you are missing data, please reach out to us at [email protected].
We should save the base URL as our entry point, but the rest of the resources should be explored through the links. This will allow your client to just follow the resources without hardcoding the links. It will make it easy to explore and integrate new resources when they become available. See this external HAL page for more information about HAL - The (hyper)media type used by the API.
A HAL client following links would have code looking like the pseudocode:
root('api.iinlist.com').follow('cards').queryString('iin=12345678').get
With that being said. We have no intentions of changing any URLs if one decide on consuming the Cards directly via the shown URL.
When testing the API through cURL we can do the following below to prevent the API key from floating around in the terminal.
|
|
When running the above, the terminal will ask for the API key in a masked field.
After inserting the API key it is provided to the cURL request as a variable and
the variable is unset when the request is finished. The commands can also be run
seperately to read an api key to a variable and fire multiple requests before
using the unset command. To do that remove both &&
and the \
in line 4.
The API consists of a Root resource and a collection of Card resources.
The Root resource links to all resources in the API to make them discoverable. Currently, it only links to itself and to a collection of Card resources.
GET
Accept
(recommended)
The returned resource will provide a link to itself and the Cards collection.
curl https://api.iinlist.com \
--header "Accept: application/hal+json; charset=utf-8; version=1"
|
|
A collection of card resources belonging to their own individual account range.
GET
X-API-Key
(required), Accept
(recommended)
iin
or bin
(required, 6-8 digits)
Below are the properties of a Card resource. A client should allow for further
property names and values to be added when e.g. a new card scheme is added or
the ISO standard for a Country code is updated. The type of the property value
e.g. string
will not change.
Visa
, Mastercard
, American Express
, Discover
(string)consumer
, business
, commercial
, government
, all
, other
(string)credit
, debit
, prepaid
, charge
, deferred debit
(string)Below we find all cards having 12345678
as IIN.
The client should be able to handle multiple Cards in the response. Depending on the use case the client can decide to show all Cards or apply logic to select the relevant Card(s). Read more about this in Why are multiple Cards returned?
curl https://api.iinlist.com/cards?iin=12345678
--header "X-API-Key: $API_KEY" \
--header "Accept: application/hal+json; charset=utf-8; version=1"
|
|
An IIN is the first 6-8 digits of a payment card number and can be used to look up the account range of a payment card. The account range contains metadata about the payment card, which we return as a Card resource.
When requesting the Card resource it accepts the first 6-8 digit (IIN) of the payment card, but it might require more than 8 digits to uniquely identify the account range of the payment card. The is due to the account range of a payment card is decided beyond the 8th digit. It is therefore not always possible to uniquely identify the account range based on the IIN. In those situations we return all the account ranges matching the provided IIN represented as individual Card resources.
Lets say we have the following 8-digit IIN: 12345678
and the following two
9-digit account ranges below. To make the example simple we use 9 digit account
ranges and only alter the last digit in the ranges.
123456780
to 123456785
123456786
to 123456789
When looking up the above IIN it will fall into both ranges, since the unique account range of the payment card is decided on the 9th digit.
The best way to be certain about the account range of a payment card is to
provide enough digits to filter through them until only 1 account range is left.
Since that is not an option, another way is to filter through the cards based on
100% reliable data from another source. This enables you to know the value of
one or more attributes e.g. that it is a danish payment card so you can try to
filter on account.country
.
We know the above two approaches might not be at your disposal, so below is an example of approaching a concrete use case. Please notice that the approach (and probably other approaches) are not flawless, as shown in the example.
The customer.segment
could be used to filter away all consumer cards to
hopefully end up with a single result. The challenge here could be if the
customer is actually using a consumer card to pay with. If consumer cards are
declined during payment you could look up the cards in hindsight and use the
customer.segment
as a filter to hopefully find the account.country
.