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 toVALIDATION 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.
- Consumer status
- Technical status
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.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.
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.
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.
REWARD_CREATED Webhook fires. If a Consumer disputes a missing Cashback, your support team runs the Customer support workflow in Shift.
FAQ
How long does a Reward stay in VALIDATION before it is confirmed?
How long does a Reward stay in VALIDATION before it is confirmed?
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.What happens to a Reward when the underlying transaction is refunded?
What happens to a Reward when the underlying transaction is refunded?
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.Can a single transaction generate multiple Rewards?
Can a single transaction generate multiple Rewards?
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.