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

# Sessions

export const ThemeImage = ({img_name, alt, width, height}) => {
  return <>
            <img width={width} height={height} src={`/images/light/${img_name}`} alt={alt} className="block dark:hidden" />
            <img width={width} height={height} src={`/images/dark/${img_name}`} alt={alt} className="hidden dark:block" />
        </>;
};

> Group multiple vouchers in a session for multi-payment flows.

A session groups multiple vouchers together under a single context. Each voucher within the session is treated **independently** — with its own code, lifecycle, and settlement — but they share the same session for tracking and coordination.

Each voucher in a session has the same capabilities as a standalone payment: SIMPLE vouchers support FX, network auto-detection, and straightforward token transfers.

## Why use sessions?

* **Multi-payment checkout**: A customer pays for multiple items as separate transactions but tracked together.
* **Split payments**: Pay different recipients from a single user session.
* **Multi-currency**: Accept EURC for one item and USDC for another, both in the same session.

## Flow overview

1. **Payer** opens their wallet, authenticates, and opens a context — shares the context code with you.
2. **You authenticate** using the context code.
3. **You open a session** using the context code.
4. **Payer** joins the session in their wallet.
5. **You reserve and redeem** each voucher independently within the session.
6. **Payer** resolves each voucher independently in their wallet.
7. **You close** the session when done.

## Example: Two payments (EURC + USDC) in one session

The payer has already opened their wallet and shared a context code with you.

### 1. Authenticate and open a session

```
POST /api/v1/auth/sign-in

{
    "type": "resource",
    "data": {
        "resource": "voucher::context::code::A1B2C3"
    }
}
```

```
POST /api/v1/vouchers/sessions/session-open
Authorization: Bearer <payee_token>

{
    "code": "A1B2C3"
}
```

Response: `{ "id": "ses_xyz", "code": "D4E5F6", "status": "OPEN" }`

The payer joins the session in their wallet.

### 2. Reserve and redeem first voucher (EURC)

```
POST /api/v1/vouchers/sessions/ses_xyz/reserve-voucher
Authorization: Bearer <payee_token>

{}
```

Response: `{ "id": "vch_482916", "code": "482916", "status": "RESERVED" }`

```
POST /api/v1/vouchers/vch_482916/redeem-voucher
Authorization: Bearer <payee_token>

{
    "expectedPayment": {
        "network": "polygon",
        "currency": "EURC",
        "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
        "amount": "100",
        "wallet": {
            "address": "0xYourWalletAddress"
        }
    }
}
```

### 3. Reserve and redeem second voucher (USDC)

```
POST /api/v1/vouchers/sessions/ses_xyz/reserve-voucher
Authorization: Bearer <payee_token>

{}
```

Response: `{ "id": "vch_739104", "code": "739104", "status": "RESERVED" }`

```
POST /api/v1/vouchers/vch_739104/redeem-voucher
Authorization: Bearer <payee_token>

{
    "expectedPayment": {
        "network": "polygon",
        "currency": "USDC",
        "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
        "amount": "50",
        "wallet": {
            "address": "0xYourWalletAddress"
        }
    }
}
```

### 4. Payer resolves, you close

The payer signs and submits receipts for each voucher in their wallet. Once all are resolved, close the session:

```
POST /api/v1/vouchers/sessions/ses_xyz/session-close
Authorization: Bearer <payee_token>

{}
```

### Diagram

<ThemeImage img_name="Payer-resolves-you-close.png" alt="Payer resolves, you close" />

## Key points

* Each voucher in a session is **independent** — status, lifecycle, and settlement are tracked per-voucher.
* Each voucher has the **same capabilities** as a standalone SIMPLE payment (FX, auto-network, etc.).
* The session groups them for coordination but does not couple their fates.
* Close the session once all vouchers are resolved.

## Next steps

* [Simple Payments](/home/web2-web3-payments/simple-payments) — single voucher payments.
* [Smart Contracts](/home/web2-web3-payments/smart-contracts) — CUSTOM voucher for contract interactions.