Skip to main content
Glama

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.

Related MCP server: error-broker

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.

Available Tools

1 tool
triage_payment_errorA

Triage a payment gateway error string or log excerpt. Returns the likely cause, what to check next, a severity, and whether a retry is safe.

Inputs: text (required), multiline.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clearly singular and distinct.

    Naming Consistency5/5

    The single tool 'triage_payment_error' follows a clear verb_noun pattern, consistent with best practices. No inconsistency exists in a one-tool set.

    Tool Count3/5

    The tool count is at the thin end of the spectrum (1 tool), which feels minimal for a server, but the narrow scope of payment error triage makes it borderline acceptable.

    Completeness5/5

    The single tool fully addresses the stated purpose of triaging payment errors, providing cause, next steps, severity, and retry safety—no obvious gaps for this focused domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Classifies agent errors and provides clear recovery actions (retry, escalate) with configurable categories and strategies, plus MCP tools for direct agent use.
      8 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to scan payment endpoints for safety, returning a letter grade (A–F) and verdict before authorizing payments.
      2
      34 npm
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to safely integrate cross-border payments by providing structured payment knowledge, deterministic validation of idempotency, security, and state-machine rules, webhook testing, executable pytest generation, and diagnosis for Python/FastAPI Checkout projects.
      -