feat(glossary): sales, transactions, checkouts

src/content/docs/tools/glossary/checkout.mdx

@@ -0,0 +1,79 @@
+---
+title: Checkout
+description: A checkout defines how SumUp should collect a payment from a customer.
+sidebar:
+  order: 40
+---
+
+A Checkout is a request or session that tells SumUp to collect a specific
+amount in a specific currency. It connects the commercial intent represented
+by a [Sale](/tools/glossary/sale/) with payment processing.
+
+A Checkout commonly contains:
+
+- The amount and currency to collect
+- The merchant receiving the payment
+- A merchant-defined reference
+- Optional customer, expiration, redirect, and callback details
+- Its current status and any linked
+  [Transactions](/tools/glossary/transaction/)
+
+A Checkout is not proof that payment succeeded. It can exist before any payment
+attempt and can remain `PENDING`, fail, or expire without a successful
+Transaction.
+
+## Checkout Types in the Public APIs
+
+The Developer Portal uses Checkout in two related payment flows:
+
+- The **Checkouts API** creates an online Checkout, processes it with a payment
+  instrument, and retrieves its latest state. Start with
+  [Create a checkout](/api/checkouts/create), then use a supported integration
+  such as the [Payment Widget](/online-payments/checkouts/card-widget/) or
+  [Hosted Checkout](/online-payments/checkouts/hosted-checkout/).
+- The **Readers API** creates a Checkout on a paired card reader. This starts an
+  asynchronous in-person payment flow. See
+  [Create a Reader Checkout](/api/readers/create-checkout).
+
+These resources have different endpoint shapes and lifecycles, but serve the
+same conceptual purpose: they coordinate how a payment should be attempted.
+
+## Typical Online Checkout Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant App as Your backend
+    participant API as Checkouts API
+    participant UI as Payment UI
+    participant Tx as Transaction record
+
+    App->>API: Create checkout
+    API-->>App: Checkout with PENDING status
+    App->>UI: Provide checkout ID
+    UI->>API: Process payment
+    API->>Tx: Record payment attempt
+    API-->>UI: Return result or next action
+    App->>API: Retrieve checkout
+    API-->>App: Latest status and linked transactions
+```
+
+For redirect-based payment methods or 3DS, processing can return a next action
+instead of a final result. Always use
+[Retrieve a checkout](/api/checkouts/get) from your backend to confirm the
+latest Checkout status.
+
+## Relationship to a Sale and Transaction
+
+- The **Sale** describes the items, taxes, discounts, customer, and other
+  commercial context.
+- The **Checkout** carries the amount, currency, and instructions needed to
+  attempt payment.
+- Processing the Checkout creates or updates a **Transaction**, which records
+  the financial result.
+
+A newly created Checkout can have an empty `transactions` array. Payment
+processing attaches Transaction records as attempts occur. Use the Checkout to
+manage the payment flow; use the
+[Transactions API](/api/transactions/get) for transaction details, history,
+and post-payment operations.

src/content/docs/tools/glossary/sale.mdx

@@ -0,0 +1,50 @@
+---
+title: Sale
+description: A sale records what was sold and connects the commercial event to its payments.
+sidebar:
+  order: 30
+---
+
+A Sale is the commercial record of an exchange between a merchant and a
+customer. It answers **what was sold**, independently of how the customer paid.
+
+A Sale can contain business details such as:
+
+- Items and quantities
+- Taxes, discounts, and tips
+- Customer information
+- The sales channel, device, or location
+- The total amount and payment state
+
+A Sale can exist before payment, be paid by one or more
+[Transactions](/tools/glossary/transaction/), or use a payment method that does
+not require a SumUp Checkout. This makes a Sale broader than a payment record.
+
+## How Sales, Checkouts, and Transactions Relate
+
+Use these terms to describe different parts of the same flow:
+
+- **Sale**: what the customer is buying
+- **[Checkout](/tools/glossary/checkout/)**: the request or session used to
+  collect an amount
+- **[Transaction](/tools/glossary/transaction/)**: the recorded outcome of a
+  payment attempt or later financial operation
+
+```mermaid
+flowchart LR
+    Sale["Sale<br/>Items, taxes, discounts, customer"]
+    Checkout["Checkout<br/>Amount, currency, payment flow"]
+    Attempt["Payment attempt<br/>Online or in person"]
+    Transaction["Transaction<br/>Financial outcome"]
+    Events["Later events<br/>Refund, chargeback, payout"]
+
+    Sale -->|Amount to collect| Checkout
+    Checkout -->|Process online or start on a reader| Attempt
+    Attempt -->|Creates a record| Transaction
+    Transaction -.->|Updates the payment state| Sale
+    Transaction --> Events
+```
+
+The exact relationship depends on the integration. For example, a merchant can
+split one Sale across multiple payments, while an online purchase commonly
+uses one Checkout to create one successful Transaction.

src/content/docs/tools/glossary/transaction.mdx

@@ -0,0 +1,63 @@
+---
+title: Transaction
+description: A transaction records the financial outcome of a payment or related operation.
+sidebar:
+  order: 50
+---
+
+A Transaction is a financial record created when a payment is attempted or a
+related operation is processed. It answers **what happened to the money**.
+
+A Transaction can include:
+
+- The amount and currency
+- Its processing status
+- The payment type and entry mode
+- SumUp and merchant-provided identifiers
+- Card, device, payout, refund, and other event details where applicable
+
+Unlike a [Sale](/tools/glossary/sale/), a Transaction does not describe the full
+basket or commercial context. Unlike a
+[Checkout](/tools/glossary/checkout/), it is not an instruction to collect a
+payment: it records the result of processing one.
+
+## Transaction Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: Payment attempt created
+    PENDING --> SUCCESSFUL: Payment completes
+    PENDING --> FAILED: Payment fails
+    PENDING --> CANCELLED: Payment is cancelled
+    SUCCESSFUL --> REFUNDED: Full or partial refund
+```
+
+The Transaction status is separate from the Checkout status. For example, a
+Checkout can be `PENDING` while a redirect-based payment is still being
+completed, and its linked Transaction can also have its own `PENDING` state.
+
+## Transactions in the Public APIs
+
+The Transactions API supports the post-payment lifecycle:
+
+- [Retrieve a transaction](/api/transactions/get) by its SumUp ID, transaction
+  code, foreign transaction ID, or client transaction ID
+- [List transactions](/api/transactions/list) for a merchant and filter the
+  history by status, payment type, entry mode, or transaction type
+- [Refund a transaction](/api/transactions/refund/) in full or partially
+
+Transaction history can include payments, refunds, and chargebacks. A full
+Transaction resource can also contain events related to refunds, chargebacks,
+payouts, and payout deductions.
+
+## Relationship to a Sale and Checkout
+
+A typical online flow starts with a Sale or order in your system. You create a
+Checkout for the amount to collect, then process it. The payment attempt creates
+a Transaction, and the Checkout response links to it through fields such as
+`transaction_id`, `transaction_code`, and `transactions`.
+
+Not every Transaction originates from the online Checkouts API. In-person
+payments initiated through a reader or mobile SDK also produce Transactions.
+Use stable merchant-provided references and store SumUp identifiers so you can
+reconcile each Transaction with the correct Sale.