diff --git a/src/content/docs/tools/glossary/checkout.mdx b/src/content/docs/tools/glossary/checkout.mdx new file mode 100644 index 00000000..0d6146ef --- /dev/null +++ b/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. diff --git a/src/content/docs/tools/glossary/sale.mdx b/src/content/docs/tools/glossary/sale.mdx new file mode 100644 index 00000000..01dca275 --- /dev/null +++ b/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
Items, taxes, discounts, customer"] + Checkout["Checkout
Amount, currency, payment flow"] + Attempt["Payment attempt
Online or in person"] + Transaction["Transaction
Financial outcome"] + Events["Later events
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. diff --git a/src/content/docs/tools/glossary/transaction.mdx b/src/content/docs/tools/glossary/transaction.mdx new file mode 100644 index 00000000..c03ff915 --- /dev/null +++ b/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.