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

# Sessions & Executions

> Checkout sessions, fund executions, idempotency, and two status models in the Dollr API.

## Session

A **session** declares intent to run an operation: **checkout** (collect) or **payout**. Create a session against a payment source (invoice, order, or checkout-created source), then execute it before the session expires.

<Note>
  **API Reference:** [Checkout session](/api-reference/sessions/create-checkout-session) · [Payout session](/api-reference/sessions/create-payout-session)
</Note>

<Info>
  **Hosted checkout** skips server-side sessions and executions — the customer pays on a Dollr page. See [Hosted checkout](/guides/hosted-checkout).
</Info>

## Execution

An **execution** submits an active session and moves funds.

**Collection** requires:

* `session_id`
* `payment_account_id` (registered wallet or card)
* `currency`
* `reference_id` — UUID v4 you generate **before** the HTTP call

**Payout** requires `session_id`, `payout_account_id`, `reference_id`, and `passcode` (merchant verification with device metadata).

<Warning>
  `reference_id` is your idempotency key. If the network fails, poll status with the **same** `reference_id` before retrying. Never mint a new UUID until you confirm the original attempt did not land.
</Warning>

## Card 3D Secure

Collection executions for cards may return `requires_action: true` and a `client_secret`. Complete Stripe authentication in your UI before polling status. See [Collect with card](/guides/collect-with-card).

## Two status models

| Model                      | Tracks             | Example values                                          |
| -------------------------- | ------------------ | ------------------------------------------------------- |
| **Execution**              | Movement of funds  | `PENDING` → `PROCESSING` → `COMPLETED` \| `FAILED`      |
| **Source** (invoice/order) | Document lifecycle | `IDLE` → `ACTIVE` → `PROCESSING` → `PAID` \| `CANCELED` |

Mobile money often stays in `PROCESSING` for several minutes. Poll execution status; do not re-execute during that window.

## Poll execution status

```http theme={null}
GET /v1/status/collection/{reference_id}
GET /v1/status/payout/{reference_id}
```

For hosted checkout, you can also check source status:

```http theme={null}
GET /v1/status/source?source_type=INVOICE&source_id={id}
```

## Fee bearer

* **`PAYER`** — Customer pays fees on top of the total; merchant receives the full invoice amount.
* **`PAYEE`** — Merchant absorbs fees; customer pays the listed total.

## Related

* [Hosted checkout](/guides/hosted-checkout) · [Parties & counterparties](/concepts/parties-and-counterparties)
* [Realtime status](/guides/realtime-status) — push updates instead of polling
* [Executions API concept](/api/executions) · [Status](/api/status)
* [Quick Start](/quickstart)