Bin Discount

Bin Discount is a feature on XPay that allows merchants to configure discounts based on card BINs (first 6 or 8 digits of a card). Merchants can apply discounts for specific BINs using either a fixed value or a percentage of the order price.

If a merchant has configured bin discounts on the XPay portal, then when a user enters their card in the SDK:

In React, the onBinDiscount event will return discount details.
In Vanilla JavaScript, the binDiscount event will return discount details.

Using these details, you need to apply the discount to the order.

How to Listen for the Event

Vanilla JavaScript (binDiscount Event)

In Vanilla JavaScript, you can listen for the binDiscount event using the xpay.on() method:

javascript

xpay.on('binDiscount', function (event) {
    console.log(event, 'bin discount event');
    // Apply the discount based on event data
});

React.js (onBinDiscount Event)

In React.js, you can listen for the event using the onBinDiscount prop inside the <PaymentElement /> component:

javascript

<PaymentElement
    onBinDiscount={(data)=> console.log("discount event data", data)}
/>

Event Response Example

When a bin discount is applied, the event will return a response in the following format:

json

{
  "account_id": "0ddb82950784f875",
  "bank_acronym": "HBL",
  "bank_logo": "https://js.xstak.com/assets/logos/HBL.png",
  "bank_name": "Habib Bank Limited",
  "bin": 512345,
  "createdAt": "2025-01-06T09:53:45.148Z",
  "discount_type": "percentage",
  "discount_value": 70,
  "hash": "df49774ea1bcf4ff15ab18af6a989fc84e2e821b19700fb8bc9aa9577d57abe4",
  "id": "d1dffc51-7b7c-4af0-b306-a8cf76c344d4",
  "on_discounted_items": false,
  "rule_enabled": true,
  "store_id": "64f06b2fcabbf492b6d3a1e1",
  "updatedAt": "2025-01-06T09:53:45.148Z",
  "__v": 0,
  "_id": "677ba829b48208d8392c7633"
}

Webhook Response Example

When the order payment is captured, you will receive a webhook response containing the transaction details, including the unique hash for tracking discounts.

json

{
  "type": "PAYMENT_INTENT_NOTIFICATION",
  "payment_intent_id": "xpay_pi_e13ac6a0f90b9ca9d5b4d84b28860fd53a5b9e68e8fbeec2751428afb985c12e",
  "refund_id": null,
  "amount": 1,
  "currency": "PKR",
  "status": "succeeded",
  "customer": {
    "name": "Amir Ghafoor",
    "email": "amir.ghafoor@xstak.com",
    "phone": null
  },
  "shipping": {
    "address1": "Lahore",
    "address2": null,
    "city": "Lahore",
    "country": "Pakistan",
    "phone": null,
    "province": null,
    "zip": "3434",
    "shipping_method": "Free"
  },
  "payment_method_types": "card",
  "product": {
    "product_name": "1 Elie Saab",
    "product_category": "1 Elie Saab",
    "no_of_items": "1",
    "_id": "67ada5d6781137aa5a2b7466"
  },
  "transaction_details": {
    "_id": "67ada5d5781137aa5a2b744b",
    "order": {
      "customer": {
        "name": "Amir Ghafoor",
        "email": "amir.ghafoor@xstak.com",
        "phone": null
      },
      "name": "OB-4700",
      "type": "headless"
    },
    "status": "CAPTURED",
    "secure": "3DS2",
    "refunded_amount": 0,
    "gateway": "bank-alfalah",
    "response_from_bank": "The payment was completed successfully",
    "status_message_from_bank": "PAYMENT_CAPTURED",
    "activity": [
      {
        "status": "AUTHENTICATION_SUCCESSFUL",
        "amount": 1,
        "timestamp": "2025-02-13T08:03:57.921Z",
        "createdAt": "2025-02-13T08:04:03.597Z",
        "token": "",
        "card": {
          "bin": "512345",
          "last4digits": "0008",
          "name": "Amir Ghafoor",
          "funding_method": "DEBIT",
          "type": "MASTERCARD",
          "issuer_details": {
            "card_issuer": "Bank Alfalah Limited",
            "card_network": "MASTERCARD",
            "card_type": "DEBIT"
          }
        },
        "3ds": {
          "authorization_code": "",
          "secure": "3DS2",
          "eci": "02"
        },
        "processing": {
          "acquirer_transaction_id": "trans-Hu94RYUyVS"
        }
      },
      {
        "status": "CAPTURED",
        "amount": 1,
        "timestamp": "2025-02-13T08:04:03.030Z",
        "createdAt": "2025-02-13T08:04:03.597Z",
        "token": "",
        "card": {
          "hash": "df49774ea1bcf4ff15ab18af6a989fc84e2e821b19700fb8bc9aa9577d57abe4",
          "bin": "512345",
          "last4digits": "0008",
          "name": "Amir Ghafoor",
          "funding_method": "DEBIT",
          "type": "MASTERCARD",
          "issuer_details": {
            "card_issuer": "Bank Alfalah Limited",
            "card_network": "MASTERCARD",
            "card_type": "DEBIT"
          }
        },
        "3ds": {
          "authorization_code": "026043",
          "secure": "3DS2",
          "eci": "02"
        },
        "processing": {
          "acquirer_transaction_id": "trans-EN7rWxcoqA"
        }
      }
    ]
  },
  "metadata": {
    "order_reference": "OB-4700",
    "shopify_reference_id": 7849931538738,
    "source": "shopify",
    "products": [
      {
        "title": "1 Elie Saab",
        "image": "abcd101",
        "price": "1.00",
        "quantity": 1,
        "line_item_id": 17819571618098,
        "total_discount": "0.00"
      }
    ]
  }
}

How to Track Discounts Against a Card

If you have configured bin discounts, the event will return a unique hash corresponding to the user's card:

React: onBinDiscount event
Vanilla JS: binDiscount event

When the order payment is captured, you will receive the same hash in the webhook data for the transaction captured status event.

Example Use Case: Restricting Discounts Per Day

If you want to allow only one discount per day for a card, follow these steps:

The event (onBinDiscount in React, binDiscount in Vanilla JS) will return a unique hash for the card.
When the order is captured, the same unique hash will be received in the webhook captured activity details.
Save this hash in your system.
On the next order, before applying the discount, check if the hash already exists. If it does, you can decide whether to allow the discount again.

This ensures that discounts are applied according to your business logic while preventing multiple discounts for the same card within a specified period.