paytriage

Reads a payment gateway error and tells you what it probably means, what to check next, and whether retrying is safe.

Point it at a log line, an error string, or a whole log file. It answers in plain language instead of a code you have to go look up.

No dependencies. Python 3.8 and up. Works as a CLI, as a library, and as an MCP server an agent can call.

Why

Support and implementation people spend a lot of time turning response_code="51" into "the customer's card did not have the money, this is not your bug." That translation lives in people's heads and in bookmarked PDFs. This puts it in a file you can read, grep, and correct.

The timeout case is the one that matters most. A timeout is not a decline. The transaction may already be authorized on the other side, so a blind retry is how you double-charge someone. paytriage says that out loud every time.

Install

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

Or skip installing and run it in place with python -m paytriage.cli.

Use it from the command line

$ 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

A whole file, rolled up:

$ 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
  ...

Add --json to any call to get machine-readable output.

Use it as a library

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

Use it as an MCP server

The server speaks JSON-RPC over stdio and exposes one tool, triage_payment_error, so an agent can hand it an error and get structured output back.

python -m paytriage.mcp_server

Claude Desktop or Claude Code config:

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

What it covers

Twenty four signatures across six families:

• Declines: insufficient funds, do not honor, expired card, pick up card, invalid number
• Verification: AVS mismatch, CVV mismatch
• Transport: TLS handshake, certificate expired or untrusted, timeout, connection refused or reset, DNS
• API: 401, 403, 429, 5xx
• Message format: XML parse, JSON parse, signature or HMAC mismatch, missing required field
• Business rules: duplicate transaction, unsupported currency, bad amount, invalid token

Matching is by response code where one is present, and by pattern otherwise. A line can match more than one signature, and results come back worst first.

What it is not

• Not fraud scoring, and not a risk engine.
• Not connected to any gateway. It reads text you already have, and it makes no network calls.
• Not exhaustive. It is a first-pass triage helper. The issuer's own documentation is still the authority on any specific code.
• Not a decision maker. Nothing here should auto-retry a payment on its own.

Adding a signature

Everything lives in one table in paytriage/signatures.py. A signature is a pattern or a set of codes, plus the cause, the fix, and a severity. Add an entry, add a test, open a pull request. Corrections to the existing wording are just as welcome as new entries.

Tests

python -m unittest discover -s tests -t .

23 tests, no network, no fixtures to download.

License

MIT. See LICENSE.