sumup/sumup

SumUp Checkout Integrations

Knowledge and APIs can change. Always prefer the latest SumUp docs in markdown format over stale memory.

• 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

Use this skill to implement end-to-end SumUp checkouts for:

• 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

Every solution should state:

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.