sumup-debug skill
✓ VerifiedDiagnose and resolve SumUp payment integration failures including checkout errors, callback verification, and merchant mismatches.
- GitHub stars
- 6
- Files
- 4
- Last commit
- Nov 4, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the sumup-debug skill do?
sumup-debug is an agent skill. Diagnose and resolve SumUp payment integration failures including checkout errors, callback verification, and merchant mismatches.
Summary generated from the skill's SKILL.md.
About the sumup-debug skill
Developers troubleshooting SumUp payment integration failures use this skill to diagnose issues ranging from checkout errors and callback verification to merchant or currency mismatches. It helps identify the root cause of problems within online checkouts, widgets, SDKs, or the Cloud API by inspecting sanitized request and response evidence. An agent should load this tool when a payment flow fails, such as when encountering 401 or 403 errors, timeout issues, or widget mounting failures.
The skill focuses on correlating specific data points like checkout_reference, transaction IDs, and timestamps to distinguish between confirmed causes and hypotheses. It provides structured investigation paths for symptoms like missing signing headers, duplicate payment attempts, or terminal initialization errors. By utilizing the current documentation index and SDK types, it assists in verifying contracts and ensuring that order states reconcile correctly with transaction results without requesting sensitive card data or secrets.
What an agent can do with it
- 1Resolve authentication and permission errorsInvestigate 401 or 403 status codes by verifying credential types, expiry, and required OAuth scopes.
- 2Fix webhook and callback issuesTroubleshoot missing signing headers or unexpected callback behavior in online notifications.
- 3Reconcile mismatched order statesDetermine why a Cloud API accepted a checkout but the order state does not match the payment success.
- 4Debug widget mounting failuresIdentify why a payment widget fails to appear by checking script loading, CSP, and DOM readiness.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the sumup-debug skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the sumup-debug skill in Plugin
/plugin marketplace add sumup/sumup-skills /plugin install sumup@sumup
Install the sumup-debug skill in Claude Code
~/.claude/skills/sumup-debug/SKILL.md
$ npx degit sumup/sumup-skills/skills/sumup-debug ~/.claude/skills/sumup-debugInstall the sumup-debug skill in Claude Code (project)
.claude/skills/sumup-debug/SKILL.md
$ npx degit sumup/sumup-skills/skills/sumup-debug .claude/skills/sumup-debugInstall the sumup-debug skill in Codex
~/.agents/skills/sumup-debug/SKILL.md
$ npx degit sumup/sumup-skills/skills/sumup-debug ~/.agents/skills/sumup-debugInstall the sumup-debug skill in Gemini CLI
~/.gemini/skills/sumup-debug/SKILL.md
$ npx degit sumup/sumup-skills/skills/sumup-debug ~/.gemini/skills/sumup-debugInstall the sumup-debug skill in Claude.ai
npx degit sumup/sumup-skills/skills/sumup-debug sumup-debug && zip -r sumup-debug.zip sumup-debug # claude.ai → Customize → Skills → + → Create skill → Upload a skill → sumup-debug.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachablesumup/sumup-skills/skills/sumup-debug is public and reachablegithub.com/sumup/sumup-skills/tree/HEAD/skills/sumup-debug ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-04github.com/sumup/sumup-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/sumup/sumup-skills/blob/HEAD/skills/sumup-debug/S ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/sumup/sumup-skills/blob/HEAD/skills/sumup-debug/S ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/sumup/sumup-skills/blob/HEAD/skills/sumup-debug/S ↗Finding
SKILL.md
View on GitHubDebug a SumUp Integration
Trace the reported failure before changing the integration. Inspect available code, the exact error, and sanitized request/response evidence; distinguish a confirmed cause from a hypothesis. Use the current documentation index and the installed SDK's types to verify the affected contract.
Gather only the evidence needed
Identify the channel (online checkout, widget, SDK, or Cloud API), authenticated merchant, and payment attempt. Useful correlation fields are checkout ID, checkout_reference, transaction ID/code, client_transaction_id, timestamps, HTTP status, and the returned error. Do not request raw card data, secrets, or full tokens.
Use a sanitized reproducer or sandbox where practical. Do not require a new sandbox setup before inspecting an existing failure, or invent a root cause when evidence is missing.
Investigate by symptom
| Symptom | Check and recovery |
|---|---|
401 / 403 |
Verify credential type, expiry, authenticated merchant, granted permissions, and any required OAuth scope verification. API keys and OAuth have different setup requirements. |
| Missing signing header or unexpected callback | Online notifications contain CHECKOUT_STATUS_CHANGED and checkout id; their published protocol does not specify HMAC signing. Retrieve the checkout and validate its expected identity, amount, currency, and final status. |
| Cloud API accepted checkout but order state differs | Acceptance is not payment success. Correlate solo.transaction.updated using payload.client_transaction_id, then reconcile the transaction. Do not substitute the online checkout status enum. |
Timeout, 5xx, lost result, or session expiry |
Retrieve the original payment first. If checkout creation returned no ID, list checkouts with the original checkout_reference. Keep pending or unknown results under reconciliation; start a new attempt only after checking the previous result. |
| Duplicate attempts or fulfillment | Trace references and state transitions. Use a distinct reference per confirmed new attempt and make order updates idempotent. Do not assume a reused reference prevents a second charge. |
| Merchant/currency rejection | Compare the actual credential, checkout merchant, and supported currency with the order; do not rely on the merchant selected in the Dashboard. |
| Terminal initialization or affiliate errors | Match Affiliate Key to the app/package identifier and include the metadata required by the selected SDK or Cloud API. Android Tap-to-Pay is a separate SDK. |
| Widget fails to mount | Check script loading, HTTPS/CSP, DOM readiness, checkout validity, and any origin settings documented for that integration. Inspect the actual browser error. |
For callback handling, see online webhooks and Cloud API results. For uncertain mutations, use the payment and refund recovery guide. Apply signature checks only where that product's current protocol requires them.
Fix and verify
Change the smallest part supported by the evidence. Recheck the failing path and any affected payment-state transition; verify repeated notifications cannot repeat fulfillment and an uncertain payment is not charged again. Use the project's tests and relevant sandbox/device checks, and distinguish local results from live-provider behavior.
Lead with the finding or the next check that will resolve the uncertainty. Include rollout or monitoring changes when the fix warrants them; a small diagnostic question does not need a full playbook.
Files in this skill
4sumup-debug skill questions
How do I install the sumup-debug skill in Claude Code?
Run npx degit sumup/sumup-skills/skills/sumup-debug ~/.claude/skills/sumup-debug. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the sumup-debug skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How should I handle 401 or 403 error responses in SumUp?
You should verify the credential type, expiry, the authenticated merchant, granted permissions, and any required OAuth scope verification, noting that API keys and OAuth have different requirements.
What should I do if a widget fails to mount?
Check script loading, HTTPS/CSP, DOM readiness, checkout validity, and any origin settings documented for that integration, while inspecting the actual browser error.
How can I prevent duplicate payments or fulfillment?
Trace references and state transitions, use a distinct reference per confirmed new attempt, and ensure order updates are idempotent.