XPay BIN Discount Integration: Enforcing Transaction Limits Per Card

Enabling BIN Discount Transaction Limits per Card on XPay

Overview

This document provides a step-by-step guide on enabling the BIN Discount feature in XPay, specifically focusing on limiting discount transactions per card. The implementation involves tracking and restricting discount usage based on individual cards using the H Hash.

For additional reference, please review the detailed BIN Discount Documentation here:
Bin Discount Documentation

1. Understanding BIN Discount & Card-Based Limitations

The BIN (Bank Identification Number) Discount feature allows merchants to offer targeted discounts on specific BIN ranges. However, without transaction limits per card, a single cardholder could misuse the discount multiple times.

Objective

Restrict the number of discount transactions per card.
Ensure that each card can only redeem a discount up to a predefined limit within a specified period.
Use H Hash (Hashed Card Identifier) to track and enforce limits without storing sensitive card details.

2. Steps to Enable BIN Discount Limits per Card

Step 1: Configure BIN Discount Rules

Define the BIN ranges (first 6 digits of the card) that qualify for discounts.
Set the discount type (percentage or fixed amount).
Determine the maximum discount amount per transaction.

Step 2: Implement Per-Card Discount Limits

To ensure fair usage, a mechanism must be established to track and limit the number of transactions per card. This can be done using the H Hash.

Generating & Storing H Hash

The H Hash is a one-way hashed representation of the card number, ensuring security while allowing tracking.
XPay’s system should store the H Hash alongside discount usage data.

Defining Limit Rules

Define discount eligibility criteria (e.g., "Each card can avail the discount up to X times per month").
Store a count of discount transactions per card in the database.
Ensure that transactions exceeding this limit are automatically rejected.

3. API Integration & Implementation

Step 3: Update API to Enforce Transaction Limits

Modify the API request to include the H Hash field:

API Request Format

CODE

json

CopyEdit

{ "cardHash": "H_HASH_VALUE", "bin": "XXXXXX", "transactionAmount": 5000, "discountCode": "BIN_DISCOUNT_10", "merchantID": "MERCHANT_123" }

Backend Logic for Checking Discount Usage

Retrieve the H Hash from the request.
Check if the discount limit for this H Hash has been reached.
If within limits, process the discount.
If exceeded, return an error response.

API Response for Exceeded Limit

CODE

json

CopyEdit

{ "response": { "code": "BIN_DISCOUNT_LIMIT_EXCEEDED", "message": "The discount limit for this card has been reached." }, "result": "FAILURE" }

4. Error Handling & Edge Cases

Common Scenarios & Resolutions

Scenario	Expected System Response
Cardholder attempts a discount beyond the allowed limit	API returns `BIN_DISCOUNT_LIMIT_EXCEEDED` error
Discount applied successfully	The transaction is processed with a discount
The cardholder retries with a different eligible card	Discount is applied as long as the new card is within the limits
Invalid BIN or non-eligible card used	API returns `BIN_NOT_ELIGIBLE` error

5. Testing & Validation

Test Cases to Validate Implementation

Test Case	Expected Outcome
Process transactions with discount within the limit	Success
Process transactions after exceeding limit	Failure (`BIN_DISCOUNT_LIMIT_EXCEEDED`)
Process transactions with an ineligible card	Failure (`BIN_NOT_ELIGIBLE`)
Process transactions with a valid but newly eligible card	Success

Perform test transactions using different cards.
Verify logs to confirm discount limits are correctly enforced.

6. Next Steps

Confirm if XPay’s existing API structure supports card-based tracking or if modifications are required.
Update API endpoints to include H Hash-based tracking for discount validation.
Provide merchants with documentation to configure discount limits on their end.