Use BIN Data to Control Click to Pay

When a customer starts typing their card number, Primer can surface enriched BIN data in the frontend. This includes network details, issuer information such as the country or the bank, or funding type like DEBIT, CREDIT, PREPAID, or DEFERRED_DEBIT. You can use this information to adapt your checkout UI early, before a payment is created. In this guide, you will build a concrete example: block Click to Pay when the selected card network is prepaid, while handling co-badged cards correctly.

What you build

You will implement this behavior:

While BIN data is loading, disable Click to Pay and show a short message
When BIN data is complete, enable Click to Pay unless the selected network is PREPAID

Events you need

Event `primer:bin-data-loading-change`

Use this event to handle the loading state.

Property	Type	Description
`loading`	boolean	`true` when BIN lookup starts, `false` when it completes

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:bin-data-loading-change', (event) => {
  const { loading } = event.detail;
  // Use loading to disable buttons or show a loader
});

Event `primer:bin-data-available`

Use this event to read BIN data once it is available.

Property	Type	Description
`preferred`	`BinDataDetails \| undefined`	Recommended network
`alternatives`	`BinDataDetails[]`	Other detected networks
`status`	`"partial" \| "complete"`	Data completeness
`firstDigits`	`string \| undefined`	BIN prefix

status = "partial" means local detection only.
status = "complete" means enriched BIN data is available, typically after 8 digits.
Only make decisions when status === "complete".

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred, alternatives, status, firstDigits } = event.detail;
});

Recipe: block Click to Pay for prepaid cards

This example is framework agnostic. You only need to wire setClickToPayDisabled to your own Click to Pay button.

function setClickToPayDisabled(disabled, message) {
  const btn = document.querySelector('#click-to-pay');
  const helper = document.querySelector('#bin-message');

  if (btn) btn.disabled = disabled;
  if (helper) helper.textContent = message || '';
}

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:bin-data-loading-change', (event) => {
  if (event.detail.loading) {
    setClickToPayDisabled(true, 'Checking card type...');
  }
});

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { status, preferred, alternatives } = event.detail;
  if (status !== 'complete') return;

  const selectedNetworkFundingType =
    preferred?.accountFundingType ||
    alternatives?.[0]?.accountFundingType;

  if (selectedNetworkFundingType === 'PREPAID') {
    setClickToPayDisabled(true, 'Prepaid cards are not supported with Click to Pay');
    return;
  }

  setClickToPayDisabled(false, '');
});

Co-badged cards

On co-badged cards, BIN data can include multiple networks for the same card. Each network can have its own accountFundingType. That means:

Funding type is network specific
You should evaluate the funding type for the network you will actually use

Example BIN data for a co-badged card

Here is an example payload you may see in the frontend for a co-badged card:

{
  "preferred": {
    "network": "VISA",
    "displayName": "Visa",
    "issuerCountryCode": "FR",
    "issuerName": "SOCIETE GENERALE S.A.",
    "accountFundingType": "DEBIT",
    "prepaidReloadableIndicator": "NOT_APPLICABLE",
    "productUsageType": "CONSUMER",
    "productCode": "F",
    "productName": "Visa Classic",
    "issuerCurrencyCode": "EUR",
    "regionalRestriction": "UNKNOWN",
    "accountNumberType": "PRIMARY_ACCOUNT_NUMBER",
    "allowed": true
  },
  "alternatives": [
    {
      "network": "CARTES_BANCAIRES",
      "displayName": "Cartes Bancaires",
      "issuerCountryCode": "FR",
      "issuerName": "SOCIETE GENERALE",
      "accountFundingType": "DEBIT",
      "prepaidReloadableIndicator": "UNKNOWN",
      "productUsageType": "CONSUMER",
      "productCode": "C",
      "productName": "CB Cobadgé - Classic",
      "issuerCurrencyCode": "EUR",
      "regionalRestriction": "UNKNOWN",
      "accountNumberType": "PRIMARY_ACCOUNT_NUMBER",
      "allowed": true
    }
  ],
  "status": "complete",
  "firstDigits": "497355"
}

How to pick the right funding type

If Primer selects the network automatically

Use the preferred network from the event payload:

const fundingType = preferred?.accountFundingType;

If the customer can select a network

Evaluate funding type for the selected network:

function getFundingTypeForNetwork(network, preferred, alternatives) {
  const allNetworks = [preferred, ...(alternatives || [])];
  return allNetworks.find((n) => n?.network === network)?.accountFundingType;
}

Do not block the entire card just because one of the networks is PREPAID.
Block only the network where accountFundingType === "PREPAID", and keep other valid networks available.

Events reference

Full reference for BIN data events and payload types

Events guide

When, why, and how to use events in your integration

Checkout

Use BIN Data to Control Click to Pay

What you build

Events you need

Event `primer:bin-data-loading-change`

Event `primer:bin-data-available`

Recipe: block Click to Pay for prepaid cards

Co-badged cards

Example BIN data for a co-badged card

How to pick the right funding type

If Primer selects the network automatically

If the customer can select a network

See also

Events reference

Events guide

​What you build

​Events you need

​Event primer:bin-data-loading-change

​Event primer:bin-data-available

​Recipe: block Click to Pay for prepaid cards

​Co-badged cards

​Example BIN data for a co-badged card

​How to pick the right funding type

​If Primer selects the network automatically

​If the customer can select a network

​See also

Events reference

Events guide

What you build

Events you need

Event `primer:bin-data-loading-change`

Event `primer:bin-data-available`

Recipe: block Click to Pay for prepaid cards

Co-badged cards

Example BIN data for a co-badged card

How to pick the right funding type

If Primer selects the network automatically

If the customer can select a network

See also