Sessions

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

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 — single voucher payments.
• Smart Contracts — CUSTOM voucher for contract interactions.