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

# Use an offer

> The two ways a Consumer uses an Offer: a Cashback Offer rewards automatically from a shared transaction, a Voucher Offer is bought up front through the Paylead API.

A [Consumer](/glossary#consumer) uses an [Offer](/glossary#offer) in one of two ways, depending on its type. A **Cashback Offer** rewards them automatically when a transaction matches the Offer's terms. A **Voucher Offer** is activated by purchasing a Voucher. This page covers both flows. For what happens to the [Reward](/glossary#reward) once it exists, see [Reward lifecycle](/program/user-journey/guides/reward-lifecycle).

## Cashback offers (automatic)

A Cashback Offer needs no action from the Consumer. Once they are enrolled in [Perks](/glossary#perks), every eligible transaction the bank shares with Paylead is matched against the Consumer's active Offers, and a match creates a [Cashback](/glossary#cashback) Reward automatically.

<Steps>
  <Step title="The Consumer is enrolled in Perks">
    Onboarding and consent put the Consumer into the Perks service. From that point their transactions are eligible for matching.
  </Step>

  <Step title="The bank shares the transaction">
    The bank pushes the transaction to Paylead through the [Share transactions](/program/user-journey/concepts/transaction-lifecycle) flow. This is a platform-level task, independent of any single Offer.
  </Step>

  <Step title="Paylead matches it against active Offers">
    Paylead checks the transaction against the Consumer's active Offers (Brand, amount, channel, validity, targeting).
  </Step>

  <Step title="A Reward is created">
    On a match, Paylead creates a Reward. Over 95% of Rewards reach the `Pending` status within 10 seconds of the transaction being shared.
  </Step>
</Steps>

<Note>
  There is nothing to render for the act of earning itself: the Consumer does not tap or confirm anything. Your job is to surface the resulting Reward. See [Reward lifecycle](/program/user-journey/guides/reward-lifecycle) for the status tracks and the list and detail endpoints.
</Note>

## Voucher offers (bought up front)

<Warning>
  The Voucher API is in **beta**. The endpoints and payloads below describe the main flow; the exact fields are still subject to change.
</Warning>

A [Voucher](/glossary#voucher) Offer lets the Consumer buy a prepaid value redeemable at a participating [Brand](/glossary#brand). Unlike a Cashback Offer, the Consumer actively places an order and pays for it. The whole flow runs through the Paylead API: Voucher order payment no longer depends on a WebApp.

### The purchase flow

<Steps>
  <Step title="Browse Voucher Offers">
    Voucher Offers are the `VOUCHER` entries in the catalog. Surface them like any other Offer (see [The Offer catalog](/program/user-journey/guides/work-with-offers)).
  </Step>

  <Step title="Create a Voucher Order">
    Place an order on the chosen Offer with `POST /offers/{offer_id}/vouchers/orders`. The body carries one or more `amount_selections`, each an `amount` and a `quantity`. The order starts in `CREATED`.

    ```json theme={null}
    {
      "amount_selections": [
        { "amount": 50, "quantity": 1 }
      ]
    }
    ```
  </Step>

  <Step title="Pay the order">
    Two payment models are available. Pick the one that matches your integration.

    <Tabs>
      <Tab title="Paylead-hosted payment">
        Paylead processes the payment page.

        1. Call `POST /vouchers/orders/{order_id}/payments/webview` to get a `redirect_url`.
        2. Redirect the Consumer to that payment webview.
        3. When the Consumer returns, call `POST /vouchers/orders/{order_id}/payments/confirm`.
      </Tab>

      <Tab title="Delegated payment">
        The bank charges the Consumer on its own platform, then notifies Paylead with `POST /vouchers/orders/{order_id}/payments` once the payment has succeeded.
      </Tab>
    </Tabs>
  </Step>

  <Step title="The order completes">
    Once payment is confirmed, the order moves to `READY` and the Vouchers are issued. A failed or abandoned payment leaves the order in `PAYMENT_FAILED` or `CANCELLED`.
  </Step>

  <Step title="Deliver the Vouchers">
    List the Consumer's Vouchers with `GET /vouchers`, fetch one with `GET /vouchers/{voucher_id}`, and download its file with `GET /vouchers/{voucher_id}/pdf`. Display the code, PIN, validity date, and Brand.
  </Step>
</Steps>

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

### Order states

| Status           | What it means                                     |
| ---------------- | ------------------------------------------------- |
| `CREATED`        | Order placed, payment not yet completed.          |
| `CONFIRMED`      | Payment confirmed, Vouchers being issued.         |
| `READY`          | Vouchers issued and ready to use.                 |
| `PAYMENT_FAILED` | Payment did not go through. No Voucher is issued. |
| `CANCELLED`      | Order cancelled before completion.                |

### What a Voucher carries

| Field                        | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `id`                         | Unique identifier of the Voucher.                               |
| `order_id`                   | The order the Voucher was issued from.                          |
| `status`                     | The order status the Voucher reflects.                          |
| `brand`                      | The Brand the Voucher is redeemable at (identity, logo, color). |
| `amount`                     | Face value of the Voucher.                                      |
| `valid_until`                | Expiry date.                                                    |
| `pin_code_1`, `pin_code_2`   | PIN codes, when the Brand uses them.                            |
| `card_number`                | Voucher or gift card number.                                    |
| `card_url`                   | Link to the Brand's redemption page, when provided.             |
| `pdf_id`                     | Identifier of the downloadable Voucher file.                    |
| `archived_at`, `refunded_at` | When the Voucher was archived or refunded, if applicable.       |

<Tip>
  Let the Consumer tidy their wallet by archiving used or expired Vouchers with `POST /vouchers/{voucher_id}/archive`, and restore them with `POST /vouchers/{voucher_id}/unarchive`.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="Reward lifecycle" icon="refresh-cw" href="/program/user-journey/guides/reward-lifecycle">
    Track and display the Rewards a Cashback Offer generates.
  </Card>

  <Card title="Pool & payout" icon="hand-coins" href="/program/user-journey/concepts/ventilation">
    How a validated Reward reaches the Consumer's pool and gets paid out.
  </Card>

  <Card title="Webhooks reference" icon="zap" href="/program/user-journey/concepts/webhooks">
    React to Reward and Voucher events in real time.
  </Card>
</CardGroup>