• Documentation
• Guides

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.

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

The following payment transaction APIs are supported:

• Create Credit Card
• List
• Show
• Update
• Update_gratis
• Retain
• Store
• Redact
• Recache
• Transactions
• Confirm (Offsite transactions)
• Purchase
• Authorize
• Verify
• Deliver

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

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": "admin@example.com",
        ...
        "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"
    }
}