Sumup best practices

Skill sumup/sumup-skills/skills/sumup-best-practices

Agent Skills for teaching agents how to build with SumUp.

Install

npx -y skills add sumup/sumup-skills --skill sumup-best-practices

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Pick the right SumUp integration path and apply security best practices. Use when deciding between Hosted Checkout, Card Widget, Checkouts API, mobile SDKs, terminal SDKs, or Cloud API; choosing API key vs OAuth vs restricted keys; or reviewing SumUp integration security.

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.2 KB, as published. Nobody here has run it

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

Classify the request: terminal, online, or hybrid.
Choose the lowest-complexity viable path first:
- Prefer Hosted Checkout or Card Widget before custom orchestration.
- Prefer Cloud API for non-native Solo control.
Select auth model:
- API key for single-merchant server integrations.
- OAuth 2.0 for delegated or multi-merchant apps.
Confirm restricted access and affiliate prerequisites:
- payments scope activation where needed.
- Affiliate Key plus app/bundle identifier alignment for card-present.
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:

Chosen integration path with a brief why.
Credential model recommendation (API key vs OAuth) and scope requirements.
Security posture checklist for the chosen path.
Risks/trade-offs and when to pick a different path.
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.