claude-skills/

Anthropic公式スキル・プラグインの日本語ディレクトリ

last sync 22h ago
スキルOfficialdevelopment

🔧sumup-debug

プラグイン
sumup
ライセンス
Apache-2.0
ソース
GitHub で見る ↗

説明

SumUpの一般的なインテグレーション障害をトラブルシューティングします。 次のような場合に使用: - SumUpのHMAC署名チェックが失敗する - チェックアウトセッションが期限切れになる - スコープが有効化されていない - ウィジェットのマウントがブロックされる - アフィリエイトキーが一致しない - `checkout_reference` が衝突する

原文を表示

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.

ユースケース

  • ✓HMAC署名チェックが失敗するとき
  • ✓チェックアウトセッションが期限切れになる
  • ✓スコープが有効化されていないとき
  • ✓ウィジェットのマウントがブロックされるとき
  • ✓アフィリエイトキーが一致しないとき

本文（日本語訳）

SumUp トラブルシューティング プレイブック

SumUp インテグレーションの障害診断および修復を行う場合に使用。

迅速なトリアージマトリクス

  1. 症状を分類する:

    • 認証／署名エラー
    • チェックアウトの作成／処理エラー
    • Widget／クライアントサイドのマウントまたはフローエラー
    • 非同期の不整合（UI では成功、バックエンドの状態では失敗）

  2. 証拠を収集する:

    • リクエスト／レスポンスのペイロード（サニタイズ済み）、HTTP ステータス、エラーコード／メッセージ
    • checkout id、merchant code、checkout_reference
    • Webhook の配信 ID および署名検証の結果

  3. 本番環境の動作を変更する前に、Sandbox で再現する。

よくある障害と修正方法

HMAC 署名の不一致（x-payload-signature）

症状:

  • すべてのイベント、または断続的に Webhook の検証が失敗する。

原因として考えられるもの:

  • ボディパーサーが検証前にペイロードを変更している。
  • Webhook シークレットと環境の組み合わせが誤っている。
  • ダイジェストが Raw ボディのバイト列ではなく計算されている。

修正:

  • Raw リクエストボディのバイト列を使って検証する。
  • 正確に設定されたシークレットを用いた HMAC SHA-256 を確認する。
  • シークレットが同一の Merchant／環境に属していることを確認する。

確認:

  • リプレイしたペイロードおよびライブ Sandbox の Webhook において、署名検証が通ること。

チェックアウト／セッションの有効期限切れ

症状:

  • 遅延後の決済試行が失敗する、チェックアウトのステータスが古い、またはタイムアウトフローが発生する。

原因として考えられるもの:

  • チェックアウトが有効期間を超えて Pending 状態のまま放置されている。
  • フロントエンドが期限切れの checkout id を使ってリトライしている。

修正:

  • リトライごとに新しいチェックアウトを作成する。
  • フロントエンドに、新しいチェックアウトをリクエストするタイムアウト処理を追加する。

確認:

  • リトライフローが必ず新しい checkout id／reference を使用し、Sandbox で成功すること。

スコープの未有効化または認証の不一致

症状:

  • 有効なクレデンシャルにもかかわらず 401／403 レスポンスが返る。

原因として考えられるもの:

  • payments などの必須スコープが不足している。
  • OAuth が必要な箇所で API キーを使用している、またはその逆。

修正:

  • インテグレーション種別に応じた認証モデルを確認する。
  • 必要なスコープをリクエスト／有効化し、必要に応じてトークン／キーを再発行する。

確認:

  • 最小権限の有効なクレデンシャルで、以前失敗していたエンドポイントが成功すること。

通貨と Merchant の不一致

症状:

  • 通貨または Merchant の制約によりチェックアウトが拒否される。

原因として考えられるもの:

  • チェックアウトの通貨が当該 Merchant で有効化されていない。
  • マルチ Merchant 環境で誤った Merchant が選択されている。

修正:

  • チェックアウト作成前に Merchant と通貨を検証する。
  • バックエンドのバリデーション層でマッピングルールを適用する。

確認:

  • 無効な組み合わせが早期にブロックされ、有効な組み合わせが処理されること。

アフィリエイトキー／アプリ識別子の不一致

症状:

  • カード対面フローが失敗する、または正常に初期化できない。

原因として考えられるもの:

  • Bundle ID／App ID がアフィリエイトキーの設定と一致していない。
  • カード対面リクエストにアフィリエイトのメタデータが含まれていない。

修正:

  • アプリ識別子をアフィリエイトキーの設定に合わせる。
  • ターミナル／クラウドフローに必要なアフィリエイトデータを含める。

確認:

  • Sandbox／テストデバイスにおいて、デバイス／リーダーのチェックアウトパスが初期化から完了まで正常に動作すること。

checkout_reference の重複

症状:

  • チェックアウトの結果が重複または競合する、消込（reconciliation）で混乱が生じる。

原因として考えられるもの:

  • Reference の生成が一意でない。
  • リトライロジックが冪等性の保護なしに古い Reference を再利用している。

修正:

  • 論理的な決済インテントごとに、一意かつ決定論的な Reference を生成する。
  • 重複検出と安全なリトライ挙動を追加する。

確認:

  • 重複した試行が拒否されるか、二重処理なく正常に消込されること。

カード Widget がブロックされる、またはマウントされない

症状:

  • Widget のレンダリングに失敗する、または error／初期化失敗が発生する。

原因として考えられるもの:

  • CSP またはドメインポリシーによってスクリプトがブロックされている。
  • checkout id が無効、または環境が一致していない。
  • フロントエンドの初期化でレースコンディションが発生している。

修正:

  • CSP および JS origins の設定で SumUp スクリプトの origin を許可する。
  • checkout id の環境とライフサイクルを確認する。
  • スクリプトの読み込みと DOM の準備完了後にのみマウントする。

確認:

  • Widget が安定してマウントされ、テスト決済を完了できること。

回答に必要な要件

各デバッグ回答には以下を含めること:

  1. 信頼度順にランク付けされた、最も可能性の高い根本原因。
  2. 各仮説を確認または否定するための、最小限の再現可能なチェック手順。
  3. リスクの低いロールアウトアドバイスを含む、具体的な修正手順。
  4. 修正後の確認チェックリスト。
  5. 再発防止のためのモニタリング／ロギングの改善提案。
原文（English）を表示

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.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。