> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Share transactions

> How the bank shares Consumer transactions with Paylead: the platform-level feed every service builds on.

Sharing the [Consumer](/glossary#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](/glossary#offer), creating [Rewards](/glossary#reward)) is downstream and summarized at the end.

## End-to-end flow

```mermaid theme={null}
%%{init: {'themeVariables': {'actorBorder':'#0465ff','signalColor':'#378add'}}}%%
sequenceDiagram
  autonumber
  participant C as Consumer
  participant B as Brand
  participant PM as Program (bank or aggregator)
  participant P as Paylead
  C->>B: Pays with linked card
  B->>PM: Authorization settles
  PM->>P: POST /consumers/{id}/transactions
  P->>P: Transaction enters bucket
  P->>P: Process bank connection + accounts
  P->>P: Transaction Worker matches active Offers
  alt Eligible
    P->>P: Create Reward (PENDING_VALIDATION)
    P-->>PM: reward_created Webhook
    P->>P: Validate after refund window
    P-->>PM: reward_validated Webhook
  else No match
    P->>P: Keep for analytics, no Reward, no Webhook
  end
```

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](#what-paylead-does-next). The [Program Manager](/glossary#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.

<Note>
  The diagram covers **card** transactions. Direct debit and bank transfer payments are also in scope: Paylead needs them to operate its services.
</Note>

## How sharing works

<Steps>
  <Step title="The Program shares transactions with Paylead">
    The [Program Manager](/glossary#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](/glossary#consumer)'s past **12 months** of settled / compensation transactions. Triggered in two cases:

       * At enrollment in the [Perks](/glossary#perks) service, to determine eligibility and seed [Offer Smart Ranking](/glossary#offer-smart-ranking) from real purchase habits.
       * In the [Loyalty](/glossary#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](/program/user-journey/guides/animate-your-program).
    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`.

    <Note>
      **Push vs Pull.** By default, the Program pushes through the Transaction Hub. The [Transaction Fetch Hub](/glossary#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. {/* TODO Gaspar: document the Fetch Hub setup and per-bank scoping once defined. */}
    </Note>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## What Paylead does next

<Info>
  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](/glossary#perks) guides.
</Info>

Once transactions are ingested, the Perks service consumes them:

* **Matching**: the Transaction Worker checks each transaction against the Consumer's active [Offers](/glossary#offer): the [Brand](/glossary#brand) is in the Offer's eligible Brands or [Stores](/glossary#stores), the date is inside the validity period, the Consumer is in any required [Segment](/glossary#segment), and the budget cap is not reached. No match → the transaction is kept for analytics, with no [Reward](/glossary#reward).
* **Attribution**: when the same transaction arrives from several sources (for example, the bank and an account aggregator), the [Reward attribution](/program/user-journey/guides/reward-lifecycle#reward-attribution) engine issues a single Reward and drops the duplicates.
* **Notification**: Paylead emits `reward_created` ([Webhook](/program/user-journey/concepts/webhooks); `PENDING_VALIDATION` / `Pending`), then `reward_validated` after the refund window. From there, [Ventilation](/program/user-journey/concepts/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:

| `state`         | Used in                                                                              |
| --------------- | ------------------------------------------------------------------------------------ |
| `authorization` | Authorization requests (real-time, optional flow)                                    |
| `cleared`       | Historical sharing and daily transactions accounted for on the client's bank account |

### Required fields

Every transaction must carry:

| Field            | Type     | Notes                                                                |
| ---------------- | -------- | -------------------------------------------------------------------- |
| `transaction_id` | string   | Bank-defined ID linking the `authorization` to its `cleared` record. |
| `state`          | enum     | `authorization` or `cleared`.                                        |
| `type`           | enum     | `card` / `deferred_card` / `order` / `payback` / `transfer`.         |
| `executed_at`    | ISO 8601 | Authorization timestamp, including timezone.                         |
| `amount`         | float    | Signed; debit `< 0`, credit `> 0`.                                   |
| `currency`       | ISO 4217 | `EUR`.                                                               |

### Recommended optional fields

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](/program/user-journey/quickstart).

<Tip>
  **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.
</Tip>

## Transaction updates and deletions

Card authorizations are not final. A €100 fuel pre-authorization may settle at €25. Two paths handle the update:

| Operation            | Method                                                             | Notes                                         |
| -------------------- | ------------------------------------------------------------------ | --------------------------------------------- |
| Update an amount     | `POST /consumers/{id}/transactions` with the same `transaction_id` | Re-runs matching against the new amount.      |
| Update an amount     | `PUT /consumers/{id}/transactions/{transaction_id}`                | Equivalent to the POST-with-same-ID method.   |
| Cancel a transaction | `DELETE /consumers/{id}/transactions/{transaction_id}`             | Cancels any Reward already in flight.         |
| Soft cancel          | `POST` with `amount: 0`                                            | Equivalent 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

<Note>
  **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.
</Note>

<Warning>
  **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.
</Warning>

<Note>
  **Currency.** All amounts handled by Paylead (transactions, Rewards, ventilation files) are denominated in **EUR**. Multi-currency Programs are not supported.
</Note>

<Tip>
  **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.
</Tip>

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

<Note>
  Transactions older than 12 months are accepted (used to enrich Smart Ranking and analytics) but never generate Rewards. Only fresh transactions trigger matching.
</Note>

## What's next

<CardGroup cols={2}>
  <Card title="Reward attribution" icon="scale" href="/program/user-journey/guides/reward-lifecycle#reward-attribution">
    Understand how Paylead picks one Program when several sources report the same transaction.
  </Card>

  <Card title="Pool & payout" icon="hand-coins" href="/program/user-journey/concepts/ventilation">
    Follow the validated Reward through to the Consumer's bank account.
  </Card>
</CardGroup>