paytriage

Lee un error de pasarela de pago y te dice qué significa probablemente, qué comprobar a continuación y si reintentar es seguro.

Apúntalo a una línea de registro, una cadena de error o un archivo de registro completo. Responde en lenguaje sencillo en lugar de un código que tengas que buscar.

Sin dependencias. Python 3.8 y superior. Funciona como CLI, como biblioteca y como servidor MCP que un agente puede llamar.

Por qué

El personal de soporte y desarrollo pierde mucho tiempo convirtiendo response_code="51" en "la tarjeta del cliente no tenía dinero, esto no es tu error". Esa traducción vive en las cabezas de la gente y en PDFs marcados. Esto la pone en un archivo que puedes leer, buscar y corregir.

El caso de tiempo de espera agotado es el que más importa. Un timeout no es un rechazo. La transacción puede ya estar autorizada en el otro lado, así que un reintento a ciegas es cómo cobras dos veces a alguien. paytriage lo dice en voz alta cada vez.

Instalar

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

O sáltate la instalación y ejecútalo en el lugar con python -m paytriage.cli.

Úsalo desde la línea de comandos

$ 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

Un archivo completo, resumido:

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

Añade --json a cualquier llamada para obtener salida legible por máquina.

Úsalo como biblioteca

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

Úsalo como servidor MCP

El servidor habla JSON-RPC sobre stdio y expone una herramienta, triage_payment_error, para que un agente pueda pasarle un error y recibir una salida estructurada.

python -m paytriage.mcp_server

Configuración de Claude Desktop o Claude Code:

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

Qué cubre

Veinticuatro firmas en seis familias:

• Rechazos: fondos insuficientes, no honrar, tarjeta caducada, retener tarjeta, número inválido

• Verificación: discrepancia AVS, discrepancia CVV

• Transporte: handshake TLS, certificado caducado o no confiable, timeout, conexión rechazada o reiniciada, DNS

• API: 401, 403, 429, 5xx

• Formato de mensaje: parseo XML, parseo JSON, discrepancia de firma o HMAC, campo obligatorio faltante

• Reglas de negocio: transacción duplicada, moneda no soportada, importe incorrecto, token inválido

La coincidencia se hace por código de respuesta cuando está presente, y por patrón en caso contrario. Una línea puede coincidir con más de una firma, y los resultados vuelven de peor a mejor.

Lo que no es

• No es puntuación de fraude, ni un motor de riesgo.

• No está conectado a ninguna pasarela. Lee texto que ya tienes y no hace llamadas de red.

• No es exhaustivo. Es una ayuda de triaje de primera pasada. La documentación del propio emisor sigue siendo la autoridad en cualquier código específico.

• No es un tomador de decisiones. Nada aquí debería reintentar un pago por sí solo.

Añadir una firma

Todo vive en una tabla en paytriage/signatures.py. Una firma es un patrón o un conjunto de códigos, más la causa, la solución y una severidad. Añade una entrada, añade una prueba, abre un pull request. Las correcciones a la redacción existente son tan bienvenidas como las nuevas entradas.

Pruebas

python -m unittest discover -s tests -t .

23 pruebas, sin red, sin fixtures que descargar.

Licencia

MIT. Ver LICENSE.