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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "count": 1,
  "_embedded": {
    "cards": [
      {
        "scheme": {
          "name": "Visa"
        },
        "range": {
          "type": "account"
        },
        "product": {
          "name": "Visa Classic",
          "segment": "consumer"
        },
        "account": {
          "funding": "debit",
          "country": {
            "code": "DK"
          },
          "currency": {
            "code": "DKK"
          }
        },
        "issuer": {
          "name": "Foreningen Af Danske Kortudstedere F.M.B.A"
        },
        "fast_funds": {
          "domestic": false,
          "cross_border": false
        }
      }
    ]
  }
}

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 or a token 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) are the first 6-8 digits of a payment card number or token. 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.

To keep things simple we consider the Issuer Identification Number (IIN) to also cover the 6-8 digits of a token and not only the payment card number. The Issuer Identification Number (IIN) can be used to look up the account range or token 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.

A token replaces a payment card number and belongs to a token range. The token range contains the associated metadata about the payment card to be used in the payment ecosystem. An Issuer Identification Number (IIN) can be used to look up what token range a token belongs to in order to get the metadata about the payment card.

Our API does all the hard work of looking through the account and token 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.

1
2
3
4
5

read -s API_KEY &&
curl --request GET \
     --url https://api.iinlist.com/cards \
     --header "X-API-Key: $API_KEY"  \
&& unset API_KEY

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"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "_links": {
    "self": {
      "href": "https://api.iinlist.com"
    },
    "cards": {
      "href": "https://api.iinlist.com/cards{?iin,bin}",
      "templated": true
    }
  }
}

A collection of card resources belonging to their own individual account range or token 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.

• Scheme: (object)
  • Name: Visa, Mastercard, American Express, Diners Club International, Discover, Japan Credit Bureau, UnionPay (string)
• Range: (object)
  • Type: account (account range) or token (token range) (string)
• Product: (object)
  • Name: e.g. Visa Classic. (string)
  • Segment: consumer, business, commercial, government, all, payouts (string)
• Account: (object)
  • Funding: credit, debit, deferred_debit, prepaid, prepaid_reloadable, charge(string)
  • Country (object)
    • Code: Country code of the account (string, ISO 3166 Alpha-2 code)
  • Currency: (object)
    • Code: Currency code of the account. (string, ISO 4217 three-letter code) Notice: Only for Mastercard at the moment.
• Issuer: (object)
  • Name: Name of the issuer. (string)
• Fast funds: (object)
  • Domestic: Indicates if fast funds is supported for Domestic. (boolean)
  • Cross Border: Indicates if fast funds is supported for cross-border (boolean)

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"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "count": 1,
  "_embedded": {
    "cards": [
      {
        "scheme": {
          "name": "Visa"
        },
        "range": {
          "type": "account"
        },
        "product": {
          "name": "Visa Classic",
          "segment": "consumer"
        },
        "account": {
          "funding": "debit",
          "country": {
            "code": "DK"
          },
          "currency": {
            "code": "DKK"
          }
        },
        "issuer": {
          "name": "Foreningen Af Danske Kortudstedere F.M.B.A"
        },
        "fast_funds": {
          "domestic": false,
          "cross_border": false
        }
      }
    ]
  }
}

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 or token range or a token. The account or token 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 or token, but it might require more than 8 digits to uniquely identify the associated range. The is due to the range of a payment card or token is decided beyond the 8th digit. It is therefore not always possible to uniquely identify the range based on the IIN. In those situations we return all the 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 ranges below. To make the example simple we use 9 digit ranges and only alter the last digit in the ranges.

1. From 123456780 to 123456785
2. From 123456786 to 123456789

When looking up the above IIN it will fall into both ranges, since the unique range of the payment card or token is decided on the 9th digit.

The best way to be certain about the associated range of a payment card or token is to provide enough digits to filter through them until only 1 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 from Denmark 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.