BIN Data Batch API Overview

This guide outlines the process of retrieving BIN bank and market details for your own local database using Pagos BIN Data Batch API. With the Batch BIN file, you can easily integrate BIN data into any bank or customer analysis you conduct. Batch is an in-house alternative to requesting directly from our database via the BIN Data API.

​

Authentication

The Pagos platform uses API keys to authenticate requests to all our services. See our API Authentication guide for full instructions on generating API keys and authenticating with the Pagos APIs.

​

How it works

1. Every Tuesday at 00:00 UTC, Pagos generates and publishes a new batch file with the most up-to-date BIN data from the card networks.
2. Pagos will pre-load the weekly database file for you.
3. You will call /batch/files to fetch URLs to the following weekly Batch files for download: a Basic file containing only standard BIN data, and an Enhanced file containing both standard and enhanced BIN data.
4. Follow the URLs to download the files.

​

File Changes

When calling /batch/files, the response will include a changes object, outlining the following changes to the Batch file since the previous week:

• bins_removed - The number of BIN ranges (rows in the file) removed
• bins_updated - The number of BIN ranges with updated information
• bins_added- The number of new BIN ranges added

The response will also include the percentage of BIN ranges that changed (removed, updated, or added) in the last week, broken out by card brand.

​

Brands Covered

At this time, the BIN Data API includes data for the following card brands.

Supported Card Brands

• Accel
• Amex
• ATM Card
• Bancontact
• Carte Bancaire
• Cirrus
• Culiance
• Dankort
• DinaCard
• Diners Club
• Discover
• EBT
• EFTPOS Australia
• Elo
• Hipercard
• JCB
• Korean Local
• Maestro
• Mastercard
• MIR
• NYCE
• PayPal
• Private Label
• Prop
• PULSE
• RuPay
• STAR
• UATP
• Unionpay
• Visa

​

BIN Data Batch Ranges

When networks issue cards, they generate BINs in ranges. All BINs issued within a set range share flags indicating card currency, card type (e.g. prepaid, reloadable, etc.), local only, gambling enabled/not supported, etc. Because these flags are set at the range level—not the individual BIN level—Batch BIN Data similarly shares BIN details in ranges between a minimum and maximum value. Design your search logic to search for a BIN value within a given range. For example, if you want to review details for BIN 464565, generate the 19-digit value for a card number, padded with zeros; search for all the rows where the card number 4645650000000000000 is between the bin_min and the bin_max.

​

Super Ranges

When adjacent BIN ranges share the exact same data, Pagos collapses them into a single row called a super range. The super range uses the bin_min value from the first adjacent range and the bin_max value from the last. By removing duplicate rows in the file, we can reduce the file size by roughly 5x. You don’t need to change your search logic to accommodate super ranges. Because a super range spans the same bin_min to bin_max as the underlying ranges combined, any BIN value that falls within the span will match the super range row.

​

BIN TTL (Time-To-Live)

The Batch file includes a flagged_for_delete_remaining_wks column, providing continuity for BIN ranges now absent from the network source files. For each BIN range, the value in this column will be either:

• Null - The BIN range is active and not flagged for deletion
• A value 1-4 - The number of weeks until this BIN range is officially removed from the BIN Data Batch files

The first week our network source files no longer contain a particular BIN range, we’ll populate this field with a countdown starting with “4.” Each subsequent week the BIN range remains absent, this value decreases by 1; by the fifth week, we remove the range entirely from the Batch file. If a network adds back a BIN range previously flagged for deletion, a “null” response replaces the countdown. This feature helps you:

• Plan for upcoming BIN removals before they affect your systems
• Maintain continuity when network files temporarily omit a BIN range due to errors
• Distinguish between permanent BIN removals and temporary network file issues

​

BIN TTL and Super Ranges

When a BIN range within a super range is removed from the network source file, Pagos both retains the original super range with the flagged_for_delete_remaining_wks countdown and creates new super ranges at the bifurcation points for the removed range. This gives you visibility into upcoming changes without losing the compact file structure. For example, before a card brand updates the source file, you see the following super range in the BIN Data Batch file: Within this super range, the range 4010213900000000000 - 4010213999999999999 is removed from our network source files. The next Batch file accounts for this by retaining the original super range with the four week countdown and adding the new super ranges representing the remaining active portions of the original: The new super ranges have no countdown values, as they remain active.

​

BIN Data Batch IP Addresses

The following static IP addresses can be used to allowlist API traffic to BIN Data Batch:

• 99.83.189.213
• 75.2.25.63

​

Testing

You can explore a mock Pagos Batch BIN file in sandbox by enabling Test Mode and following the testing details.