> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt
> Use this file to discover all available pages before exploring further.
# Reward lifecycle
> The Reward lifecycle: types, the two status tracks, listing and retrieving Rewards through the Paylead API, and how attribution guarantees one Reward per purchase.
A [Reward](/glossary#reward) is what a [Consumer](/glossary#consumer) earns when they use an [Offer](/glossary#offer). This page covers the Reward lifecycle: the types Paylead generates, the two status tracks, how to list and retrieve Rewards through the [Paylead API](/program/user-journey/quickstart), and how attribution guarantees one Reward per purchase. For how a Consumer earns a Cashback or buys a Voucher in the first place, see [Use an offer](/program/user-journey/guides/use-an-offer).
## Reward types
Paylead generates four types of Rewards. Treat them identically on the Consumer screen: they all credit the bank account the same way.
| Type | Source |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `ALO_CASHBACK` | A bank transaction matched an Offer. Detected via [ALO](/glossary#alo-account-linked-offer). |
| `LBS_CASHBACK` | A local merchant Campaign via [LBS](/glossary#lbs-local-business-solution). |
| `GIFT` | A welcome bonus, loyalty incentive, or promotional one-off. |
| `VOUCHER_CASHBACK` | A Voucher converted as a cashback |
***
## The Reward status flow
Every Reward carries **two parallel status tracks**: a **technical** status your back-office uses for accounting and [Ventilation](/glossary#ventilation), and a **Consumer-facing** status to surface in the bank app. Show the Consumer status in the UI; reconcile on the technical status.
**Rewards are near-instant.** Over 95% of Rewards are created and set to `Pending` within 10 seconds of the Consumer using the Offer. You can surface the Reward in the app almost immediately, no polling delay to design around.
What the Consumer sees in your app (five values).
| Status | What it means | Display tip |
| ----------- | ------------------------------------------------------- | ---------------------------------------- |
| `Pending` | Reward earned, not yet confirmed. | "Earning: confirms within 30 days". |
| `Validated` | Reward confirmed; payout guaranteed. | "Confirmed". |
| `Pool` | Reward sitting in the Consumer's pool, awaiting payout. | "Confirmed: paid out next month". |
| `Paid` | Reward credited to the Consumer's bank account. | Show the credit date and amount. |
| `Cancelled` | Underlying transaction refunded, disputed, or voided. | Show with reason, archive after 30 days. |
What your back-office systems track (seven values).
| Status | What it means |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `PENDING_ATTRIBUTION` | Awaiting the attribution decision: which Consumer owns the purchase. See [Reward attribution](#reward-attribution) below. |
| `NOT_ATTRIBUTED` | Discarded as a duplicate of the same purchase; never paid out. |
| `PENDING_VALIDATION` | Attributed, inside the refund window (typically 30 days). |
| `VALIDATED` | Paylead guarantees the payout. |
| `PAID_IN` | Funds received from the merchant. |
| `PAID_OUT` | Funds disbursed via the Ventilation pipeline. |
| `CANCELLED` | Reward cancelled (refund, dispute) before validation. |
As soon as a Reward is visible to the Consumer (`Pending`), display it. Don't wait for validation: the early signal is what drives engagement. The two tracks are decoupled: the Consumer status follows UX moments, not the exact accounting state.
***
## List rewards
Return every Reward generated for a specific Consumer.
**Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
Each item in the response includes the amount, status, origin Brand, and a `links.detail` URL for the full payload.
## Get reward details
Fetch the full payload for a single Reward. Show it on the detail screen with the estimated payout date, the originating transaction, and the source Offer.
**Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
Need real-time status updates instead of polling? Subscribe to the `reward.*` events on the [Webhooks reference](/program/user-journey/concepts/webhooks). Paylead pushes a notification on every status transition so you can drive in-app notifications, CRM updates, and accounting reconciliation without batch jobs.
## Reward attribution
A single Consumer purchase can land in Paylead from multiple sources at the same time: the bank's own feed, an account aggregator. Without arbitration, the merchant could be billed twice and the Consumer rewarded twice. [Reward attribution](/glossary#reward-attribution) prevents that: it runs automatically on every eligible transaction, in two stages.
```mermaid theme={null}
flowchart LR
T1[Transaction A - Bank] --> D{Duplication engine}
T2[Transaction B - Aggregator] --> D
D -->|Same purchase| A{Attribution engine}
D -->|Distinct purchases| R0[Reward each]
A -->|Winner| R1[One Reward issued]
A -->|Losers| R2[Not attributed Reward]
classDef neutral fill:#f1efe8,stroke:#888780,color:#2c2c2a
classDef decision fill:#ffffff,stroke:#888780,color:#2c2c2a
classDef success fill:#eaf3de,stroke:#3b6d11,color:#173404
classDef danger fill:#fcebeb,stroke:#a32d2d,color:#501313
class T1,T2 neutral
class D,A decision
class R0,R1 success
class R2 danger
```
The duplication engine inspects incoming transactions against a battery of signals (IBAN, issuing bank, amount, executed-at timestamp, Brand identifier, and sequence proximity) to detect when several records describe the same underlying purchase.
When two or more transactions resolve to the same purchase, only one is allowed to generate a Reward. The others are flagged as duplicates and excluded.
If the deduplicated transaction is eligible to be rewarded under more than one Program, the attribution engine picks the winning Program based on a scoring system. Only the winner issues a Reward.
### When no Reward is attributed
Not every eligible transaction generates a Reward. Common reasons:
* The Offer's budget cap was reached before the transaction settled.
* The transaction was cancelled or refunded before validation.
* A duplicate was processed and the current record lost the attribution round.
Paylead drops the un-attributed transaction. No `reward_created` Webhook fires. Use Consumer detail on Shift if a Consumer disputes a missing Cashback.
***
## FAQ
Up to 30 days, matching the refund window of most card networks. The exact validation date is exposed as `executed_at` plus the brand's validation delay.
If the refund occurs before validation, the Reward transitions to `CANCELLED` automatically. Once a Reward reaches `VALIDATED`, it can no longer be cancelled or modified: a later refund is **not** clawed back. For disputes, use the form on Shift; there is no public dispute API endpoint.
No. Paylead's [Reward attribution](#reward-attribution) mechanism guarantees exactly one Reward per qualifying purchase, even when the same transaction is reported by multiple sources (bank feed plus aggregator).
***
## What's next
How a validated Reward reaches the Consumer's pool and gets paid out.
React to Reward lifecycle events in real time.
The loyalty wallet Consumers build alongside their Rewards.