> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Drive Loyalty with Cashback Campaigns

> Configure campaigns, enrol users, deliver real-time cashback on qualifying payments, and manage withdrawals.

## What you’ll build

Hello Clever’s cashback lets you reward customers with real-time cash back on qualifying payments. You configure campaigns (tiers, schedule, eligible payment methods, caps), activate a cashback account for each user, deliver cashback when they transact, and let them withdraw their accumulated balance. Rewards are distributed automatically on qualifying transactions: instantly for bank payments, and on settlement for card payments.

The **Cashback APIs (v2)** expose the endpoints to read campaigns, manage user accounts, and move cashback.

## Prerequisites

* Merchant account and `app-id` / `secret-key`.
* Sandbox `https://api.cleverhub.co`; production `https://api-merchant.helloclever.co`.
* Cashback rates/campaigns can also be set up in the Merchant Portal.

## The endpoints

| Endpoint                                                       | Purpose                                                                                                                                                                    |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Get Cashback Campaign List** (`GET /v2/cashbacks/campaigns`) | Paginated list of campaigns, filterable by status (`active`, `scheduled`, `inactive`). Includes tiers, schedule, applicable payment methods, and maximum cashback amounts. |
| **Get Campaign Configurations**                                | Detailed configuration for campaigns.                                                                                                                                      |
| **Activate User’s Cashback Account**                           | Enable a customer to earn/hold cashback.                                                                                                                                   |
| **Initiate Cashback Delivery**                                 | Pay cashback to a user for a qualifying event.                                                                                                                             |
| **Initiate Cashback Withdrawal**                               | Move a user’s accumulated cashback out to their account.                                                                                                                   |
| **Get User List**                                              | List users enrolled in cashback.                                                                                                                                           |

## Build the loyalty flow

<Steps>
  <Step title="Model your campaign">
    Decide the campaign shape before writing code:

    * **Tiers**: e.g. 2% up to \$50, 5% above.
    * **Schedule**: duration and frequency (seasonal promo, daily offer, single-day event).
    * **Eligible payment methods**: which rails qualify (bank vs card behave differently on timing).
    * **Caps**: maximum cashback per transaction / campaign.

    Create/configure campaigns in the Merchant Portal, then read them back via **Get Cashback Campaign List** / **Get Campaign Configurations** to drive your UI and eligibility logic.
  </Step>

  <Step title="Enrol the customer">
    Call **Activate User’s Cashback Account** so the user can receive and hold cashback. Do this at signup or first eligible checkout. Use **Get User List** to check enrolment state and reconcile your own records.
  </Step>

  <Step title="Deliver cashback on a qualifying transaction">
    When a customer completes a qualifying payment, call **Initiate Cashback Delivery** to credit their cashback. For bank/real-time payments this can be granted immediately; for card payments, cashback applies once the underlying payment settles.

    <Tip>
      If you use the AUD Payment Gateway, individual line items carry an `enable_cashback` flag and the payment payload returns `cashback_amount`. Cashback earned through checkout is reflected there; use the Cashback API to manage the standalone account, delivery, and withdrawal lifecycle.
    </Tip>
  </Step>

  <Step title="Let customers withdraw">
    Call **Initiate Cashback Withdrawal** to disburse a user’s accumulated cashback to their nominated account. Surface the current balance and withdrawal status in your app.
  </Step>
</Steps>

## Design considerations

<AccordionGroup>
  <Accordion title="Timing differs by rail" icon="clock">
    Communicate to customers that card cashback lands on settlement, not instantly, to set expectations.
  </Accordion>

  <Accordion title="Respect caps and tiers server-side" icon="shield-check">
    Read campaign configuration and enforce eligibility on your backend rather than trusting the client.
  </Accordion>

  <Accordion title="Reconcile regularly" icon="rotate">
    Use the list endpoints to keep your ledger aligned with Hello Clever’s.
  </Accordion>
</AccordionGroup>


## Related topics

- [Get Started with Hello Clever](/getting-started/overview.md)
- [Hello Clever Developer Documentation](/index.md)
- [Instant Cashback for Your Customers](/services/instant-cashback.md)