> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Card BIN Promotions

QFPay Checkout supports **Card BIN Promotions** for online card payments.\
This feature allows merchants to offer discounts or promotional campaigns to specific cardholders by matching eligible Card BIN ranges.

Card BIN promotions are commonly used for:

* Bank-issued card campaigns
* Visa / Mastercard promotions
* Merchant-funded discounts
* Limited-time issuer offers
* Loyalty and co-branded campaigns

## How Card BIN Promotions Work

A Card BIN Promotion works by matching:

1. A merchant-defined `promotion_tag`
2. Eligible Card BIN ranges
3. Supported payment methods
4. Active promotion period

Only transactions meeting all conditions will qualify for the promotion.

## Key Concepts

| Term                     | Description                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Card BIN                 | The first 6–8 digits of a payment card, identifying the issuing bank and card type |
| `promotion_tag`          | Unique identifier used to associate a transaction with a promotion campaign        |
| Promotion Period         | Active start and end time for the campaign                                         |
| Eligible Payment Methods | Payment methods allowed for the promotion (e.g. Visa, Mastercard)                  |

## Supported Scenarios

Examples of supported campaigns:

* Visa cardholders receive 10% discount
* Mastercard users receive cashback
* Specific issuing bank promotions
* Merchant seasonal campaigns
* Co-branded partner promotions

## Prerequisites

Before activating a Card BIN Promotion, merchants must provide the following information to QFPay for pre-registration.

### Required Information

| Item                             | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| Promotion Period                 | Promotion start and end date/time                   |
| Card BIN List                    | List of eligible Card BIN ranges                    |
| Promotion Tag                    | Unique campaign identifier                          |
| Historical Promotion Information | (Optional) previous campaign information for review |

## Example Promotion Configuration

| Item             | Example                  |
| ---------------- | ------------------------ |
| Promotion Period | 2025-06-01 to 2025-06-30 |
| Payment Methods  | Visa, Mastercard         |
| Eligible BINs    | 412345, 512345, 622345   |
| Promotion Tag    | `PROMO12345`             |

## API Integration

To identify a transaction as part of a promotion campaign, include the `promotion_tag` in the payment request.

### Example Request

```text theme={null}
{"promotion_tag": "PROMO12345"}
```

***

## Request Parameters

| Parameter       | Type   | Required | Description                                                |
| --------------- | ------ | -------- | ---------------------------------------------------------- |
| `promotion_tag` | String | Yes      | Promotion identifier provided during campaign registration |

***

## Promotion Matching Behaviour

A transaction qualifies for the promotion only if:

* `promotion_tag` is valid
* Promotion period is active
* Card BIN matches eligible BIN list
* Payment method is supported

If any condition fails, the user may receive an eligibility error message during the payment process.

***

## Testing & Verification

Before launching the promotion:

### Test Transactions

Perform test payments using:

* Eligible Card BINs
* Non-eligible Card BINs

Verify that:

* Eligible cards successfully trigger the promotion
* Non-eligible cards do not receive promotional benefits

***

## Error Handling

Ensure your integration properly handles invalid promotion scenarios.

### Common Scenarios

| Scenario                   | Description                            |
| -------------------------- | -------------------------------------- |
| Invalid `promotion_tag`    | Promotion identifier does not exist    |
| BIN Not Eligible           | Card BIN does not match campaign rules |
| Promotion Expired          | Promotion is outside active period     |
| Unsupported Payment Method | Wallet type is not supported           |

***

## Webhook & Reporting

Merchants may use:

* QFPay merchant portal
* Transaction reports
* Merchant backend logs

to monitor promotion performance and validate eligible transactions.

It is recommended to store the `promotion_tag` in your internal order system for reconciliation purposes.

***

## Best Practices

<Tip>
  Use unique `promotion_tag` values for each campaign to simplify reconciliation and reporting.
</Tip>

<Tip>
  Test both successful and non-successful matching scenarios before production launch.
</Tip>

<Warning>
  Card BIN promotions must be pre-registered with QFPay before use.

  Transactions with unregistered promotion tags may not qualify for promotional pricing or issuer offers.
</Warning>

<Warning>
  If multiple promotions are active simultaneously, ensure the correct `promotion_tag` is sent for the intended campaign.
</Warning>

***

## Launch Process

1. Submit campaign details to QFPay
2. Complete integration testing
3. Receive confirmation from QFPay
4. Launch campaign during approved promotion period
5. Monitor transaction behaviour and promotion performance

***

## Post-Promotion Review

After the campaign ends, merchants are encouraged to:

* Review transaction performance
* Analyze conversion and usage
* Evaluate eligible BIN performance
* Share feedback for future campaigns

***

## Support

For setup assistance or campaign registration, please contact:

[technical.support@qfpay.com](mailto:technical.support@qfpay.com)