BIN Metadata

BIN metadata is a feature that is open to Spreedly customers who want to make more informed and cost-saving payment decisions for their overall business needs. Some examples may include advanced decision making, fraud prevention and customer loyalty tracking.

Spreedly supports BIN Metadata automatically for any card that is currently enrolled in Advanced Vault. By receiving metadata related to the card’s BIN, merchants get the benefits of having real-time updated data without additional API costs and having the ability to detect card type differences to make advanced decision making.


BIN metadata overview

The BIN refers to the first six (or more) digits of a debit or credit card. BIN numbers are moving towards an industry standard of eight digits, which provides a much greater accuracy.

Spreedly updates an internal database on a monthly basis that supports up to 11 digit BINs and includes up to 13 attributes per BIN. Some examples of metadata include card brand, issuing bank, issuing country, card type, etc.

BIN metadata response body

Spreedly will return the most up to date BIN metadata associated with the Payment Method’s BIN on iFrame and each API response that includes a payment method object (see below) and where PAN is used to tokenize. All available attributes will be included; If an attribute is unavailable, the value will be null.

The following payment transaction APIs are supported:

For iFrame, a map of the full payment method in JSON form is returned, which includes the BIN metadata.

Note: Apple Pay and Google Pay are not supported at this time.

Response

Existing API & iFrame properties remain unchanged. Example below is truncated only to illustrate new properties for BIN metadata.

{
        "payment_method": {
            "token": "LE4MDycgmPnMjmvZOcb32kRLYIy",
            "created_at": "2023-07-27T12:58:46Z",
            "updated_at": "2023-07-27T12:58:46Z",
            "email": "[email protected]",
		…
            "managed": true,
            "payment_method_type": "credit_card",
            "bin_metadata": {
                "card_brand": "DISCOVER",
                "card_category": "PERSONAL",
                "card_type": "CREDIT",
                "issuing_bank": "DISCOVER BANK",
                "issuing_country_iso_number": "840",
                "issuing_country_iso_a2_code": "US",
                "issuing_country_iso_a3_code": "USA",
                "issuing_country_iso_name": "UNITED STATES",
                "issuing_bank_phone_number": "1 (800) 347-7000",
                "issuing_bank_website": "HTTPS://WWW.DISCOVER.COM/",
                "bin_type": "PERSONAL",
                "regulated": "Y",
                "max_pan_length": 19,
                "message": "Successful"
            },
            "fingerprint": "bbfaccebd69a9a2623aeb6e71b72718a83d8",
            "verification_value": "XXX",
            "number": "XXXX-XXXX-XXXX-1117"
        }
    }
ElementDescription
card_brandThe card brand (i.e. card network or association) is the organization that facilitates the card’s payment transactions.
Visa
Mastercard
Discover
issuing_bankThe bank that issued the card to the customer. Some examples include:
Chase
Wells Fargo
Charles Schwab
card_typeThe type of card that is issued by the issuing bank. Some examples include:
Credit
Debit
Charge Card
card_categoryThe category of the card that an issuer may assign to a specific card. Some examples include:
B2B
Prepaid
Unembossed
Personal Platinum Revolve
issuing_country_ISO_nameISO country name that is associated with an ISO code. Some examples include:
United States of America
Germany
Canada
issuing_country_ISO_A2_codeISO country codes are internationally recognized codes that designate every country and most dependent areas a two-letter alpha character code or abbreviation. Some examples include:
US (United States of America)
DE (Germany)
CA (Canada)
issuing_country_ISO_A3_codeISO three-letter alpha character code or abbreviation. Some examples include:
US (United States of America)
DEA (Germany)
CAN (Canada)
issuing_country_ISO_numberISO numerical character code or abbreviation. Some examples include:
840 (United States of America)
276 (Germany)
124 (Canada)
issuing_bank_websiteThe web address associated with the issuing bank’s organization. Some examples include:
www.discover.com
http://www.citi.com/uae/homepage/index.htm
issuing_bank_phone_numberThe phone number associated with the issuing bank’s organization. Some examples include:
1-402-935-2050
(707) 449-4000
+7 (495) 981-81-81
max_PAN_lengthThe maximum PAN length associated with the BIN. Some examples include:
16
19
BIN_typeIndication if the card type is for commercial or personal use. Commercial would indicate a card that is associated with a business or given to an employee for use in connection with business expenses. A personal card is used privately by the general consumer, not related to a business. Can be one of the following:
Commercial
Personal
regulatedIf the card issuing bank is regulated (i.e. exempt bank) it means that their assets equal more than $10 billion. However, if the card issuing bank is non-regulated (i.e. non-exempt bank) then they have assets under $10 billion. Bank fees may differ depending if the issuing bank is regulated or not. Can be one of the following:
Y
N