paytriage

Liest einen Zahlungsgateway-Fehler und sagt dir, was er wahrscheinlich bedeutet, was du als Nächstes prüfen solltest und ob ein erneuter Versuch sicher ist.

Gib ihm eine Logzeile, eine Fehlermeldung oder eine ganze Logdatei. Es antwortet in einfacher Sprache statt mit einem Code, den du nachschlagen musst.

Keine Abhängigkeiten. Python 3.8 und höher. Funktioniert als CLI, als Bibliothek und als MCP-Server, den ein Agent aufrufen kann.

Warum

Support- und Implementierungsleute verbringen viel Zeit damit, response_code="51" in „Die Karte des Kunden hatte kein Geld, das ist nicht dein Fehler" zu übersetzen. Diese Übersetzung lebt in den Köpfen der Leute und in Lesezeichen-PDFs. Dieses Tool legt sie in eine Datei, die du lesen, durchsuchen und korrigieren kannst.

Der Timeout-Fall ist der wichtigste. Ein Timeout ist keine Ablehnung. Die Transaktion kann auf der anderen Seite bereits autorisiert sein, also ist ein blinder erneuter Versuch der Weg, jemanden doppelt zu belasten. paytriage sagt das jedes Mal deutlich.

Installation

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

Oder überspringe die Installation und führe es direkt mit python -m paytriage.cli aus.

Verwendung über die Befehlszeile

$ 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

Eine ganze Datei, zusammengefasst:

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

Füge --json zu jedem Aufruf hinzu, um maschinenlesbare Ausgabe zu erhalten.

Verwendung als Bibliothek

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

Verwendung als MCP-Server

Der Server spricht JSON-RPC über stdio und stellt ein Tool bereit, triage_payment_error, damit ein Agent ihm einen Fehler übergeben und strukturierte Ausgabe zurückbekommen kann.

python -m paytriage.mcp_server

Claude Desktop- oder Claude Code-Konfiguration:

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

Was abgedeckt wird

Vierundzwanzig Signaturen in sechs Familien:

• Ablehnungen: unzureichende Deckung, nicht honorieren, abgelaufene Karte, Karte einziehen, ungültige Nummer

• Verifizierung: AVS-Abweichung, CVV-Abweichung

• Transport: TLS-Handshake, Zertifikat abgelaufen oder nicht vertrauenswürdig, Timeout, Verbindung abgelehnt oder zurückgesetzt, DNS

• API: 401, 403, 429, 5xx

• Nachrichtenformat: XML-Parse, JSON-Parse, Signatur- oder HMAC-Abweichung, fehlendes Pflichtfeld

• Geschäftsregeln: doppelte Transaktion, nicht unterstützte Währung, ungültiger Betrag, ungültiges Token

Der Abgleich erfolgt anhand des Antwortcodes, falls einer vorhanden ist, andernfalls anhand von Mustern. Eine Zeile kann mehr als eine Signatur treffen, und die Ergebnisse werden nach Schweregrad absteigend zurückgegeben.

Was es nicht ist

• Kein Betrugs-Scoring und keine Risiko-Engine.

• Nicht mit einem Gateway verbunden. Es liest Text, den du bereits hast, und führt keine Netzwerkaufrufe durch.

• Nicht vollständig. Es ist ein Helfer für die erste Einschätzung. Die eigene Dokumentation des Emittenten ist weiterhin maßgeblich für jeden spezifischen Code.

• Kein Entscheidungsträger. Nichts hier sollte automatisch eine Zahlung erneut versuchen.

Hinzufügen einer Signatur

Alles lebt in einer Tabelle in paytriage/signatures.py. Eine Signatur ist ein Muster oder eine Reihe von Codes, plus Ursache, Lösung und Schweregrad. Füge einen Eintrag hinzu, füge einen Test hinzu, öffne einen Pull-Request. Korrekturen am bestehenden Wortlaut sind genauso willkommen wie neue Einträge.

Tests

python -m unittest discover -s tests -t .

23 Tests, kein Netzwerk, keine herunterzuladenden Fixtures.

Lizenz

MIT. Siehe LICENSE.