mcpField
S
sumup-best-practices

sumup-best-practices

github.com/sumupDevelopment560 installsUpdated 3w ago
Repository

About sumup-best-practices

A skill for AI agents making architecture and security decisions about SumUp integrations. It helps developers choose among in-person, online, and hybrid payment paths and assess credentials and operational constraints; it is not an implementation walkthrough.

Key features

  1. 01Classify terminal, online, or hybrid needs
  2. 02Choose a suitable SumUp integration path
  3. 03Compare API key and OAuth credentials
  4. 04Review payment security and operational constraints
  5. 05Require risks and a validation plan

Use cases

  1. 01Select an approach for in-person or online payments
  2. 02Choose credentials for single- or multi-merchant apps
  3. 03Assess webhook retries and idempotent handling
  4. 04Plan validation before a payment rollout

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/sumup/sumup-skills --skill sumup-best-practices

After installing, type/sumup-best-practicesin Claude Code to confirm it loaded.

Bundled filesagents/openai.yamlassets/small-logo.svg

Details

From the project README

SumUp Integration Decisions and Best Practices

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

Use this skill for architecture and security decisions, not implementation walkthroughs.

Quick Decision Tree

Need to accept a payment?
├─ In-person (card-present)
│  ├─ Native mobile app controls reader directly -> iOS Terminal SDK / Android Reader SDK
│  ├─ POS/backend controls Solo from non-native environment -> Cloud API
│  └─ Legacy handoff to SumUp app is mandatory -> Payment Switch
└─ Online (card-not-present)
   ├─ Fastest redirect flow, no embed required -> Hosted Checkout
   ├─ Embedded payment form with low PCI scope -> Card Widget
   ├─ Mobile app checkout UX -> Swift Checkout SDK / React Native SDK
   ├─ Save card and charge later -> Customers + tokenization
   └─ Custom orchestration needs -> Checkouts API + 3DS + webhooks

Start Here

  1. Classify the request: terminal, online, or hybrid.
  2. Choose the lowest-complexity viable path first:
    • Prefer Hosted Checkout or Card Widget before custom orchestration.
    • Prefer Cloud API for non-native Solo control.
  3. Select auth model:
    • API key for single-merchant server integrations.
    • OAuth 2.0 for delegated or multi-merchant apps.
  4. Confirm restricted access and affiliate prerequisites:
    • payments scope activation where needed.
    • Affiliate Key plus app/bundle identifier alignment for card-present.
  5. Confirm operational constraints:
    • Currency/merchant alignment
    • Webhook endpoint readiness and idempotency
    • Legacy compatibility requirements

Non-Negotiable Rules

  • Keep API keys and OAuth secrets server-side only.
  • Never handle raw PAN/card details directly.
  • Create online checkouts server-to-server.
  • Prefer hosted/widget/SDK checkout UI over custom card handling.
  • Avoid deprecated endpoints.
  • Use unique transaction references (checkout_reference, foreignTransactionId, or equivalent).
  • Treat webhook callbacks as signals and verify final state via API before fulfillment.
  • Assume retries and duplicate deliveries; enforce idempotent backend handling.

Required Response Contract

When giving guidance, always return:

  1. Chosen integration path with a brief why.
  2. Credential model recommendation (API key vs OAuth) and scope requirements.
  3. Security posture checklist for the chosen path.
  4. Risks/trade-offs and when to pick a different path.
  5. Minimum validation plan before production rollout.

Hand-off to Implementation Skills

  • Use sumup for end-to-end implementation steps.
  • Use upgrade-sumup for SDK/API migrations.
  • Use sumup-debug for failure diagnosis.
  • Use sumup-testing for sandbox and QA setup.

Comments

Markdown supported