> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/other-features/offer-engine.md).
# Offer Engine
Hyperswitch Offers lets you run card-based promotions — instant discounts tied to card BINs directly inside your existing checkout. Offers are powered by the **Offer Engine**, a dedicated service that evaluates eligibility, enforces budgets and velocity limits (like "once per card"), and tracks redemptions.
The best part: if you already use the Hyperswitch Web SDK, offers appear in your checkout **with zero frontend changes**. The SDK detects the card, fetches the matching offer, displays it as applied, and attaches it to the payment — all automatically.
### What is an Offer?
An offer is a promotion configured against card attributes — for example, *"10% off (up to $20) on all Amex credit cards, valid till month end, once per card."* When a customer enters an eligible card at checkout:
* The discount is calculated and shown to the customer before they pay
* The customer is charged the **discounted amount** at the payment processor
* Budgets and redemption counters are tracked centrally, so an offer can never be over-redeemed
* If the payment fails or is refunded, the redemption is automatically rolled back
### How does it work?
The full journey of a payment with an offer:
```mermaid
sequenceDiagram
autonumber
participant C as Customer
participant SDK as Web SDK
participant HS as Hyperswitch
participant OE as Offer Engine
participant PSP as Payment Processor
Note over C,HS: Payment created (confirm = false), SDK mounted
C->>SDK: Types card number
SDK->>HS: POST /payments/{id}/eligibility
HS->>OE: Check offers for this card (BIN, network, card fingerprint)
OE-->>HS: Best eligible offer + discount
HS-->>SDK: Offer details + discounted net amount
SDK-->>C: Shows offer as "Applied" in the card form
C->>SDK: Clicks Pay
SDK->>HS: POST /payments/{id}/confirm (with offer reference)
HS->>OE: Apply offer (locks budget & counters)
OE-->>HS: Applied ✓
HS->>PSP: Authorize discounted amount
PSP-->>HS: Success
HS-->>SDK: status: succeeded, applied_offer, net_amount
```
Key behaviours:
| Behavior | Detail |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Amounts in the payment response | `amount` stays the full order amount; `net_amount` and `amount_received` reflect the discount; `applied_offer` carries the offer details |
| Offer Engine unavailable at eligibility | Checkout continues with no offer — payments are **never blocked** by the offers system |
| Offer selected but cannot be applied at confirm | The confirm fails (error `IR_16`) — a customer is never silently charged full price after seeing a discount |
| Payment fails or is refunded | The redemption is revoked automatically in the background; budgets and per-card counters roll back |
| Once-per-card limits | Enforced via a PAN-free card fingerprint — the same card cannot reuse an offer even across different customer accounts |
### What's supported today
* **One offer per payment** — the best eligible offer is auto-applied, read-only
* **Web SDK works out of the box**; custom/headless and mobile checkouts integrate via the REST APIs
* **Automatic capture** — partial capture is not supported with offers
* **Refunds are handled** — Both full and partial refunds are supported. Any successful refund triggers background revocation of the entire applied offer. Once the revocation is processed, the offer redemption is fully reversed, restoring the offer budget and per-card usage counters.
* **Disputes are not handled today** — a chargeback does not revoke the redemption
* **Offer configuration** — creation, updates, pause/resume, and deletion are a self-serve configuration UI on control center
* **Display offers on your website** — use the Browse Offers API show available offers before a payment is created. Its optional display\_title field provides a short label for website banners or offer listings, alongside code, title, and description. Eligibility for the customer's card is checked during the payment flow.
### Getting started
{% hint style="info" %}
Offers require onboarding with the Hyperswitch team. **Reach out to your Hyperswitch point of contact** to get:
1. An **Offer Engine merchant account** created for you in sandbox
2. Your **Offer Engine API key** and **merchant ID**
3. The **Offer Engine base URL** for your environment (sandbox / production)
4. Your first offers configured (BINs, discount value, validity, velocity rules)
{% endhint %}
Then follow the setup guide for your deployment model:
* **Hyperswitch Cloud** — the Hyperswitch team enables the feature for your merchant account; you only verify and go live.
* **Self-hosted** — you add the Offer Engine configuration to your own Hyperswitch stack (config, feature flags).
### FAQs
1. **Do I need to build any UI for offers?**\
No. The Web SDK renders the offer inside the card form automatically. If you want to also reflect the discount in your own order summary (outside the SDK), subscribe to the `appliedOffersInfo` event — see How the SDK works.
2. **Can a customer choose between multiple offers?**\
Not currently. The best eligible offer is selected and auto-applied. One offer per payment.
3. **What happens to the offer if the payment fails?**\
Hyperswitch notifies the Offer Engine in the background and the redemption is revoked — the customer's card can use the offer again, and the budget is restored.
4. **Does this work for wallets / bank transfers?**\
No. Offers are currently supported for card payments only.
5. **Is the card number shared with the Offer Engine?**\
No. Only the card BIN (upto 9 digits), network metadata, and a PAN-free fingerprint (`card_alias`) are sent — never the full card number.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.hyperswitch.io/other-features/offer-engine.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
