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

The diagram shows the happy path end to end for context. Your part is the sharing (the POST); 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. Refunds, deletions, and updates re-enter the pipeline at the matching stage.
The diagram covers 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. Accepted Card Authorization requests (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. Post-onboarding transactions (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:
stateUsed in
authorizationAuthorization requests (real-time, optional flow)
clearedHistorical sharing and daily transactions accounted for on the client’s bank account

​
Required fields

Every transaction must carry:
FieldTypeNotes
transaction_idstringBank-defined ID linking the authorization to its cleared record.
stateenumauthorization or cleared.
typeenumcard / deferred_card / order / payback / transfer.
executed_atISO 8601Authorization timestamp, including timezone.
amountfloatSigned; debit < 0, credit > 0.
currencyISO 4217EUR.
Matching quality improves significantly with channel (store / online), brand.name, brand.mcc, store.merchant_id, store.terminal_id, and scheme (Visa, MasterCard, CB, …). The full schema (including raw_label, truncated_pan, truncated_dpan, authorization_id_response, rrn, and the rest of store.*) 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.

​
Transaction updates and deletions

Card authorizations are not final. A €100 fuel pre-authorization may settle at €25. Two paths handle the update:
OperationMethodNotes
Update an amountPOST /consumers/{id}/transactions with the same transaction_idRe-runs matching against the new amount.
Update an amountPUT /consumers/{id}/transactions/{transaction_id}Equivalent to the POST-with-same-ID method.
Cancel a transactionDELETE /consumers/{id}/transactions/{transaction_id}Cancels any Reward already in flight.
Soft cancelPOST with amount: 0Equivalent to DELETE for matching purposes.
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.