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

# Autonomous ventilation

> For Programs that run Cashback payouts to their Consumers themselves, instead of delegating to Paylead.

<Warning>
  **Work in progress, under review.** This page is not validated yet and may contain inaccuracies. Track and record its status in the [documentation review tracker](https://www.notion.so/22a535a8f8794ec8aa19f56cbb5f749a). This banner is removed once the page is validated.
</Warning>

By default, [Paylead manages the Consumer pool and runs the payout](/program/user-journey/concepts/ventilation). This page covers the **autonomous** model, where the [Program Manager](/glossary#program-manager) distributes Cashbacks to its [Consumers](/glossary#consumer) itself.

<Info>
  Autonomous ventilation is not the default. Use it only if your Program operates its own Consumer payouts. Coordinate the setup with your Paylead representative.
</Info>

In the autonomous model, Paylead computes who owes what to whom; the Program Manager executes the payout to its Consumers. Two approaches exist. The Program Manager picks one when the [Program](/glossary#program) is created, then operates it consistently for every [Cashback](/glossary#cashback).

## How it works

```mermaid theme={null}
%%{init: {'themeVariables': {'actorBorder':'#0465ff','signalColor':'#378add'}}}%%
sequenceDiagram
  autonumber
  participant C as Consumer
  participant P as Paylead
  participant PM as Program Manager
  C->>P: Purchase reported (paid by card)
  P->>P: Match Offer, create Reward (Pending)
  P->>P: Validate Reward (Validated)
  Note over P,PM: Branch on approach
  P-->>PM: REWARD_VALIDATED (Consumer-centric)
  PM->>C: Advance Cashback to bank account
  P->>PM: Ventilation file + payment (Standard, see schedule)
  PM->>C: Distribute Cashback from received funds
```

The first three steps are identical. The split happens at payout: either the Program Manager pays the Consumer up front and Paylead reimburses later, or the Program Manager waits for Paylead's [settlement schedule](#settlement-schedule) before distributing.

## Choosing an approach

<Tabs>
  <Tab title="Consumer-centric">
    **When to use:** Programs that compete on Consumer experience and where the Program Manager can pre-fund Cashbacks.

    **How it works**

    1. Paylead validates the Reward and sets its technical status to `VALIDATED`.
    2. Paylead emits the `REWARD_VALIDATED` [Webhook](/program/user-journey/concepts/webhooks).
    3. The Program Manager immediately credits the Consumer's bank account with the Cashback amount.
    4. Paylead reimburses the Program Manager at the next monthly settlement.

    **Trade-offs**

    | Pros | Cons |
    | - | - |
    | Cashback lands in the Consumer's account within hours of validation. | The Program Manager fronts the cash for up to 30 days. |
    | Strong NPS and retention signal. | Requires reconciliation between advances paid and the monthly Paylead settlement. |
    | No CSV download step. | The Program Manager bears the risk on any post-advance refund (Paylead does not claw back Cashbacks). |
  </Tab>

  <Tab title="Standard">
    **When to use:** Programs that prefer to avoid cash advances or do not yet have automated banking flows wired to Paylead Webhooks.

    **How it works:** follows the [settlement schedule](#settlement-schedule) below.

    1. Paylead identifies validated commissions at each month end and emits a ventilation file the following month end.
    2. Two months after the file, Paylead pays the Program Manager, setting affected Rewards to `PAID_OUT`.
    3. Paylead emits the `PAYOUT_SUCCESS` Webhook.
    4. The Program Manager pulls the ventilation file via the [Paylead API](/program/user-journey/quickstart) and credits each Consumer.

    **Trade-offs**

    | Pros | Cons |
    | - | - |
    | No cash advance. The Program Manager only distributes funds it has received. | The Consumer waits until M+3 to M+4 after validation (see schedule). |
    | One batch reconciliation per month. | Lower NPS impact; the Cashback feels slower. |
    | Predictable cash flow. | Requires CSV or JSON ingestion in the Program Manager's accounting stack. |
  </Tab>
</Tabs>

## Retrieving the ventilation file

When the payout is successfully processed by Paylead's PSP, Paylead emits a `PAYOUT_SUCCESS` [Webhook](/program/user-journey/concepts/webhooks) and makes the matching ventilation file available. All affected Rewards move from `PAID_IN` to `PAID_OUT`.

### Configure the Webhook

In [Shift](/glossary#shift), set the Webhook URL under `My Account` → `Developers` → `Hooks` → `Payout success`.

The payload Paylead `POST`s to that URL carries the `payout_id` as its `resource_id`. Pass it to the ventilation endpoint below.

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

### Retrieve the file

Call `GET /programs/me/ventilation?payout_id=<payout_id>`.

<Warning>
  This endpoint must be called with your Program's access token. See [Authentication](/program/user-journey/authentication).
</Warning>

The response carries a signed `download_url` for the CSV file.

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

### CSV schema

The CSV contains **one row per Reward** included in the payout:

| Column | Description |
| - | - |
| `reward` | The Reward identifier. |
| `consumer_id` | The Program-scoped Consumer identifier. |
| `offer_reference` | The Offer that triggered the Reward. |
| `reward_rate` | The Cashback rate applied. |
| `amount` | The Reward amount. |
| `bankwire_ref` | The bank wire reference for the payout. |
| `payment_date` | When the payout was executed. |

The Program Manager aggregates rows by `consumer_id` before issuing bank transfers.

<Tip>
  The file can also be downloaded directly from [Shift](/glossary#shift): `My account` → `Ventilation`.
</Tip>

## Settlement schedule

Payout in the Standard approach follows a fixed monthly cadence:

1. **End of each month:** Paylead identifies the commissions generated and **validated** by the Program's Consumers during that month.
2. **End of the following month:** Paylead emits a ventilation file detailing the validated commission per Consumer (`consumer_id` and total amount).
3. **End of the month two months after that:** Paylead pays out the full set of commissions. The payment may be split in two: one for the Program Manager's own commission, one for the commissions attached to a Reward.

<Note>
  **Net delay.** Once a Reward is `VALIDATED`, you wait until that month end to be counted, the next month end to appear in the ventilation file, then two more months to receive the funds: roughly **M+3 to M+4** depending on when validation occurred.
</Note>

<Warning>
  Changing the Ventilation approach on a live Program does not retroactively re-allocate Rewards already paid out. Coordinate the switch with your Paylead representative and pick a clean month boundary.
</Warning>

## Recommendations

To absorb the M+3/M+4 delay without hurting the Consumer experience:

* **Advance funds on validation.** Use the Consumer-centric approach: credit the Cashback as soon as it reaches `VALIDATED`, then reconcile against Paylead's later payment.
* **Use a pool with a minimum payout threshold.** Holding Cashback in a [pool](/glossary#pool) and paying out only past a small threshold (**€5 is enough**) reduces the working-capital need and maximizes marketing value: the Consumer watches their pool grow and is paid in meaningful increments.

## No clawback

<Note>
  **As soon as a Cashback reaches `VALIDATED`, it can no longer be cancelled or modified.** Refunds, disputes, and cancellations must happen **before** validation. Once validated (and a fortiori once included in a Ventilation file) the amount is definitively owed to the Consumer.
</Note>

## Edge cases

<AccordionGroup>
  <Accordion title="The Consumer leaves the Program before payout">
    A Consumer may unsubscribe between Reward validation and ventilation. Paylead drops them from the ventilation file because their account link is no longer authoritative.

    The Program Manager handles this case in one of two ways:

    * Honor the Cashback from internal records (recommended for Consumer-centric Programs that already advanced the funds).
    * Document in the Program's terms and conditions that unsubscribing forfeits the Consumer's pending pool.
  </Accordion>

  <Accordion title="The transaction is refunded before the Reward is validated">
    Paylead reconciles the refund against the original transaction and cancels the Reward during the refund window, before it reaches `VALIDATED`. Once validated, the Cashback is locked, even if a later refund hits the bank account. Programs running the Consumer-centric approach may have already advanced the Cashback. Recovering it on a pre-validation refund is the Program Manager's responsibility, based on Program policy.
  </Accordion>

  <Accordion title="Multiple Rewards on one Consumer in the same payout">
    The ventilation file lists **one row per Reward**, grouped together by `consumer_id`. The Program Manager aggregates rows before issuing a single bank transfer per Consumer to reduce transfer fees.
  </Accordion>

  <Accordion title="Currency">
    All Ventilation files are denominated in **EUR**. Paylead does not support multi-currency Programs.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Ventilation (default)" icon="hand-coins" href="/program/user-journey/concepts/ventilation">
    The default model, where Paylead manages the Consumer pool and runs the payout.
  </Card>

  <Card title="Webhooks" icon="zap" href="/program/user-journey/concepts/webhooks">
    Subscribe to `REWARD_VALIDATED` and `PAYOUT_SUCCESS` to drive autonomous payouts in real time.
  </Card>
</CardGroup>