From b671fe1fb4378be0905a92511e4c81fec8d72033 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Dzivjak?= Date: Sun, 2 Aug 2026 10:09:43 +0200 Subject: [PATCH] feat(docs): update quickstart guide Walk the user through the whole process of accepting first payment. --- src/content/docs/online-payments/index.mdx | 255 ++++++++++------ .../docs/terminal-payments/quickstart.mdx | 287 ++++++++++++++---- src/pages/index.astro | 4 +- vitest.config.ts | 2 +- 4 files changed, 394 insertions(+), 154 deletions(-) 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. - - - -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. - - +**Expected time:** 10–15 minutes after you can access the SumUp Dashboard. -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. - - -A screenshot of the account selection dropdown in the SumUp dashboard with the sandbox merchant account highlighted with red circle - -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. - -A screenshot of the dashboard with sandbox merchant account selected -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 + -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 + - -The APMs you can offer depend on the location your business is registered and operates in. - +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. - -See the [Payment Methods overview](/online-payments/payment-methods/) for the -full list of supported methods grouped by payment method family. -### 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 @- < + +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 + -### 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. - -Do you have specific questions? Check out our [help page](/help) for the most frequently asked questions or [contact us here](/contact). - +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. - - - -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**. - - +**Expected time:** 15–20 minutes after you can access the SumUp Dashboard. -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. - -A screenshot of the account selection dropdown in the SumUp dashboard with the sandbox merchant account highlighted with red circle +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. - -A screenshot of the dashboard with sandbox merchant account selected - -## Choose Your Path - -### Reader SDKs - -Best for native Android and iOS apps that want more control over the payment experience. + - +## 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. | - +## 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 - +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. - +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. - +```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. + - +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. - -Use a unique transaction reference such as `foreignTransactionId` or `foreign-tx-id` for each payment. That prevents duplicate transaction conflicts and makes reconciliation easier. -## 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 @- <Card-present Solutions