paytriage

결제 게이트웨이 오류를 읽고, 그 오류가 대체 무엇을 의미하는지, 다음에 무엇을 확인해야 하는지, 재시도가 안전한지 알려줍니다.

로그 줄, 오류 문자열, 또는 전체 로그 파일을 대상으로 지정하세요. 찾아봐야 하는 코드 대신 평이한 언어로 답합니다.

의존성 없음. Python 3.8 이상. CLI, 라이브러리, 그리고 에이전트가 호출할 수 있는 MCP 서버로 작동합니다.

왜

지원 및 구현 담당자들은 response_code="51"을 "고객 카드에 돈이 없었고, 이건 당신 버그가 아니다"로 바꾸는 데 많은 시간을 보냅니다. 그 변환은 사람들의 머릿속과 북마크된 PDF에 있습니다. 이 도구는 그것을 읽고, grep하고, 수정할 수 있는 파일에 넣습니다.

타임아웃 사례가 가장 중요합니다. 타임아웃은 거절이 아닙니다. 거래가 이미 상대편에서 승인되었을 수 있으므로, 무작정 재시도하면 이중 청구가 발생합니다. 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 서버로 사용

서버는 stdio를 통해 JSON-RPC를 사용하며 triage_payment_error라는 하나의 도구를 노출하므로, 에이전트가 오류를 넘겨주면 구조화된 출력을 받을 수 있습니다.

python -m paytriage.mcp_server

Claude Desktop 또는 Claude Code 설정:

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

다루는 내용

여섯 가지 계열에 걸친 24개의 시그니처:

• 거절: 잔액 부족, do not honor, 카드 만료, 카드 회수, 잘못된 번호

• 검증: AVS 불일치, CVV 불일치

• 전송: TLS 핸드셰이크, 인증서 만료 또는 신뢰할 수 없음, 타임아웃, 연결 거부 또는 재설정, DNS

• API: 401, 403, 429, 5xx

• 메시지 형식: XML 파싱, JSON 파싱, 서명 또는 HMAC 불일치, 필수 필드 누락

• 비즈니스 규칙: 중복 거래, 지원되지 않는 통화, 잘못된 금액, 유효하지 않은 토큰

응답 코드가 있으면 그 코드로, 없으면 패턴으로 매칭합니다. 한 줄이 여러 시그니처와 일치할 수 있으며, 결과는 가장 심각한 것부터 반환됩니다.

이것은 아닙니다

• 사기 점수 산정도, 리스크 엔진도 아닙니다.

• 어떤 게이트웨이에도 연결되지 않습니다. 이미 가지고 있는 텍스트를 읽을 뿐이며 네트워크 호출을 하지 않습니다.

• 완전하지 않습니다. 1차 분류 도우미입니다. 특정 코드에 대한 최종 권위는 발급사 문서입니다.

• 결정을 내리지 않습니다. 여기 있는 어떤 것도 스스로 결제를 자동 재시도해서는 안 됩니다.

시그니처 추가

모든 것은 paytriage/signatures.py의 한 테이블에 있습니다. 시그니처는 패턴 또는 코드 집합과 원인, 해결책, 심각도로 구성됩니다. 항목을 추가하고, 테스트를 추가하고, 풀 리퀘스트를 여세요. 기존 문구에 대한 수정도 새 항목만큼 환영합니다.

테스트

python -m unittest discover -s tests -t .

23개의 테스트, 네트워크 없음, 다운로드할 픽스처 없음.

라이선스

MIT. LICENSE 참조.