SumUp Checkout Integrations

• Docs root:

  https://developer.sumup.com/

• LLM entrypoint:

  https://developer.sumup.com/llms.txt

• Markdown page format example:

  https://developer.sumup.com/terminal-payments/cloud-api/index.md

• Terminal payments (native mobile SDKs, Cloud API for Solo, or Payment Switch)
• Online payments (Card Widget and API-orchestrated checkout flow)

Quick Decision Tree

Need to accept a payment?
├─ In-person (card-present) → terminal
│  ├─ Native mobile app + direct reader flow → terminal/mobile (iOS SDK or Android Reader SDK)
│  ├─ Non-native POS/backend controls Solo reader → terminal/platform-agnostic (Cloud API)
│  └─ Legacy app handoff to SumUp app explicitly required → terminal/legacy-lightweight (Payment Switch)
└─ Online (card-not-present) → online
   ├─ Fastest secure integration, hosted/embedded UI acceptable → online/low-complexity (Card Widget)
   └─ Custom orchestration and async lifecycle handling required → online/custom (Checkouts API + 3DS + webhooks)

Start Here

1. Classify the requested flow:

   • terminal

     : in-person card-present payment

   • online

     : e-commerce/web/app card-not-present payment

   • hybrid

     : both (for example, web checkout + in-store Solo)
2. Pick integration path:

   • terminal/mobile

     : iOS SDK or Android Reader SDK

   • terminal/platform-agnostic

     : Cloud API with Solo readers

   • terminal/legacy-lightweight

     : Payment Switch

   • online/low-complexity

     : Card Widget

   • online/custom

     : Checkouts API + 3DS + webhooks
3. Confirm credentials and environment:
   • API key or OAuth access token
   • Affiliate Key for card-present flows
   • Merchant code and currency alignment
   • Sandbox merchant account for non-production testing
4. Ask for missing critical inputs before implementation:
   • integration channel (mobile SDK, Cloud API, Card Widget, or API-orchestrated)
   • target market/currency and merchant code
   • auth model (API key vs OAuth)
   • webhook endpoint and idempotency strategy
   • existing constraints (legacy compatibility, migration, PCI scope)
5. Apply the implementation pattern from

   references/checkout-playbook.md

   .
6. Use

   references/README.md

   and open only the single most relevant entrypoint for the request.

Non-Negotiable Rules

• Keep secret API keys and OAuth client secrets server-side only.
• Never handle raw PAN/card data directly.
• Create online checkouts server-to-server.
• Prefer Card Widget and SDK-provided checkout experiences to avoid handling raw card details.
• For card-present integrations, include the Affiliate Key and ensure app identifiers match the key setup.
• Avoid Payment Switch unless the user explicitly requests it or has a hard legacy constraint.
• Use unique transaction references (

  checkout_reference

  ,

  foreignTransactionId

  , or equivalent) to prevent duplicates and improve reconciliation.
• Do not use endpoints marked as deprecated.
• Prefer endpoints that accept

  merchant_code

  as an explicit parameter when equivalent alternatives exist.
• Treat webhook events as notifications only; verify state through API reads.
• After a widget/client callback reports success, always verify final checkout state on the backend before confirming order/payment success.

Implementation Workflow

1. Set up auth and merchant context.
2. Create checkout request with unique reference and correct currency.
3. Complete checkout via chosen channel:
   • terminal SDK checkout call
   • Cloud API reader checkout
   • Card Widget
   • direct checkout processing flow
4. Handle async outcomes:
   • SDK callback / activity result / event stream
   • 3DS

     next_step

     redirect flow
   • webhook delivery + API verification
5. Return normalized result (status, transaction identifiers, retry guidance).

Required Response Contract

1. Chosen integration path and why.
2. End-to-end sequence (server, client, webhook/async verification).
3. Exact endpoint set, confirming no deprecated endpoints and preference for

   merchant_code

   -accepting endpoints.
4. Failure and retry handling (timeouts, duplicate refs, webhook retries).
5. Test plan for success, deliberate failure, and reconciliation checks.

Validation Checklist

• Test and capture both successful payment and deliberate failure case (

  amount = 11

  in test mode).
• Verify behavior for duplicate transaction references.
• Verify timeout/session expiry behavior in the selected checkout path.
• Verify webhook retries and idempotent processing.
• Verify reconciliation fields are stored (checkout id, transaction id/code, merchant code, reference).

References

• Use

  references/README.md

  to pick the right reference file.
• Each reference file includes its own canonical markdown docs URL. Prefer that URL over stale memory.