BIN discounts

Use a BIN discount to apply a merchant-configured fixed or percentage discount when the customer's card BIN is eligible. A BIN is the first six or eight digits of a card number.

How it works#

1. The merchant configures eligible BINs and discount rules in XPay.
2. The merchant creates a PaymentIntent with BIN discount evaluation enabled.
3. The customer enters a card in XPay Element.
4. XPay evaluates the BIN, order amount, active days, and configured usage limits.
5. The Web SDK emits the applicable BIN result.
6. XPay includes the accepted discount result in the payment outcome.

Enable discount evaluation#

Add apply_bin_discount to the PaymentIntent request:

{
  "amount": 1000,
  "currency": "PKR",
  "payment_method_types": "card",
  "apply_bin_discount": true
}

Use the complete Create a PaymentIntent request for customer and merchant-reference fields.

Initialize Web SDK v5 for pre-calculation#

Pass the PaymentIntent client secret as piClientSecret when BIN discount results must be calculated for the current PaymentIntent:

const xpay = new XPay({
  publishableKey: "{{publishable_key}}",
  accountId: "{{account_id}}",
  piClientSecret: paymentIntent.pi_client_secret
});

In Vanilla JavaScript, listen for binDiscount. In React, use onBinDiscount on PaymentElement. Use the event to update the displayed order summary; use the accepted payment and webhook data for backend reconciliation.

Calculate tax after a discount#

When the merchant uses an exclusive tax, XPay documentation applies the tax after the BIN discount. For a PKR 1,000 order with a 10% discount and 8% exclusive tax:

Discount: 1,000 × 10% = PKR 100
Discounted amount: 1,000 − 100 = PKR 900
Tax: 900 × 8% = PKR 72
Total: 900 + 72 = PKR 972

The related PaymentIntent fields are:

{
  "apply_bin_discount": true,
  "tax_info": {
    "rate": 8,
    "type": "exclusive"
  }
}

Confirm supported tax types, additional charges, discount limits, and amount units in the Create Payment Intent API.

Validate a merchant-applied BIN#

When the merchant already selected a BIN-specific offer, provide the six- or eight-digit BIN as a string:

{
  "applied_bin": "123456"
}

XPay validates the submitted card against the supplied BIN during payment processing.

Next steps#

• XPay Web SDK.
• Integrate XPay webhooks.
• Use the Fetch BIN details via BIN Number API for the lookup schema.