sumup-debug

name	sumup-debug
description	Troubleshoot common SumUp integration failures. Use when SumUp HMAC signature checks fail, checkout sessions expire, scopes aren't activated, widget mount is blocked, affiliate keys don't match, or `checkout_reference` collides.
license	Apache-2.0

SumUp Troubleshooting Playbook

Use this skill for diagnosis and remediation of failing SumUp integrations.

Fast Triage Matrix

1. Classify symptom:
   • Auth/signature error
   • Checkout creation/processing error
   • Widget/client-side mount or flow error
   • Async mismatch (success in UI, failure in backend state)
2. Capture evidence:
   • request/response payloads (sanitized), HTTP status, error code/message
   • checkout id, merchant code, checkout_reference
   • webhook delivery id and signature verdict
3. Reproduce in sandbox before changing production behavior.

Common Failures and Fixes

HMAC signature mismatch (x-payload-signature)

Symptoms:

• Webhook verification fails for all events or intermittently.

Likely causes:

• Body parser mutates payload before verification.
• Wrong webhook secret/environment pair.
• Digest computed with non-raw body bytes.

Fix:

• Verify against raw request body bytes.
• Ensure HMAC SHA-256 with exact configured secret.
• Confirm secret belongs to the same merchant/environment.

Verify:

• Signature validation passes for replayed payload and for live sandbox webhook.

Expired checkout/session window

Symptoms:

• Payment attempt fails after delay, stale checkout status, or timeout flow.

Likely causes:

• Checkout left pending beyond validity window.
• Frontend retries with expired checkout id.

Fix:

• Create a new checkout for each retry attempt.
• Add frontend timeout handling that requests a fresh checkout.

Verify:

• Retried flow always uses new checkout id/reference and succeeds in sandbox.

Missing scope activation or auth mismatch

Symptoms:

• 401/403 responses despite valid credentials.

Likely causes:

• Missing payments or other required scope.
• API key used where OAuth is required, or vice versa.

Fix:

• Confirm auth model for integration type.
• Request/enable required scopes and re-issue token/key as needed.

Verify:

• Previously failing endpoint succeeds with least-privilege valid credentials.

Currency and merchant mismatch

Symptoms:

• Checkout rejected for currency or merchant constraints.

Likely causes:

• Checkout currency not enabled for merchant.
• Wrong merchant selected in multi-merchant context.

Fix:

• Validate merchant and currency before checkout creation.
• Enforce mapping rules in backend validation layer.

Verify:

• Invalid combinations are blocked early; valid combinations process.

Affiliate key / app identifier mismatch

Symptoms:

• Card-present flows fail or cannot initialize correctly.

Likely causes:

• Bundle ID/app ID does not match affiliate key configuration.
• Missing affiliate metadata in card-present requests.

Fix:

• Align app identifiers with affiliate key setup.
• Include required affiliate data for terminal/cloud flows.

Verify:

• Device/reader checkout path initializes and completes in sandbox/test device.

Duplicate checkout_reference

Symptoms:

• Duplicate or conflicting checkout outcomes, reconciliation confusion.

Likely causes:

• Non-unique reference generation.
• Retry logic reuses stale reference without idempotency safeguards.

Fix:

• Generate unique deterministic references per logical payment intent.
• Add duplicate detection and safe retry behavior.

Verify:

• Duplicate attempts are rejected or reconciled without double fulfillment.

Card Widget blocked or not mounting

Symptoms:

• Widget fails to render or emits error/init failures.

Likely causes:

• Script blocked by CSP or domain policy.
• Invalid checkout id or environment mismatch.
• Frontend initialization race conditions.

Fix:

• Allow required SumUp script origin in CSP and JS origins config.
• Confirm checkout id environment and lifecycle.
• Mount only after script load and DOM ready.

Verify:

• Widget consistently mounts and can complete test payments.

Required Response Contract

For each debugging answer, include:

1. Most likely root cause ranked by confidence.
2. Minimal reproducible check to confirm/disprove each hypothesis.
3. Exact fix steps with low-risk rollout advice.
4. Post-fix verification checklist.
5. Any monitoring/logging improvements to prevent recurrence.