sumup-debug

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

SumUp の連携に関する障害の診断と修正には、このスキルを使用します。

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

1. 症状を分類します：
   • 認証／署名エラー
   • チェックアウトの作成／処理エラー
   • ウィジェット／クライアント側のマウントまたはフローエラー
   • 非同期処理の不一致（UI では成功、バックエンドの状態では失敗）
2. 証拠を収集します：
   • リクエスト／レスポンスのペイロード（機密情報を除去したもの）、HTTP ステータス、エラーコード／メッセージ
   • チェックアウト ID、加盟店コード、checkout_reference
   • Webhook 配信 ID と署名の検証結果
3. 本番環境の動作を変更する前に、サンドボックスで再現します。

よくある障害と修正方法

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

症状：

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

考えられる原因：

• ボディーパーサーが検証前にペイロードを変更しています。
• Webhook シークレットと環境の組み合わせが誤っています。
• 生のボディーバイト列を使わずにダイジェストを計算しています。

修正方法：

• リクエストボディーの生バイト列を使って検証します。
• 設定済みの正確なシークレットを使用して HMAC SHA-256 を行います。
• シークレットが同じ加盟店／環境に属していることを確認します。

確認方法：

• 再送したペイロードと、サンドボックスのライブ Webhook の両方で署名検証に成功します。

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

症状：

• 遅延後に支払いが失敗する、チェックアウトの状態が古いままになる、またはタイムアウトフローになる。

考えられる原因：

• チェックアウトが有効期間を超えて保留状態になっています。
• フロントエンドが期限切れのチェックアウト ID で再試行しています。

修正方法：

• 再試行のたびに新しいチェックアウトを作成します。
• 新しいチェックアウトを要求するフロントエンドのタイムアウト処理を追加します。

確認方法：

• 再試行フローでは常に新しいチェックアウト ID／参照情報を使用し、サンドボックスで成功します。

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

症状：

• 認証情報が有効であるにもかかわらず、401/403 レスポンスが返されます。

考えられる原因：

• payments またはその他の必須スコープがありません。
• OAuth が必要な箇所で API キーを使用している、またはその逆です。

修正方法：

• 連携の種類に応じた認証方式を確認します。
• 必須スコープをリクエスト／有効化し、必要に応じてトークン／キーを再発行します。

確認方法：

• 以前失敗していたエンドポイントが、最小権限の有効な認証情報で成功します。

通貨と加盟店の不一致

症状：

• 通貨または加盟店の制約により、チェックアウトが拒否されます。

考えられる原因：

• 加盟店でチェックアウトの通貨が有効になっていません。
• 複数加盟店のコンテキストで誤った加盟店が選択されています。

修正方法：

• チェックアウトの作成前に、加盟店と通貨を検証します。
• バックエンドの検証レイヤーでマッピングルールを適用します。

確認方法：

• 無効な組み合わせは早い段階でブロックされ、有効な組み合わせは処理されます。

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

症状：

• カード提示型のフローが失敗する、または正しく初期化できません。

考えられる原因：

• バンドル ID／アプリ ID がアフィリエイトキーの設定と一致していません。
• カード提示型のリクエストにアフィリエイトメタデータがありません。

修正方法：

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

確認方法：

• デバイス／リーダーのチェックアウト経路が初期化され、サンドボックス／テストデバイスで完了します。

checkout_reference の重複

症状：

• チェックアウト結果の重複や競合が発生し、照合が困難になります。

考えられる原因：

• 参照情報が一意に生成されていません。
• 冪等性を確保せず、再試行ロジックが古い参照情報を再利用しています。

修正方法：

• 論理的な支払い意図ごとに、一意で決定的な参照情報を生成します。
• 重複検出と安全な再試行の動作を追加します。

確認方法：

• 重複した試行は、二重の履行を発生させることなく拒否または照合されます。

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

症状：

• ウィジェットが描画されない、または error／初期化エラーが発生します。

考えられる原因：

• CSP またはドメインポリシーによってスクリプトがブロックされています。
• チェックアウト ID が無効であるか、環境が一致していません。
• フロントエンドの初期化で競合状態が発生しています。

修正方法：

• CSP と JS オリジン設定で、必要な SumUp スクリプトのオリジンを許可します。
• チェックアウト ID の環境とライフサイクルを確認します。
• スクリプトの読み込みと DOM の準備が完了してからマウントします。

確認方法：

• ウィジェットが一貫してマウントされ、テスト支払いを完了できます。

必須の回答要件

デバッグの回答には、次の内容を含めてください。

1. 信頼度の高い順に並べた、最も可能性の高い根本原因。
2. 各仮説を確認または否定するための、最小限の再現確認。
3. リスクを抑えた段階的な展開に関するアドバイスを含む、具体的な修正手順。
4. 修正後の確認チェックリスト。
5. 再発防止のための、モニタリングやログ記録の改善点。