Skip to main content
Glama
README.md
# 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

```bash
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

```bash
$ 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:

```bash
$ 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

```python
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.

```bash
python -m paytriage.mcp_server
```

Claude Desktop or Claude Code config:

```json
{
  "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

```bash
python -m unittest discover -s tests -t .
```

23 tests, no network, no fixtures to download.

## License

MIT. See [LICENSE](LICENSE).

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