Overview

Parrot by Pagos is an API-driven service that provides detailed bank and market data for the payment cards your customers transact with. Using a simple HTTPS request, you can submit a 6-10 digit <<glossary:bank identification number (BIN)—also known as an Issuer Identification number (IIN)—for a customer's card to the Parrot API. Parrot will then return information about the card type and brand, the bank that issued it, and details of the market it was issued in, such as currency, country, and time zone. At an additional cost, you can request enhanced data for a BIN.

BIN data can help you better understand both your customers and their preferred payment cards. With this added context, you can design and implement a payments strategy that benefits your bottom line and improves the checkout experience for your customers. For examples of how to get started, check out our integration guides.

📘

Note

Parrot doesn't have a test environment. Instead, we offer a free trial for Parrot, which allows you to test out the service and the data it provides.

Sign Up

To get started with Parrot, you can create a free trial account and query up to 100 unique BINs:

1. On the Parrot Sign Up page, select whether to sign up with your email address, Google, or Microsoft account credentials.
2. If you choose to sign up with your email address, enter your email, then click Begin Free Trial.
3. Set a password, then click Continue.
4. Check your email for a verification request from Parrot. Click Verify Email in the confirmation email to verify your new account.
5. Enter your company name, then click Create Your Company to set up your businesses’ Pagos account.

Upgrading to a Paid Plan

After you complete the sign up process, you'll have access to the Parrot Service Panel. The green bar under Remaining BIN Lookups in the main navigation tracks the number of free trial queries you have left. Click Upgrade Plan to select from the available Parrot pricing options.

Generate an API Key

After you create an account, open the Parrot Service Panel to generate an API Key:

1. Click Developers in the main navigation.
2. Click Create API Key to add a new key to your account. A side panel will open with the new key value.
3. Copy your new API key and store it somewhere secure. You can only view this value one time.
4. Click I’ve Copied My Key to confirm and exit out of the side panel.

You'll provide this API key in the x-api-key header when you make your first BIN request to Parrot. Parrot uses this value alone to authenticate your request to our servers; you don't need to provide a password. For more information on how the Pagos platform uses API keys, see our API Keys guide.

Look Up a BIN

You're now ready to query for a BIN! We recommend using cURL on the command line to submit API requests to Parrot, but you can also use API query tools like Postman. Here’s a cURL example for details on BIN 55630400

curl -H "x-api-key:[your API key here]" "https://parrot.prod.pagosapi.com/bins?bin=55630400"

This will return the details for the BIN:

{
    "card": {
        "number": {
            "length": 16
        },
        "bin_min": "5563040000000000000",
        "bin_max": "5563049999999999999",
        "card_brand": "MASTERCARD",
        "type": "Credit",
        "prepaid": false,
        "product": {
            "product_id": "MCF",
            "product_name": "MasterCard Corporate Fleet Card"
        },
        "bank": {
            "name": "CITIBANK N.A."
        },
        "country": {
            "alpha2": "US",
            "numeric": "840",
            "name": "UNITED STATES OF AMERICA"
        },
        "correlation_id": "eyJGaWxlSWQiOjI3NiwiVmVyc2lvbiI6NX0=”
    }
}

Card Product ID and Name

When available, we will provide the details around the card product ID and the card product name – this will denote the type of card typically present on the BIN. More details are available in the BIN / IIN Product Code Guide.

Brands Covered

At this time, Parrot covers BIN data for the following card brands.

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

Enhanced Data

In both Parrot and Parrot Batch, you can request enhanced data. This provides you with up to 35 additional fields beyond the standard data fields of Parrot. It includes additional card brand information, estimated interchange costs, SCA regulation requirements, and more. See the Parrot Data Dictionary for a detailed list of the enhanced data fields available and an example of how BIN data appears in a query response.

Parrot FAQ

What does a Null field response mean?

The data provided in an individual field response depends on what data appears in the files Parrot receives from the card brands. If a field response is null, this means our card brand files don't include any data for that field.

Why are Parrot's responses different from my current BIN list provider's responses?

Pagos receives BIN data directly from the card brands. As such, our response data is accurate and up-to-date according to the latest card brand records. Because other BIN providers may receive their data from third party sources outside of the card brands, so we can't speak to the accuracy of their responses.

Why is BIN_length not always available in a BIN response?

bin_length is an attribute only shared by certain card brands. If a card brand's file doesn't contain this field, Parrot will present a null response. That being said, bin_length is not a necessary field for determining the details of a particular BIN. Instead, we recommend focusing on the values returned for the bin_min and bin_max attributes. BIN min/max values identify the BIN range a customer's card sits within, and all cards within a set range share flags indicating important details about them (e.g. card currency, card type, etc). As a best practice, always submit up to 10 digits for a PAN when querying Parrot to narrow down your results to a specific BIN range.