paytriage

Читает ошибку платёжного шлюза и объясняет, что она, скорее всего, означает, что проверить дальше и безопасно ли повторять попытку.

Скармливаете ему строку лога, текст ошибки или целый файл лога. Он отвечает обычным языком, а не кодом, который нужно искать в справочнике.

Без зависимостей. Python 3.8 и выше. Работает как CLI, как библиотека и как MCP сервер, к которому может обратиться агент.

Зачем

Специалисты поддержки и разработчики тратят много времени на превращение response_code="51" в «на карте клиента не было денег, это не ваша ошибка». Этот перевод живёт в головах людей и в закладках на PDF. Этот инструмент кладёт его в файл, который можно читать, искать по нему и исправлять.

Случай с таймаутом — самый важный. Таймаут — это не отказ. Транзакция могла уже быть авторизована на той стороне, так что слепой повтор — это способ дважды списать деньги с клиента. paytriage проговаривает это каждый раз.

Установка

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

Или пропустите установку и запустите на месте с помощью python -m paytriage.cli.

Использование из командной строки

$ 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

Целый файл, сводкой:

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

Добавьте --json к любому вызову, чтобы получить машиночитаемый вывод.

Использование как библиотеки

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

Использование как MCP сервера

Сервер говорит на JSON-RPC через stdio и предоставляет один инструмент, triage_payment_error, чтобы агент мог передать ему ошибку и получить структурированный ответ.

python -m paytriage.mcp_server

Конфигурация Claude Desktop или Claude Code:

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

Что покрывает

Двадцать четыре сигнатуры в шести семействах:

• Отказы: недостаточно средств, do not honor, карта просрочена, заберите карту, неверный номер

• Верификация: несовпадение AVS, несовпадение CVV

• Транспорт: рукопожатие TLS, сертификат истёк или недоверенный, таймаут, соединение отклонено или сброшено, DNS

• API: 401, 403, 429, 5xx

• Формат сообщения: разбор XML, разбор JSON, несовпадение подписи или HMAC, отсутствует обязательное поле

• Бизнес-правила: повторная транзакция, неподдерживаемая валюта, неверная сумма, неверный токен

Сопоставление идёт по коду ответа, если он есть, и по шаблону в остальных случаях. Строка может соответствовать нескольким сигнатурам сразу, и результаты возвращаются от худшего к лучшему.

Чем это не является

• Не скоринг фрода и не риск-движок.

• Не подключено ни к какому шлюзу. Оно читает текст, который у вас уже есть, и не совершает сетевых вызовов.

• Не исчерпывающий справочник. Это инструмент первичной триажной помощи. Документация самого эмитента остаётся авторитетным источником по любому конкретному коду.

• Не принимает решений. Ничто здесь не должно само по себе повторять платёж.

Добавление сигнатуры

Всё живёт в одной таблице в paytriage/signatures.py. Сигнатура — это шаблон или набор кодов, плюс причина, решение и серьёзность. Добавьте запись, добавьте тест, откройте pull request. Исправления существующих формулировок так же приветствуются, как и новые записи.

Тесты

python -m unittest discover -s tests -t .

23 теста, без сети, без загрузки фикстур.

Лицензия

MIT. См. LICENSE.