Skip to main content
A Consumer is the anchor of your Program. Every Reward, Offer eligibility check, and Webhook references one. This guide follows the Consumer lifecycle: the Consumer is created on the platform, opts in to one or both services, and then transaction sharing is set up. For the wider picture, see the User journey.

​
The Consumer lifecycle

1

Create on the platform

Create the Consumer with their consumer_id, the only required field. Service-agnostic: it registers the end user before any service opt-in.
2

Opt in to a service

Enroll the Consumer in Perks, Loyalty, or both. Each opt-in accepts that service’s terms and unlocks it.
3

Set up transaction sharing

Share the Consumer’s transaction history (typically the last 12 months), then keep pushing new transactions.
4

Add the Smart Ranking consent (Perks, optional)

On Perks, the Consumer can grant the SMART_RANKING consent to enable Offer Smart Ranking.
5

Assign Segments (Perks, optional)

On Perks, the Program Manager can assign one or more Segments to scope which Offers the Consumer sees.
6

Off-board

Deactivate the Consumer when they unsubscribe from all Paylead services.
The Consumer is created, opts in to a service, and then transaction sharing is set up. The Perks add-ons are optional; off-boarding is the terminal, irreversible state.

​
Create a Consumer on the platform

The Consumer ID you pass is the bank’s internal identifier. Paylead reuses it across every downstream call (transactions, Rewards, Webhooks). Once chosen, it cannot be changed without a full off-board and re-onboard. It is also the identifier Paylead displays to represent the Consumer across all business units (support, marketing, technical). Create the Consumer with Onboard a consumer on Paylead platform. Payload essentials
  • id: bank-internal Consumer ID. The only required field. Must be unique and stable across the Consumer’s lifetime.
  • banks: optional. The bank connections and accounts to link. One Consumer can hold several accounts under the same id, and accounts can be added later.
Once created, the Consumer exists on the platform and is ready to opt in to a service.

​
Opt in to Perks

Enroll the Consumer in the Perks service with Enroll a consumer into the perks program. Enrolling accepts the Program’s terms and makes the Consumer eligible to match Offers. Enrollment marks the start of Reward eligibility on the Consumer’s linked bank accounts. Opting in is per service. A Consumer can be enrolled in Perks, Loyalty, or both. This guide covers the Perks-side operations; the Loyalty opt-in is covered in the User journey.

​
Set up transaction sharing

Transactions are shared at the platform level and reused by whichever service the Consumer joins. Push the Consumer’s history with Create a bulk of historical transactions, then keep them current with Create a bulk of transactions. Always call the historical endpoint, even when the Consumer has no history to share: with no past transactions, send an empty payload ({ "banks": [] }) to complete this step. For how Paylead ingests and matches transactions, see Share transactions. Paylead needs time after this call to compute the Consumer’s targeted Offers and Smart Ranking. Tell the Consumer their catalog will keep improving over the next hours, rather than presenting the first catalog they see as final. Offer Smart Ranking personalizes the order of Offers from the Consumer’s transaction data. It requires the Consumer’s explicit SMART_RANKING consent. Manage it through the Perks enrollment call: pass SMART_RANKING in extra_consents to grant it, and in removed_consents to withdraw it.
Capturing consent is the bank’s responsibility. Collect the Consumer’s explicit choice in your own UI before sending it to Paylead. The Paylead call records the result; it does not replace your consent-capture flow under GDPR.

​
Assign Segments (Perks, optional)

Segments let you expose Offers to a defined audience, set by your bank’s own criteria, for example Premium, New, or Gold. A Consumer can belong to several Segments at once. Segmentation is optional. Your Paylead account manager provisions Segment definitions after a compliance check on the criteria, and the Program Manager then assigns Consumers to them in Shift or through the API, keeping targeting rules under business control.

​
Off-board a Consumer

Off-boarding stops Reward generation, revokes the Consumer’s identifier, and locks their record. Use it when the Consumer leaves your Program, closes their bank account, or exercises their right to be forgotten under GDPR. Off-board with Offboard a consumer from Paylead platform.
Off-boarding is irreversible. No new Rewards are generated. Rewards already issued are kept for accounting, but a Reward that has not been paid out yet is handled per Rewards in flight at off-boarding. Kept transactions are dissociated from the consumer_id, so a Reward can no longer be traced back to the Consumer. To re-enroll the Consumer later, use a new id.

​
Rewards in flight at off-boarding

Off-boarding closes the Consumer’s pool. What happens to a Reward that has not been paid out yet depends on the technical status it holds at that moment. A Reward still in PENDING_VALIDATION is cancelled: no Cashback and no commission are ever due. A Reward already in PAID_OUT is settled on both sides and nothing is reversed. Everything in between is decided by the payout model your Program runs.
Paylead holds the pool and pays the Consumer directly. An off-boarded Consumer can no longer be paid, so the pooled amount is forfeited and retained by Paylead. The Program Manager’s commission is unaffected and is settled as usual.
A Consumer who off-boards with a non-empty pool loses the pooled amount. Warn them in your off-boarding flow, and offer a payout before the off-board call whenever the manual threshold is reached. Check perks.can_trigger_pooled, then trigger the payout. See Triggering the payout.
With advance of fundsWithout advance of funds

​
Payout that failed before off-boarding

A payout can fail for a technical reason, for example a rejected bank transfer, and leave the amount unpaid. If the Consumer then off-boards, that amount is not forfeited straight away: Paylead keeps it available for 6 months.During that window, the Program Manager can raise a claim on behalf of its Consumer, through your Paylead account manager or on Shift, and the amount is paid. The Program Manager is the only claim channel: an off-boarded Consumer no longer exists on the Paylead side and cannot be identified directly. After 6 months without a claim, Paylead retains it.

​
Data retention after off-boarding

Off-boarding deletes all of the Consumer’s transactions, except those that produced a Reward. Paylead keeps those for 5 years, for their accounting value and to meet its legal and regulatory archiving obligations. Deletion is immediate. The 2-year retention window that applies while the Consumer is active does not carry over. The transactions that are kept are dissociated from the consumer_id. They remain as standalone records, with no link back to the Consumer. The Consumer is now off-boarded: Reward generation stops and the pool is closed.

​
What’s next

The Offer catalog

Surface partner Brands and Offers to your onboarded Consumers.

Reward lifecycle

Track the Reward lifecycle and display statuses in your app.

Webhooks reference

Subscribe to Consumer and Reward events for real-time updates.