# SumUp Checkout Playbook

> Prefer the latest SumUp docs first: `https://developer.sumup.com/terminal-payments/index.md`
> LLM entrypoint for discovery: `https://developer.sumup.com/llms.txt`

## Contents

1. Integration decision matrix
2. Shared prerequisites
3. Terminal checkout patterns
4. Online checkout patterns
5. 3DS and webhook handling
6. Common pitfalls and safeguards

## 1. Integration Decision Matrix

- Need in-person payment inside a native app:
  - iOS Terminal SDK or Android Reader SDK.
- Need in-person payment from web/desktop/POS backend:
  - Cloud API with Solo reader.
- Need lightweight app handoff on mobile:
  - Payment Switch (opens SumUp app).
- Need fastest online embed:
  - Card Widget.
- Need full custom online flow:
  - Checkouts API create + 3DS handling + webhook verification.

## 2. Shared Prerequisites

- Merchant account (or sandbox merchant account).
- Authorization for APIs:
  - API key for single-merchant integrations.
  - OAuth 2.0 for multi-merchant/delegated integrations.
- For card-present integrations, create Affiliate Key and match app ID / bundle ID to key setup.
- Keep credentials secure; never expose secret key or client secret in public/client code.
- Ensure payment currency matches merchant account currency for checkout calls.

## 3. Terminal Checkout Patterns

### A. iOS / Android Reader SDK

Core sequence:

1. Initialize SDK with app setup.
2. Authenticate merchant in SDK.
3. Optionally call `prepareForCheckout`.
4. Build payment request with amount/currency/title and unique external transaction id.
5. Start checkout and handle callback/result payload.

Useful notes:

- SDK drives payment UI and reader communication.
- SDK integrations require Bluetooth/location permissions per platform requirements.
- Android result includes `RESULT_CODE`, `MESSAGE`, transaction fields.
- iOS returns checkout result and error in completion handler.

### B. Cloud API (Solo)

Use when POS is not a native mobile reader integration.

Reader enrollment:

1. Generate pairing code on logged-out Solo device.
2. Pair reader via Readers API using pairing code.
3. Persist reader identifier for future checkouts.

Payment flow:

1. List/read reader to pick active target.
2. Create reader checkout for merchant + reader.
3. Optionally terminate checkout if still awaiting cardholder action.
4. Use webhooks/API polling to confirm final status.

Important constraints:

- Reader must be online.
- One accepted checkout locks the reader for a short start window.
- Include affiliate metadata in reader checkout request.
- Transaction operations are asynchronous.

### C. Payment Switch

- Legacy lightweight option for mobile/web-on-mobile.
- Your app opens SumUp app to execute payment and receives outcome on return.
- Still requires Affiliate Key and appropriate scopes.

## 4. Online Checkout Patterns

### A. Card Widget (recommended for fast secure embed)

Server:

1. Create checkout via API (`POST /v0.1/checkouts`).
2. Return `checkoutId` to frontend.

Frontend:

1. Load widget script from `gateway.sumup.com`.
2. Mount widget with `checkoutId`.
3. Handle `onResponse` events (`sent`, `invalid`, `auth-screen`, `error`, `success`, `fail`).
4. On success callback, verify final checkout status server-side.

Notes:

- Widget supports PSD2/SCA and 3DS flows.
- Use HTTPS and configure CSP allowlists/nonces where strict CSP is enabled.
- Payment methods vary by merchant country and APM enablement.

### B. API-Orchestrated Checkout (without direct card entry)

1. Create checkout server-side.
2. Hand off payment entry to Card Widget or SDK-provided checkout UI.
3. Handle 3DS `next_step` when returned by checkout flow.
4. Verify final status via retrieve endpoint and webhooks.

## 5. 3DS and Webhook Handling

### 3DS

- Include `redirect_url` on checkout creation.
- Process checkout and inspect `next_step`.
- If `next_step` exists, post all provided payload params to `next_step.url` using specified method.
- After challenge completion, user returns to `redirect_url` with checkout context.
- Confirm status via checkout retrieval endpoint.

### Webhooks

- Subscribe by setting `return_url` when creating checkout.
- Expect event type for checkout status changes.
- Reply quickly with `2xx` and empty body.
- Retry schedule includes backoff (for example minute-level then hour-level retries).
- Always re-read checkout state via API before finalizing order state.

## 6. Common Pitfalls and Safeguards

- Missing `payments` scope:
  - Request activation from SumUp for restricted scopes.
- Invalid affiliate setup:
  - Ensure Affiliate Key and app identifier match integration app IDs.
- Duplicate transaction IDs:
  - Generate stable unique references (UUID/order ID strategy).
- Merchant currency mismatch:
  - Validate currency before checkout creation.
- Treating widget callback success as fully settled:
  - Confirm with backend checkout retrieval/webhook.
- Poor idempotency on webhook retries:
  - Store processed event/checkouts and deduplicate updates.