Overview

Payment Form supports real-time BIN (Bank Identification Number) lookup while a customer enters their card number. BIN lookup retrieves card metadata, such as brand, class, product type, issuer, and issuing country. You can use this information to tailor the checkout experience, for example by displaying surcharge messages, routing payments, or applying fraud checks.

BIN lookup is optional. If BIN data is unavailable, customers can still complete and submit the form without interruption.

How BIN lookup works

When a customer enters a card number in Payment Form, BIN lookup is triggered in stages.

• After at least six digits are entered, Payment Form performs client-side brand detection and updates the card brand logo.
• After at least 13 digits are entered and the customer moves focus away from the card number field, Payment Form calls Zuora’s BIN lookup service. If BIN lookup is enabled for your tenant, the service returns card metadata.

If BIN data is available, Payment Form emits a cardBinInfo event that your integration can handle. If no BIN match is found or the service is unavailable, the form remains usable and the payment can still be submitted.

BIN metadata returned

When BIN lookup succeeds, the cardBinInfo event includes the following fields:

• brand: Card brand, for example VISA or MASTERCARD
• cardClass: Card class, such as Credit, Debit, or Prepaid (if available)
• cardProductType: Product type, for example Commercial or Consumer card (if available)
• issuer: Issing bank name (if available)
• issuingCountryCode: ISO country code of the issuing country, such as US or DE (if available)

If no BIN match is found, the event is raised with a status indicating not found, and some or all fields might be null or omitted.

Use the cardBinInfo event in your integration

After rendering the Payment Form, you can register an event handler to respond to BIN lookup results. This allows you to dynamically adjust the user experience, such as displaying surcharge messages or recommending alternative payment methods.

// Render Payment Form (example)
zuoraPaymentSDK.render('zuora-payment-form', {
  profile: 'PF-00000006',
  locale: 'en',
  region: 'US',
  currency: 'USD',
  amount: '1599.00'
});
// Listen for BIN lookup results
zuoraPaymentSDK.on('cardBinInfo', (data) => {
  if (data.code === 'BinDataFound') {
    if (data.cardClass === 'Credit') {
      showSurchargeBanner('A 2.5% processing fee applies to credit cards.');
    }
    if (data.issuingCountryCode === 'DE') {
      showAlternativeMethodsBanner('We recommend SEPA Direct Debit for German cards.');
    }
  }
});    
            

Availability and configuration

BIN lookup in Payment Form is an opt-in feature. To enable it, contact Zuora Global Support to enable BIN lookup for Payment Forms in your tenant. No additional configuration is required in the Payment Form setup. After enablement, your front end can listen for the cardBinInfo event to consume BIN metadata.