Skip to main content
A Reward is what a Consumer earns when they use an 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, 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.

Reward types

Paylead generates four types of Rewards. Treat them identically on the Consumer screen: they all credit the bank account the same way.

The Reward status flow

Every Reward carries two parallel status tracks: a technical status your back-office uses for accounting and Ventilation, and a Consumer-facing status to surface in the bank app. Show the Consumer status in the UI; reconcile on the technical status. Over 95% of Rewards are created and set to VALIDATION within 10 seconds of the Consumer using the Offer, so you can surface the Reward in the app almost immediately, with no polling delay to design around.
What the Consumer sees in your app. Four values, returned in the consumer_status field.VALIDATION covers a Reward that is earned and one that is confirmed. The technical status tells those two apart.
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 id, amount, type, created_at, the originating transaction (null for a Reward without one, such as a Gift), the origin brand, and both status fields: status for the technical track and consumer_status for the Consumer-facing one. Filter the listing on type, and on the created_at__gte / created_at__lte / executed_at__gte / executed_at__lte date bounds.

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.
For real-time status updates instead of polling, subscribe to the reward.* events on the Webhooks reference. 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. It can also be claimed by several Consumer IDs on the same bank account: the co-owners of a joint account, or one person enrolled on two Paylead Programs. Without arbitration, the merchant could be billed twice and the purchase rewarded twice. Reward attribution prevents that: it runs automatically on every eligible transaction, in two stages.
1

Duplication engine

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.
2

Attribution engine

When the bank account is linked to several Consumer IDs, each of them is a candidate for the Reward. Their Rewards wait in PENDING_ATTRIBUTION for 48 hours, so that every duplicate of the purchase has arrived, then the attribution engine picks a single winner.The winner’s Reward moves on to PENDING_VALIDATION. Every other candidate’s Reward becomes NOT_ATTRIBUTED and is never paid out.

How the winner is chosen

Only candidates who were shown the Offer in their app compete. A candidate who never saw it is set aside, unless no candidate saw it, in which case they all compete. When a single candidate is left, it wins outright. Otherwise, Paylead scores each candidate on four criteria, each from 0 to 1: The four criteria combine into a global score, and the highest global score wins. On a tie, the candidate recorded first wins. Paylead does not publish how the criteria are weighted. Your support team sees each candidate’s scores on the Attributions card of the Reward in Shift: see Reading the Attributions card.

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. If a Consumer disputes a missing Cashback, your support team runs the Customer support workflow in Shift.

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 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

Pool & payout

How a validated Reward reaches the Consumer’s pool and gets paid out.

Webhooks reference

React to Reward lifecycle events in real time.

Loyalty journey

The loyalty wallet Consumers build alongside their Rewards.