diff --git a/src/content/docs/online-payments/index.mdx b/src/content/docs/online-payments/index.mdx
index 2840a6ed..d545db2e 100644
--- a/src/content/docs/online-payments/index.mdx
+++ b/src/content/docs/online-payments/index.mdx
@@ -1,124 +1,209 @@
 ---
-title: Online Payments
-description: Get started with accepting online payments. This guide walks you through creating a sandbox merchant account and processing your first transaction in minutes.
+title: Online Payments Quickstart
+description: Create a sandbox Hosted Checkout, complete a test payment, and verify the result through the SumUp API.
 sidebar:
   label: Quickstart
   order: 1
 ---
 
-import { Steps } from '@astrojs/starlight/components';
-import Callout from '@components/content/Callout';
-import Image from '@components/content/Image.astro';
+import Callout from "@components/content/Callout";
 
-Online payments form an integral part of the SumUp product portfolio. SumUp supports online payments through multiple approaches to address every merchant use case. Use one of the out-of-the-box integrations or build a complete custom payments flow with the APIs. Your app communicates with SumUp via HTTP requests defined in the [API Reference](/api).​
+Complete your first online payment with [Hosted Checkout](/online-payments/checkouts/hosted-checkout/), SumUp's hosted payment page. This path requires one server-side API call and no payment UI code.
 
-![Image showing integrations in SumUp](/img/guides/integrations.png)
-
-To get started, review the options SumUp offers for managing online payments.
-
-## Getting a Sandbox Merchant Account
-
-To test SumUp APIs and tools without involving real money, use a sandbox merchant account. Create one from your Dashboard account as follows.
-
-<Steps>
-
-1. Log in to your SumUp account.
-2. Open [Developer Settings](https://me.sumup.com/settings/developer?tab=sandboxes).
-3. In the **Sandboxes** tab, create a sandbox merchant account if you do not have one yet.
-
-</Steps>
+**Expected time:** 10–15 minutes after you can access the SumUp Dashboard.
 
 <Callout type="note">
-If you don't have a sandbox account yet, [sign up for a developer account](https://me.sumup.com/signup?signup_intent=developer). This starts you with a sandbox merchant account.
-</Callout>
-
-<Image alt="A screenshot of the account selection dropdown in the SumUp dashboard with the sandbox merchant account highlighted with red circle" src="/img/guides/test_acc.png" width="40%" />
-
-With your sandbox merchant account, begin making API calls with real data. Sandbox merchant accounts **do not** process transactions with real funds. The sandbox merchant account has a different ID and displays a clear warning. Requests with a value of 11 (in any currency) always fail by design, to test failed transaction scenarios.
-
-<Image alt="A screenshot of the dashboard with sandbox merchant account selected" src="/img/guides/test-account-warning.png" width="100%" />
 
-When finished experimenting with the sandbox merchant account, switch back to a regular account for business purposes.
+You are finished when the Hosted Checkout shows a successful payment and a server-side Retrieve Checkout request returns `PAID`.
 
-## Authorization
+</Callout>
 
-All online payment products use SumUp APIs, which require authorization via an API key or access token. See the [Authorization Guide](/tools/authorization/) for details on available options.​
+## What runs where
 
-## Checkout Products
+| Surface                  | Responsibility                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| Your backend or terminal | Creates the checkout, stores its ID and reference, and verifies the final status. The API key stays here.           |
+| Customer's browser       | Opens the returned `hosted_checkout_url` and displays SumUp's payment form.                                         |
+| SumUp                    | Hosts the payment UI, handles card data and authentication, processes the payment, and records the checkout status. |
 
-SumUp provides a range of checkout products for seamless integration with your website.
+## Prerequisites
 
-### Hosted Checkout
+- A SumUp developer account and sandbox merchant account.
+- The sandbox merchant's merchant code, currency, and API key.
+- A terminal with `curl` and `jq`.
+- A browser in which to open the hosted payment page.
 
-Hosted Checkout is the fastest path to launch. SumUp hosts the payment page, while your integration creates the checkout and redirects the customer to the returned URL.
+## Getting a sandbox merchant account
 
-See the [Hosted Checkout documentation](/online-payments/checkouts/hosted-checkout/) for details.
+1. Log in to the [SumUp Dashboard](https://me.sumup.com).
+2. Open [Developer Settings](https://me.sumup.com/settings/developer?tab=sandboxes).
+3. Create a sandbox merchant account, then select it in the Dashboard account switcher.
+4. With the sandbox merchant selected, go to **Settings** > **For Developers** > **Toolkit** > **API Keys**.
+5. Create and copy an API key. Do not use the SumUp Public Key.
+6. Copy the sandbox merchant code and note its account currency.
 
-### Payment Widget
+If you do not have a SumUp account, [create a developer account](https://me.sumup.com/signup?signup_intent=developer). New developer accounts start with a sandbox merchant account.
 
-For an embedded checkout on your own site, use the [Payment Widget](/online-payments/checkouts/card-widget/). It only requires adding a single script to your payment page.
+Sandbox payments are simulations and do not move real funds.
 
-#### Alternative Payment Methods
+## 1. Configure your terminal
 
-The Payment Widget supports [Alternative Payment Methods](/online-payments/apm) (APMs) to accept payments beyond traditional card schemes such as Visa and Mastercard. To enable APMs for your Payment Widget integration, use the [contact form](/contact).
+Replace the values below with the sandbox credentials you just collected. The checkout currency must match the sandbox merchant account currency.
 
-Available APMs include:
+```bash
+export SUMUP_API_KEY="sk_test_replace_me"
+export SUMUP_MERCHANT_CODE="replace_me"
+export SUMUP_CURRENCY="EUR"
+```
 
-- Apple Pay
-- Bancontact
-- Blik
-- Boleto
-- EPS
-- Google Pay
-- iDeal
-- MyBank
-- PIX
-- Przelewy24
-- Satispay
+<Callout type="caution">
 
-<Callout type="tip">
-The APMs you can offer depend on the location your business is registered and operates in.
-</Callout>
+Keep the API key on your server or local development machine. Never put it in browser code, a mobile application, source control, screenshots, or support messages.
 
-<Callout type="note">
-See the [Payment Methods overview](/online-payments/payment-methods/) for the
-full list of supported methods grouped by payment method family.
 </Callout>
 
-### Swift Checkout SDK
-
-The Swift Checkout SDK provides a complete and fast checkout experience to your end users, collecting payment, address, and contact information with a click of a button.
-
-See the [Swift Checkout Documentation](/online-payments/checkouts/swift-checkout/) for details.
+## 2. Create a Hosted Checkout
+
+Set a successful test amount and a unique reference, then create the checkout:
+
+```bash
+export SUMUP_AMOUNT="12.00"
+export SUMUP_CHECKOUT_REFERENCE="quickstart-$(date +%s)"
+
+SUMUP_CHECKOUT_RESPONSE="$(
+  curl --fail-with-body --silent --show-error \
+    --request POST "https://api.sumup.com/v0.1/checkouts" \
+    --header "Authorization: Bearer $SUMUP_API_KEY" \
+    --header "Content-Type: application/json" \
+    --data @- <<JSON
+{
+  "checkout_reference": "$SUMUP_CHECKOUT_REFERENCE",
+  "amount": $SUMUP_AMOUNT,
+  "currency": "$SUMUP_CURRENCY",
+  "merchant_code": "$SUMUP_MERCHANT_CODE",
+  "description": "Quickstart order",
+  "hosted_checkout": {
+    "enabled": true
+  }
+}
+JSON
+)"
+
+echo "$SUMUP_CHECKOUT_RESPONSE" | jq
+```
+
+The response should contain these fields:
+
+```json
+{
+  "id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91",
+  "checkout_reference": "quickstart-1785686400",
+  "status": "PENDING",
+  "hosted_checkout": {
+    "enabled": true
+  },
+  "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676"
+}
+```
+
+Store the values needed for the next steps:
+
+```bash
+export SUMUP_CHECKOUT_ID="$(echo "$SUMUP_CHECKOUT_RESPONSE" | jq -r '.id')"
+export SUMUP_HOSTED_CHECKOUT_URL="$(echo "$SUMUP_CHECKOUT_RESPONSE" | jq -r '.hosted_checkout_url')"
+
+echo "$SUMUP_HOSTED_CHECKOUT_URL"
+```
+
+If either value is empty or `null`, stop and inspect the API response before continuing.
+
+## 3. Complete the payment
+
+1. Copy the printed `SUMUP_HOSTED_CHECKOUT_URL` into your browser.
+2. Enter the following sandbox card details.
+3. Submit the payment and wait for the Hosted Checkout success page.
+
+| Field           | Test value                       |
+| --------------- | -------------------------------- |
+| Card number     | `4200 0000 0000 0091`            |
+| Expiry date     | Any future date, such as `12/30` |
+| CVV             | Any three digits, such as `123`  |
+| Cardholder name | Any name                         |
+
+The browser result is useful customer feedback, but it is not the state your backend should use to fulfill an order.
+
+## 4. Verify the payment
+
+Retrieve the checkout from your backend or terminal:
+
+```bash
+SUMUP_VERIFICATION_RESPONSE="$(
+  curl --fail-with-body --silent --show-error \
+    "https://api.sumup.com/v0.1/checkouts/$SUMUP_CHECKOUT_ID" \
+    --header "Authorization: Bearer $SUMUP_API_KEY"
+)"
+
+echo "$SUMUP_VERIFICATION_RESPONSE" | jq
+```
+
+After the successful sandbox payment, the relevant fields look like this:
+
+```json
+{
+  "id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91",
+  "checkout_reference": "quickstart-1785686400",
+  "status": "PAID",
+  "transactions": [
+    {
+      "status": "SUCCESSFUL",
+      "transaction_code": "TEENSK4W2K"
+    }
+  ]
+}
+```
+
+- `PAID`: mark the order as paid exactly once.
+- `PENDING`: wait and retrieve the checkout again.
+- `FAILED`: keep the order unpaid and let the customer start a new attempt.
+- `EXPIRED`: create a new checkout with a new reference.
+
+<Callout type="caution">
+
+Fulfill the order only after your backend retrieves the checkout and confirms `PAID`. A browser redirect, hosted success page, frontend callback, or webhook delivery is not payment proof on its own.
 
-## Plugins
-
-For Prestashop, Wix, or WooCommerce, use SumUp plugins for seamless payments. See the [Plugins section](/online-payments/plugins/) for details on each.​
-
-## Custom Integrations
+</Callout>
 
-### SumUp APIs
+## 5. Test a failed payment
 
-SumUp provides REST APIs for creating and retrieving checkouts, managing transactions, storing tokenized payment instruments, and issuing refunds. SumUp APIs use API keys or [OAuth 2.0](https://www.rfc-editor.org/rfc/rfc6749) for authentication.
+Set the deliberate failure amount and a new reference:
 
-Call authenticated API endpoints from your server. Keep API keys and client secrets out of browsers and mobile apps.
+```bash
+export SUMUP_AMOUNT="11.00"
+export SUMUP_CHECKOUT_REFERENCE="quickstart-failure-$(date +%s)"
+```
 
-### Receiving Payments
+Repeat steps 2–4 with the same test card. The hosted page should show a failed payment and Retrieve Checkout should return `FAILED`. Never reuse the successful checkout ID or reference for this attempt.
 
-Start by [choosing a checkout integration](/online-payments/checkouts/). Your server creates a checkout with the amount, currency, merchant code, and a unique checkout reference. The selected checkout integration then collects the customer's payment details and completes the payment without sending raw card details through your server.
+## Troubleshooting
 
-SumUp supports the following payment paths:
+| Symptom                                       | What to check                                                                             |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `401 Unauthorized`                            | The value is a sandbox secret API key, and the header uses `Bearer`.                      |
+| `403 Forbidden`                               | The sandbox merchant can accept online payments and the credential can create checkouts.  |
+| `409 Conflict`                                | Generate a new `checkout_reference`; do not reuse a previous attempt's reference.         |
+| Missing `hosted_checkout_url`                 | Confirm that `hosted_checkout.enabled` is `true` and inspect the complete error response. |
+| Hosted page is expired                        | Hosted Checkout sessions expire after 30 minutes. Create a new checkout and URL.          |
+| Browser says success but the API is `PENDING` | Keep the order pending and retrieve the checkout again.                                   |
 
-- [Hosted Checkout](/online-payments/checkouts/hosted-checkout/) redirects the customer to a SumUp-hosted payment page.
-- [Payment Widget](/online-payments/checkouts/card-widget/) embeds the SumUp payment form in your website.
-- [Swift Checkout SDK](/online-payments/checkouts/swift-checkout/) and the [React Native SDK](/online-payments/sdks/react-native/) provide checkout experiences for supported mobile use cases.
-- [Alternative Payment Methods](/online-payments/apm/) support wallets, bank-based methods, vouchers, and other locally available options.
-- [Tokenization and recurring payments](/online-payments/guides/tokenization-with-payment-sdk/) use a saved payment instrument rather than raw card details.
+## Move to production
 
-Do not build a payment form that sends raw card details to the Checkouts API. Use one of the checkout integrations above to collect payment details.
+Before accepting real payments:
 
-## Contact SumUp
+1. Switch to the live merchant account and create separate production credentials.
+2. Store `checkout.id`, `checkout_reference`, merchant code, amount, currency, and transaction identifiers with your order.
+3. Add a real HTTPS `redirect_url` for customer navigation and a webhook for status-change notifications.
+4. Make checkout creation and order fulfillment safe against retries and duplicates.
+5. Test success, failure, expiry, and abandoned-payment scenarios.
+6. Process a small live payment and reconcile it in the SumUp Dashboard before launch.
 
-<Callout type="note">
-Do you have specific questions? Check out our [help page](/help) for the most frequently asked questions or [contact us here](/contact).
-</Callout>
+For an embedded payment form, continue with the [Payment Widget](/online-payments/checkouts/card-widget/). For mobile applications or other checkout experiences, compare the [checkout integrations](/online-payments/checkouts/).
diff --git a/src/content/docs/terminal-payments/quickstart.mdx b/src/content/docs/terminal-payments/quickstart.mdx
index c2ec860e..d8a9965c 100644
--- a/src/content/docs/terminal-payments/quickstart.mdx
+++ b/src/content/docs/terminal-payments/quickstart.mdx
@@ -1,94 +1,249 @@
 ---
-title: Quickstart
-description: Get your first in-person payment running with the right SumUp integration path and the prerequisites for testing.
+title: In-Person Payments Quickstart
+description: Pair Virtual Solo, start a sandbox Cloud API checkout, and verify your first in-person payment.
 sidebar:
+  label: Quickstart
   order: 2
 ---
 
-import { Steps } from '@astrojs/starlight/components';
-import Callout from '@components/content/Callout';
-import Image from '@components/content/Image.astro';
+import Callout from "@components/content/Callout";
 
-Get your first in-person payment running quickly.
+Complete your first in-person payment with the Cloud API and [Virtual Solo](https://virtual-solo.sumup.com). This path exercises the same reader APIs as a physical Solo without requiring hardware or a native mobile application.
 
-## Prerequisites
-
-- A SumUp merchant account
-- A supported reader or Tap to Pay-capable device
-- The credentials required for your chosen integration:
-  - [Affiliate Key](/tools/authorization/affiliate-keys/) for Reader SDKs and Payment Switch
-  - [Authorization](/tools/authorization/) for Cloud API and Tap to Pay SDK flows
-
-## Sandbox Merchant Account
-
-To test without real money, create a sandbox merchant account from the SumUp Dashboard.
-
-<Steps>
-
-1. Log in to your SumUp account.
-2. Open [Developer Settings](https://me.sumup.com/settings/developer?tab=sandboxes).
-3. In the **Sandbox environment** section, create a sandbox merchant account if you do not have one yet.
-4. Open the account switcher in the Dashboard and select **Sandbox Merchant Account**.
-
-</Steps>
+**Expected time:** 15–20 minutes after you can access the SumUp Dashboard.
 
 <Callout type="note">
-If you don't have a sandbox account yet, [sign up for a developer account](https://me.sumup.com/signup?signup_intent=developer). This starts you with a sandbox merchant account.
-</Callout>
 
-<Image alt="A screenshot of the account selection dropdown in the SumUp dashboard with the sandbox merchant account highlighted with red circle" src="/img/guides/test_acc.png" width="40%" />
+You are finished when Virtual Solo completes the simulated payment and Get Reader Checkout returns `successful`.
 
-Sandbox accounts do not process real funds. They have a separate merchant ID, show a clear warning in the Dashboard, and requests with a value of `11` always fail by design so you can test failed transaction scenarios.
-
-<Image alt="A screenshot of the dashboard with sandbox merchant account selected" src="/img/guides/test-account-warning.png" width="100%" />
-
-## Choose Your Path
-
-### Reader SDKs
-
-Best for native Android and iOS apps that want more control over the payment experience.
+</Callout>
 
-<Steps>
+## What runs where
 
-1. Install the SDK for [Android SDK](/terminal-payments/sdks/android-sdk/), [iOS SDK](/terminal-payments/sdks/ios-sdk/), or [Android Tap-to-Pay SDK](/terminal-payments/sdks/android-ttp/).
-2. Authenticate the merchant.
-3. Pair a reader over Bluetooth, or initialize Tap to Pay on device.
-4. Start a payment and handle the result in your app.
+| Surface                       | Responsibility                                                                                                               |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Your POS backend or terminal  | Pairs the reader, creates the checkout, stores identifiers, and verifies the final result. API and Affiliate Keys stay here. |
+| Virtual Solo or physical Solo | Presents the amount and cardholder flow. Card data never passes through your POS backend.                                    |
+| SumUp                         | Connects the checkout to the reader, processes the simulated payment, and records its status.                                |
 
-</Steps>
+## Prerequisites
 
-### Cloud API
+- A SumUp developer account and sandbox merchant account.
+- The sandbox merchant's merchant code, currency, and API key.
+- An Affiliate Key and its matching application ID.
+- A terminal with `curl` and `jq`.
+- A browser in which to run Virtual Solo.
 
-Best for server-driven, web-based, or multi-platform systems using Solo readers.
+## Sandbox merchant account
 
-<Steps>
+1. Log in to the [SumUp Dashboard](https://me.sumup.com).
+2. Open [Developer Settings](https://me.sumup.com/settings/developer?tab=sandboxes).
+3. Create a sandbox merchant account, then select it in the Dashboard account switcher.
+4. With the sandbox merchant selected, go to **Settings** > **For Developers** > **Toolkit**.
+5. Under **API Keys**, create and copy an API key. Do not use the SumUp Public Key.
+6. Under **Affiliate Keys**, create a key for an application ID you control, such as `com.example.quickstart`.
+7. Copy the sandbox merchant code and note its account currency.
 
-1. Set up [authorization](/tools/authorization/) for API access.
-2. Pair or register a Solo reader through the [Cloud API](/terminal-payments/cloud-api/).
-3. Create a checkout for the paired reader.
-4. Let the reader complete the payment and track the result asynchronously.
+If you do not have a SumUp account, [create a developer account](https://me.sumup.com/signup?signup_intent=developer). New developer accounts start with a sandbox merchant account.
 
-</Steps>
+Sandbox transactions are simulations and do not move real funds.
 
-### Payment Switch
+## 1. Configure your terminal
 
-Best for lightweight legacy mobile integrations that hand off checkout to the SumUp app.
+Replace the values below. `SUMUP_APP_ID` must exactly match an application ID assigned to the Affiliate Key, and the currency must match the sandbox merchant account.
 
-<Steps>
+```bash
+export SUMUP_API_KEY="sk_test_replace_me"
+export SUMUP_MERCHANT_CODE="replace_me"
+export SUMUP_AFFILIATE_KEY="replace_me"
+export SUMUP_APP_ID="com.example.quickstart"
+export SUMUP_CURRENCY="EUR"
+```
 
-1. Install the SumUp app on the merchant device.
-2. Build a Payment Switch request with amount, currency, and a callback URL.
-3. Open the SumUp app and let it handle the checkout.
-4. Receive the payment result back in your app.
+<Callout type="caution">
 
-</Steps>
+API keys authorize account access; Affiliate Keys identify the card-present integration. Keep both on your backend and send the full `affiliate` object in every reader checkout.
 
-<Callout type="note">
-Use a unique transaction reference such as `foreignTransactionId` or `foreign-tx-id` for each payment. That prevents duplicate transaction conflicts and makes reconciliation easier.
 </Callout>
 
-## Next Steps
+## 2. Pair Virtual Solo
+
+1. Open [Virtual Solo](https://virtual-solo.sumup.com) and select the sandbox environment.
+2. In the simulated reader, open **Connections** > **API** > **Connect**.
+3. Copy the displayed pairing code. It expires after five minutes.
+4. Export the code, then create the reader:
+
+```bash
+export SUMUP_PAIRING_CODE="replace_me"
+
+SUMUP_READER_RESPONSE="$(
+  curl --fail-with-body --silent --show-error \
+    --request POST "https://api.sumup.com/v0.1/merchants/$SUMUP_MERCHANT_CODE/readers" \
+    --header "Authorization: Bearer $SUMUP_API_KEY" \
+    --header "Content-Type: application/json" \
+    --data @- <<JSON
+{
+  "pairing_code": "$SUMUP_PAIRING_CODE",
+  "name": "Quickstart Virtual Solo"
+}
+JSON
+)"
+
+echo "$SUMUP_READER_RESPONSE" | jq
+export SUMUP_READER_ID="$(echo "$SUMUP_READER_RESPONSE" | jq -r '.id')"
+```
+
+The initial response identifies the reader:
+
+```json
+{
+  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
+  "name": "Quickstart Virtual Solo",
+  "status": "processing",
+  "device": {
+    "identifier": "VIRTUAL-SOLO-01",
+    "model": "virtual-solo"
+  }
+}
+```
+
+Wait for the pairing confirmation in Virtual Solo, then retrieve the reader:
+
+```bash
+curl --fail-with-body --silent --show-error \
+  "https://api.sumup.com/v0.1/merchants/$SUMUP_MERCHANT_CODE/readers/$SUMUP_READER_ID" \
+  --header "Authorization: Bearer $SUMUP_API_KEY" | jq
+```
+
+Continue when the reader status is `paired`. If it remains `processing`, wait briefly and retrieve it again. If it becomes `expired`, generate a new pairing code and repeat this step.
+
+## 3. Start the reader checkout
+
+Use a unique foreign transaction ID for every attempt. For currencies with two decimal places, `value: 1200` and `minor_unit: 2` represent 12.00.
+
+```bash
+export SUMUP_AMOUNT_VALUE="1200"
+export SUMUP_FOREIGN_TRANSACTION_ID="quickstart-$(date +%s)"
+
+SUMUP_READER_CHECKOUT_RESPONSE="$(
+  curl --fail-with-body --silent --show-error \
+    --request POST "https://api.sumup.com/v0.1/merchants/$SUMUP_MERCHANT_CODE/readers/$SUMUP_READER_ID/checkout" \
+    --header "Authorization: Bearer $SUMUP_API_KEY" \
+    --header "Content-Type: application/json" \
+    --data @- <<JSON
+{
+  "total_amount": {
+    "currency": "$SUMUP_CURRENCY",
+    "minor_unit": 2,
+    "value": $SUMUP_AMOUNT_VALUE
+  },
+  "description": "Quickstart payment",
+  "affiliate": {
+    "app_id": "$SUMUP_APP_ID",
+    "key": "$SUMUP_AFFILIATE_KEY",
+    "foreign_transaction_id": "$SUMUP_FOREIGN_TRANSACTION_ID"
+  }
+}
+JSON
+)"
+
+echo "$SUMUP_READER_CHECKOUT_RESPONSE" | jq
+export SUMUP_READER_CHECKOUT_ID="$(echo "$SUMUP_READER_CHECKOUT_RESPONSE" | jq -r '.data.checkout_id')"
+```
+
+The accepted response contains identifiers for reconciliation:
+
+```json
+{
+  "data": {
+    "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+  }
+}
+```
+
+If `checkout_id` is empty or `null`, stop and inspect the complete response.
+
+## 4. Complete the payment on Virtual Solo
+
+The checkout should appear on Virtual Solo within 60 seconds.
+
+1. Confirm the amount and start the simulated payment.
+2. Follow the on-screen flow. No real card is needed; Virtual Solo simulates the reader interaction and auto-approves simulated PIN entry.
+3. Wait until the device returns to its idle screen.
+
+Do not start another checkout on the same reader while this checkout is active.
+
+## 5. Verify the result
+
+Retrieve the reader checkout from your backend or terminal:
+
+```bash
+SUMUP_READER_VERIFICATION_RESPONSE="$(
+  curl --fail-with-body --silent --show-error \
+    "https://api.sumup.com/v0.1/merchants/$SUMUP_MERCHANT_CODE/readers/$SUMUP_READER_ID/checkout/$SUMUP_READER_CHECKOUT_ID" \
+    --header "Authorization: Bearer $SUMUP_API_KEY"
+)"
+
+echo "$SUMUP_READER_VERIFICATION_RESPONSE" | jq
+```
+
+After the successful simulation, the relevant fields look like this:
+
+```json
+{
+  "data": {
+    "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "status": "successful",
+    "payment_type": "card",
+    "total_amount": {
+      "currency": "EUR",
+      "minor_unit": 2,
+      "value": 1200
+    }
+  }
+}
+```
+
+- `successful`: record the payment exactly once.
+- `pending`: wait and retrieve the checkout again.
+- `failed`: keep the order unpaid and inspect `payment_failure_reason`.
+- `cancelled`: keep the order unpaid and start a new checkout only if the merchant wants to retry.
+
+Treat a callback as a notification only. Get Reader Checkout is the authoritative result for the POS order state.
+
+## 6. Test a failed payment
+
+Set the deliberate failure amount and a new foreign transaction ID:
+
+```bash
+export SUMUP_AMOUNT_VALUE="1100"
+export SUMUP_FOREIGN_TRANSACTION_ID="quickstart-failure-$(date +%s)"
+```
+
+Repeat steps 3–5. Virtual Solo should complete the simulated attempt, and Get Reader Checkout should return `failed`. Never reuse the successful `foreign_transaction_id` or checkout ID.
+
+## Troubleshooting
+
+| Symptom                       | What to check                                                                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Pairing code is rejected      | Pair within five minutes and make sure the code came from the selected sandbox Virtual Solo session.                                  |
+| Reader stays `processing`     | Confirm pairing on Virtual Solo, then retrieve the reader again. Re-pair if the reader becomes `expired`.                             |
+| Checkout is rejected          | Confirm the reader is `paired` and online, the currency matches the merchant account, and the complete `affiliate` object is present. |
+| Nothing appears on the reader | The checkout must start on the device within 60 seconds. Retrieve the checkout before creating another attempt.                       |
+| Duplicate transaction error   | Generate a new `foreign_transaction_id` for the new attempt.                                                                          |
+| Callback and API disagree     | Keep the POS order pending until Get Reader Checkout returns a final status.                                                          |
+
+## Move to production
+
+Before accepting real card-present payments:
+
+1. Pair a physical Solo with the live merchant and validate reader connectivity.
+2. Use separate production API and Affiliate Keys with the correct application ID.
+3. Store the reader ID, checkout ID, client transaction ID, foreign transaction ID, merchant code, amount, and final status.
+4. Add an HTTPS `return_url` and process callbacks idempotently, then verify every result with Get Reader Checkout.
+5. Handle reader-offline, active-checkout, timeout, cancellation, and duplicate-reference scenarios.
+6. Run a small live transaction and reconcile it in the SumUp Dashboard before launch.
 
-- Need an embedded mobile flow? Continue with [Reader SDKs](/terminal-payments/sdks/).
-- Need remote Solo payments? Continue with [Cloud API](/terminal-payments/cloud-api/).
-- Need app handoff to SumUp? Continue with [Payment Switch](/terminal-payments/payment-switch/).
+Building a native mobile app instead? Choose the [Android or iOS Reader SDK](/terminal-payments/sdks/). Use [Payment Switch](/terminal-payments/payment-switch/) only when your app must hand off to the installed SumUp app.
diff --git a/src/pages/index.astro b/src/pages/index.astro
index bcd7fd40..48f1eea6 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -41,10 +41,10 @@ const props = {
         <Headline as="h2" className="header">Card-present Solutions</Headline>
         <div class="button-links">
           <ListItem
-            href="/terminal-payments"
+            href="/terminal-payments/quickstart/"
             variant="navigation"
             label="Quickstart"
-            details="Integrate with SumUp Solo card reader to accept in-person payments."
+            details="Run a sandbox payment with Virtual Solo."
             leadingComponent={Play}
           />
           <ListItem
diff --git a/vitest.config.ts b/vitest.config.ts
index c7e4328f..225ac886 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,7 +5,7 @@ export default getViteConfig(
   {
     test: {
       environment: "node",
-      include: ["src/lib/codesamples/**/*.test.ts"],
+      include: ["src/lib/**/*.test.ts"],
     },
   },
   {