paytriage

支払いゲートウェイのエラーを読み取り、それが何を意味するか、次に何を確認すべきか、再試行が安全かどうかを教えてくれます。

ログ行、エラー文字列、ログファイル全体を指定できます。調べに行かなければならないコードではなく、平易な言葉で答えます。

依存関係なし。Python 3.8以上。CLI、ライブラリ、エージェントが呼び出せるMCPサーバーとして動作します。

なぜ

サポート担当者や実装担当者は、response_code="51" を「顧客のカードに残高がなかった、これはあなたのバグではない」に変換するのに多くの時間を費やしています。その変換は人々の頭の中や、ブックマークされたPDFに存在します。これを、読んで、grepして、修正できるファイルに置きます。

タイムアウトのケースが最も重要です。タイムアウトは拒否ではありません。取引はすでに相手側で承認されている可能性があるため、盲目的な再試行は二重請求の原因になります。paytriageはそのたびにそれを明確に伝えます。

インストール

git clone https://github.com/Flyingmiata-droid/paytriage.git
cd paytriage
pip install -e .

または、インストールをスキップして、python -m paytriage.cli でその場で実行します。

コマンドラインから使う

$ paytriage 'AUTH DECLINED response_code="51" insufficient funds'

  [low] Insufficient funds  (decline)
    cause: The issuer declined the authorization because the account did not have
           enough available balance or credit.
    check: Nothing to fix on the integration side. Ask the cardholder to use
           another card or retry later.
    matched response code: 51
    safe to retry: no

ファイル全体をまとめて:

$ paytriage -f examples/gateway.log --summary

lines: 11  matched: 9  unmatched: 2

by severity:
  low: 2
  medium: 3
  high: 2
  critical: 2

by signature:
  decline.insufficient_funds: 1
  transport.tls_handshake: 1
  format.signature_mismatch: 1
  ...

任意の呼び出しに --json を追加すると、機械可読な出力が得られます。

ライブラリとして使う

from paytriage import triage_line

result = triage_line("SSLError: handshake failure tlsv1 alert protocol version")

result.severity          # "critical"
result.retryable         # True
result.findings[0].label # "TLS handshake failure"
result.findings[0].fix   # what to check

MCPサーバーとして使う

サーバーはstdio上でJSON-RPCを話し、triage_payment_error という1つのツールを公開するので、エージェントはエラーを渡して構造化された出力を得ることができます。

python -m paytriage.mcp_server

Claude DesktopまたはClaude Codeの設定:

{
  "mcpServers": {
    "paytriage": {
      "command": "python",
      "args": ["-m", "paytriage.mcp_server"]
    }
  }
}

カバー範囲

6つのファミリーにわたる24のシグネチャ:

• 拒否: 残高不足、do not honor、有効期限切れカード、カード回収、無効な番号

• 検証: AVS不一致、CVV不一致

• トランスポート: TLSハンドシェイク、証明書の有効期限切れまたは信頼できない、タイムアウト、接続拒否またはリセット、DNS

• API: 401、403、429、5xx

• メッセージ形式: XMLパース、JSONパース、署名またはHMAC不一致、必須フィールド欠落

• ビジネスルール: 重複取引、未対応通貨、不正な金額、無効なトークン

マッチングは、レスポンスコードが存在する場合はそれに基づき、それ以外はパターンに基づきます。1行が複数のシグネチャにマッチすることがあり、結果は深刻度の高い順に返されます。

そうではないもの

• 不正検知スコアリングでも、リスクエンジンでもありません。

• どのゲートウェイにも接続しません。既に持っているテキストを読み、ネットワーク呼び出しは行いません。

• 網羅的ではありません。これは一次トリアージのヘルパーです。特定のコードに関する権威は、依然として発行元自身のドキュメントです。

• 意思決定者ではありません。ここにあるものは、単独で支払いを自動再試行すべきではありません。

シグネチャの追加

すべては paytriage/signatures.py の1つのテーブルにあります。シグネチャは、パターンまたはコードのセットに加えて、原因、修正、深刻度です。エントリを追加し、テストを追加し、プルリクエストを開いてください。既存の文言の修正も、新しいエントリと同じくらい歓迎します。

テスト

python -m unittest discover -s tests -t .

23テスト、ネットワークなし、ダウンロードするフィクスチャなし。

ライセンス

MIT。LICENSE を参照してください。