# 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).