Skip to main content
Sharing the Consumer’s bank transactions is a platform-level task, independent of any service: the bank pushes transactions once, and whichever service the Consumer joined consumes them. This page covers how to share transactions and how Paylead processes them. What a service then does with them (matching Offers, creating Rewards) is downstream and summarized at the end.

​
End-to-end flow

Sharing happens in three moments across the Consumer’s life with the service. Your part is the sharing (the API calls); everything from matching onward is downstream service behavior, summarized under What Paylead does next. The Program Manager (the bank itself, or an aggregator acting on its behalf) is the single entity exchanging data with Paylead.

​
Enrollment and historical sharing

When the Consumer joins a Paylead service, the Program creates the Consumer, then pushes the past 12 months of settled transactions in one shot to seed eligibility and Offer Smart Ranking.

​
Real-time authorization (optional)

At each authorized payment, the Program may send the transaction individually with state: authorization. This flow is optional: it lets Paylead emit reward_created within a second of the purchase, which powers live animations.

​
Settlement (mandatory)

Once the transaction is cleared on the bank account, the Program sends it with state: cleared. This flow is mandatory whether or not the authorization was shared: the cleared record is what Paylead matches and turns into a confirmed Reward.
These diagrams cover card transactions. Direct debit and bank transfer payments are also in scope: Paylead needs them to operate its services.

​
How sharing works

1

The Program shares transactions with Paylead

The Program Manager (the bank, or an aggregator acting on its behalf) shares transactions with Paylead through three distinct flows, each with its own purpose:
  1. Historical sharing: a one-shot POST of the Consumer’s past 12 months of settled / compensation transactions. Triggered in two cases:
    • At enrollment in the Perks service, to determine eligibility and seed Offer Smart Ranking from real purchase habits.
    • In the Loyalty domain, if the Consumer consents to sort partner loyalty programs by their purchase habits.
    Send this call even when the Consumer has no history. With no past transactions, the payload carries an empty banks array ({ "banks": [] }).
  2. Real-time sharing (optional, recommended): transactions sent individually in real time as the bank authorizes the payment. Paylead can then emit reward_created within a second of an eligible purchase, which is the foundation of live “your Cashback is on its way” animations.
  3. Daily sharing (mandatory): the daily batch of newly settled transactions (cleared card transactions, direct debits, and bank transfers), transferred to Paylead every day.
The real-time and daily flows hit POST /consumers/{consumer_id}/transactions. Historical sharing uses its own endpoint, POST /consumers/{consumer_id}/transactions/history.
Push vs Pull. By default, the Program pushes through the Transaction Hub. The Transaction Fetch Hub is the alternative where Paylead pulls: a bespoke, per-bank service scoped during the build phase of the integration. The three flows above apply in either mechanism.
2

Paylead buckets and processes

Each source pushes into a dedicated transaction bucket: a pool of bank connections grouping the accounts each Consumer has linked.Processing a bucket happens in three sub-steps:
  1. Bank connections are resolved: the bank ID, user ID, and sync status.
  2. Bank accounts linked to each connection are checked.
  3. Transactions are persisted, then forwarded to the Transaction Worker queue.

​
What Paylead does next

Matching, Rewards, and attribution are downstream of sharing and service-specific: you do not implement them. They are summarized here for context; the detail lives in the Perks guides.
Once transactions are ingested, the Perks service consumes them:
  • Matching: the Transaction Worker checks each transaction against the Consumer’s active Offers: the Brand is in the Offer’s eligible Brands or Stores, the date is inside the validity period, the Consumer is in any required Segment, and the budget cap is not reached. No match → the transaction is kept for analytics, with no Reward.
  • Attribution: when the same transaction arrives from several sources (for example, the bank and an account aggregator), the Reward attribution engine issues a single Reward and drops the duplicates.
  • Notification: Paylead emits reward_created (Webhook; PENDING_VALIDATION / Pending), then reward_validated after the refund window. From there, Ventilation takes over.

​
Transaction payload

The real-time and daily flows use POST /consumers/{consumer_id}/transactions, while historical sharing uses POST /consumers/{consumer_id}/transactions/history. Two payload conventions matter for the rest of this page:
  • Sign. Debits are negative, credits are positive. A €10.40 purchase is amount: -10.40; a refund landing back on the card is a positive amount on a new transaction.
  • Unit. Amounts are floats in EUR (for example -10.40), not cents.

​
state maps to the flow

The state field on each transaction tells Paylead where it sits in its life and which of the three flows it belongs to:

​
Required fields

Every transaction must carry: None of these are required, but matching quality improves significantly with each one you add: The full schema is in the API reference.
Send as many optional fields as you can. The richer the data you share, the more Paylead can do with it: a larger Offer catalog surfaced to your Consumers, higher Cashback rates made available, and fewer support requests reaching the Program. Some Offers and services are conditioned on sharing specific optional fields.

​
Network field mapping

For teams building against acquiring or interbank feeds, these fields map to standard network references:

​
Transaction updates and deletions

Card authorizations are not final. A €100 fuel pre-authorization may settle at €25. You update or cancel a transaction by re-sending it with the same id. Two methods are equivalent and both handle every operation below:
  • POST /consumers/{consumer_id}/transactions (bulk), carrying the transaction with its original id.
  • PUT /consumers/{consumer_id}/transactions/{transaction_id}.
A dedicated DELETE /consumers/{consumer_id}/transactions/{transaction_id} is also available and cancels any Reward already in flight. Refunds use a different signal: the bank shares a positive-amount card transaction referencing the same Brand. Paylead reconciles the refund against the original debit and adjusts or cancels the Reward.

​
Timing

Latency depends on the flow. With authorization-time sharing enabled, Paylead emits reward_created within a second of an eligible purchase made with a payment card. Programs running only the daily compensation flow see the Reward appear once the day’s batch is processed. Contact your Paylead account manager for the timing applicable to your Program before exposing the flow to Consumers.
Sandbox is not production. Sandbox transactions process in seconds, but real Programs run against batched aggregator feeds and end-to-end latency is materially longer. Always deploy a beta in production before going live to verify your transaction-sharing pipeline.
Currency. All amounts handled by Paylead (transactions, Rewards, ventilation files) are denominated in EUR. Multi-currency Programs are not supported.
The Consumer ID is the linchpin. Every transaction is scoped to a consumer_id. A mismatched or missing Consumer ID means the transaction is orphaned: no bucket, no match, no Reward. Validate Consumer creation before turning on transaction sharing.

​
Data quality matters

The Brand identifier (often called merchant_id) and the executed_at timestamp drive matching accuracy. Garbage in, garbage out:
  • A wrong merchant_id produces no match even when the Consumer shopped at an eligible Brand.
  • A wrong executed_at may push the transaction outside the Offer’s validity period.
Transactions older than 12 months are accepted (used to enrich Smart Ranking and analytics) but never generate Rewards. Only fresh transactions trigger matching.

​
What’s next

Reward attribution

Understand how Paylead picks one Program when several sources report the same transaction.

Pool & payout

Follow the validated Reward through to the Consumer’s bank account.