diff --git a/src/content/docs/tools/glossary/checkout.mdx b/src/content/docs/tools/glossary/checkout.mdx deleted file mode 100644 index 0d6146ef..00000000 --- a/src/content/docs/tools/glossary/checkout.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -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 deleted file mode 100644 index 01dca275..00000000 --- a/src/content/docs/tools/glossary/sale.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -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 deleted file mode 100644 index c03ff915..00000000 --- a/src/content/docs/tools/glossary/transaction.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -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.