Skip to main content

Documentation Index

Fetch the complete documentation index at: https://primer.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.
PropertyTypeDescription
loadingbooleantrue 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.
PropertyTypeDescription
preferredBinDataDetails | undefinedRecommended network
alternativesBinDataDetails[]Other detected networks
status"partial" | "complete"Data completeness
firstDigitsstring | undefinedBIN 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.

​
See also

Events reference

Full reference for BIN data events and payload types

Events guide

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