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.
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
A Card BIN Promotion works by matching:
- A merchant-defined
promotion_tag
- Eligible Card BIN ranges
- Supported payment methods
- 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.
| 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 |
| 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
{"promotion_tag": "PROMO12345"}
Request Parameters
| Parameter | Type | Required | Description |
|---|
promotion_tag | String | Yes | Promotion identifier provided during campaign registration |
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
Use unique promotion_tag values for each campaign to simplify reconciliation and reporting.
Test both successful and non-successful matching scenarios before production launch.
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.
If multiple promotions are active simultaneously, ensure the correct promotion_tag is sent for the intended campaign.
Launch Process
- Submit campaign details to QFPay
- Complete integration testing
- Receive confirmation from QFPay
- Launch campaign during approved promotion period
- 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
