Acceso a la API de pagos para agentes autónomos: aprueba cada acción

Dar a un agente autónomo una sola credencial de pagos con la que pueda reembolsar a clientes, capturar fondos y modificar suscripciones es un atajo peligroso. Esas acciones afectan a estados distintos, fallan de maneras diferentes y requieren decisiones humanas diferentes.

El acceso a la API de pagos para agentes autónomos debería empezar en un sandbox, pero el sandbox solo sirve para comprobar si el flujo de la acción funciona. No responde si el agente debería realizar un cambio financiero concreto. Diseña el límite de aprobación alrededor de la operación, el registro afectado y la consecuencia, y traslada ese límite al uso en producción.

He visto equipos tratar el acceso a pagos como una casilla de verificación porque la llamada a la API parece pequeña. Un endpoint de reembolso puede recibir solo un identificador y un importe. Una captura puede no llevar cuerpo. Una actualización de suscripción puede parecer un cambio de campo inofensivo. Precisamente por ser breve, la solicitud lleva a subestimar la decisión que hay detrás.

El éxito en el sandbox demuestra el enrutamiento, no el criterio

Un sandbox demuestra que el agente puede identificar objetos, enviar solicitudes, gestionar errores y leer respuestas sin mover dinero real. No demuestra que sus datos de entrada sean fiables, que su razonamiento coincida con tu política de soporte ni que una persona vaya a reconocer una solicitud incorrecta antes de que se ejecute.

Mantén el alcance inicial del sandbox deliberadamente limitado. Usa clientes y pedidos sintéticos cuyos nombres hagan evidente el escenario. Da a cada elemento de prueba un único propósito: una autorización capturada parcialmente, un pago capturado por completo, un pago con un reembolso parcial anterior, una suscripción activa que aplicará prorrateo y otra que debe cancelarse al final del periodo. Los datos de prueba aleatorios generan una confianza falsa porque nadie puede saber qué significa un resultado.

Escribe el contrato operativo antes de permitir que el agente haga llamadas. No es un archivo de políticas para una pasarela de API. Es un documento breve que producto, finanzas e ingeniería pueden revisar juntos.

environment: sandbox
operations:
  capture:
    approval: per_call
    reviewer_must_see:
      - authorization_amount
      - requested_amount
      - order_status
      - authorization_expiry
  refund:
    approval: per_call
    reviewer_must_see:
      - original_payment
      - total_refunded
      - requested_amount
      - customer_request_reference
  subscription_change:
    approval: per_call
    reviewer_must_see:
      - current_plan
      - proposed_plan
      - proration_effect
      - billing_anchor
      - cancellation_state

Este documento evita un fallo habitual: alguien aprueba el proceso del agente al principio del turno de soporte y después descubre que una rebaja de plan con un abono inmediato y una captura manual se ejecutaron bajo aquella aprobación imprecisa. El documento hace visibles los datos que faltan antes de que producción tenga que hacerlo por ti.

Ejecuta cada caso de prueba dos veces. Primero, deja que el agente proponga la acción y recházala. Confirma que el rechazo no provoca un reintento posterior con un identificador de solicitud nuevo. Después, apruébala y compara la respuesta del proveedor con el estado esperado del registro. Prueba también un error de API después de que la solicitud salga de tu pasarela. El camino de reintento causa más accidentes de pago que el camino exitoso.

Los datos del sandbox también pueden causar problemas. Un agente que borra elementos de prueba, cambia suscripciones compartidas o genera miles de eventos ruidosos ralentizará a todos los que intenten validar una versión. El impacto financiero no está presente, pero el problema de control sí. Haz que la aprobación en el sandbox sea menos pesada que en producción, no inexistente.

La autoridad para reembolsar necesita trazabilidad y un límite estricto del importe

Un reembolso debería requerir una decisión por llamada en producción porque devuelve dinero y porque el pago original, por sí solo, no justifica el reembolso. Una conversación con soporte, un fallo de entrega, una revisión de fraude o una condición contractual aportan la justificación. El agente necesita suficientes pruebas para proponer el reembolso, pero no debe convertir una frase imprecisa como «hay que arreglar esto» en un débito sin revisión.

Exige que la acción propuesta quede vinculada al objeto de pago original, no al nombre de un cliente ni a un número de pedido que podría coincidir con varios cargos. La persona que revisa debe ver el importe y la moneda originales, los reembolsos anteriores, el importe solicitado y una referencia a la solicitud del cliente o al caso interno. Si el proveedor admite reembolsos parciales, calcula el importe que aún se puede reembolsar a partir del estado más reciente del proveedor, no de un saldo almacenado localmente.

La recomendación peligrosa es aprobar automáticamente los reembolsos pequeños. Resulta atractiva porque reduce el tiempo de gestión y muchos importes pequeños parecen inofensivos. Falla porque el número de casos no tiene límite, un agente puede elegir el pago equivocado y un importe pequeño también puede infringir una política. Una aprobación por llamada tarda un momento. Revertir un reembolso incorrecto suele exigir una conversación incómoda con el cliente y quizá no sea posible a través de la red de pagos.

Define una expectativa de importe incluso cuando una persona apruebe cada llamada. Si el agente solicita más que la captura original o más que el importe restante reembolsable, tu capa de acciones debe rechazarlo antes de preguntar a una persona. No conviertas esa comprobación en una instrucción para el agente. Aplícala donde viven la credencial y la ejecución de la solicitud.

Un buen registro de aprobación se parece a la nota de un empleado de pagos, no a la transcripción de un modelo:

Refund request
Payment: pay_123
Original captured: 84.00 USD
Already refunded: 20.00 USD
Requested: 64.00 USD
Reason reference: case_481
Expected result: payment fully refunded

La referencia del motivo importa. Permite que alguien que revise una disputa posterior rastree por qué ocurrió la acción sin introducir la correspondencia del cliente ni las credenciales de pago en una instrucción para el agente. Mantén breve el resumen del agente, pero conserva el registro original fuera de la conversación con el agente.

No confundas la aprobación del reembolso con la verificación de identidad del cliente. Por lo general, la API de pagos conoce un objeto de pago, no si la persona que participa en un chat es la titular de la cuenta. Haz las comprobaciones de identidad en el flujo de soporte antes de que el agente proponga la acción financiera.

Una captura es un cobro, aunque exista una autorización

Una captura de pago debería recibir una aprobación independiente por llamada porque la autorización y el cobro son estados distintos del cliente. El cliente puede haber autorizado un importe máximo, pero la empresa aún debe decidir si el pedido se envió, si cambió el importe final y si la autorización sigue siendo válida.

Las solicitudes de captura suelen parecer engañosamente seguras. Un agente puede ver un pago autorizado y concluir que debe capturarlo al encontrar una etiqueta de envío. Esa etiqueta podría haberse anulado, el pedido podría haberse dividido, el inventario podría estar pendiente de reposición o una persona podría haber acordado otra liquidación. El agente no puede inferir una decisión de cobro a partir de un solo campo de estado.

Muestra a la persona revisora cuatro datos: el importe autorizado, el importe propuesto, el estado de preparación y envío, y la fecha de caducidad de la autorización. Si se permite una captura parcial, indica si más adelante se podrá realizar otra captura según las reglas del proveedor. Esas reglas varían según el método de pago y el proveedor, así que usa la respuesta del proveedor como fuente de verdad en lugar de copiar suposiciones en las instrucciones.

Trata una diferencia entre importes como un momento de aprobación independiente. Una captura por el total autorizado y una captura por un importe final reducido tienen explicaciones diferentes. La tarjeta de aprobación debe expresar la diferencia con claridad, por ejemplo: «Autorizados 100,00 USD; se solicitan 86,50 USD después de retirar un artículo». Una persona no puede detectar la diferencia si la interfaz oculta la autorización original.

No concedas capacidad de captura simplemente porque el agente pueda crear un pedido. Crear un pedido es una intención interna. Capturar un pago es una acción financiera externa. Mantener separadas ambas capacidades también mejora la respuesta ante incidentes: si la integración de preparación y envío empieza a comportarse de forma extraña, puedes desactivar los cobros sin desactivar la investigación habitual de pedidos.

Para el trabajo en sandbox, crea una autorización que deba capturarse correctamente, otra que deba permanecer sin capturar y otra cuyo elemento de prueba simule una autorización caducada. El agente no debería proponer ninguna acción para la segunda y debería mostrar una excepción para la tercera. Si simplemente reintenta en cualquiera de esos estados, has probado el formato de la solicitud, no el criterio.

Las modificaciones de suscripción tienen consecuencias financieras diferidas

Un cambio de suscripción merece una aprobación por llamada porque su impacto puede aparecer en la siguiente factura y no en la respuesta inmediata de la API. Los campos de riesgo no se limitan a los identificadores del plan. La cantidad, la fecha de referencia de facturación, las fechas de prueba, la configuración de cancelación, los descuentos, los impuestos y el comportamiento del prorrateo pueden cambiar lo que el cliente paga o recibe.

No apruebes una solicitud de suscripción que solo muestre el plan propuesto. La persona revisora necesita una vista de antes y después: plan y cantidad actuales, plan y cantidad propuestos, fecha de renovación actual, fecha de renovación prevista, estado de cancelación y resultado proyectado del prorrateo o de la factura del proveedor, cuando esté disponible. Sin esa comparación, la persona ve el nombre de un producto y no ve el importe de la factura.

Las operaciones de suscripción necesitan su propio vocabulario. Una rebaja en la renovación, una rebaja inmediata con un abono, una cancelación al final del periodo y una cancelación inmediata no son equivalentes. Haz que el agente seleccione una intención explícita del flujo de soporte. Si la solicitud del cliente es ambigua, devuélvela para que se aclare en lugar de pedir al agente que elija una consecuencia de facturación.

Los peores fallos de suscripción suelen parecer correctos desde el punto de vista administrativo. La API responde correctamente, la cuenta tiene el nombre de plan esperado y el cliente descubre después una factura inesperada o que ha perdido el acceso. Por eso la aprobación debe incluir el resultado financiero y de acceso esperado, no solo los campos modificados.

Los escenarios del sandbox deberían incluir una reducción de cantidad a mitad del ciclo, una mejora que produzca prorrateo y una cancelación programada para el final del periodo. Confirma la respuesta del proveedor en el sandbox y cualquier objeto de factura generado. Después, haz que una persona rechace el mismo cambio propuesto y confirma que el agente no intenta una acción parecida, como establecer la cantidad en cero en lugar de fijar una fecha de cancelación.

La idempotencia evita reintentos duplicados, no una autoridad incorrecta

La idempotencia protege una solicitud frente a una ejecución duplicada después de un fallo de red o una respuesta incierta, pero no puede hacer segura una acción no autorizada o equivocada. Los equipos suelen mezclar ambos controles porque los dos parecen relacionados con los reembolsos duplicados. No son el mismo control y fallan en direcciones distintas.

La documentación de Stripe sobre las solicitudes idempotentes indica que almacena el primer código de estado y el cuerpo de la respuesta para una clave de idempotencia, incluida una respuesta de error del servidor, y devuelve ese resultado en las solicitudes posteriores que usan la misma clave. También indica que las solicitudes posteriores deben usar parámetros coincidentes. Es un comportamiento útil, pero no impide que un agente genere una clave de idempotencia diferente para el mismo reembolso previsto ni le indica si el reembolso debería existir.

Usa un único identificador de acción estable para una intención aprobada por una persona. Genéralo antes de la ejecución, regístralo junto con la aprobación y reutilízalo para reintentar exactamente esa solicitud. No lo derives de la hora actual ni permitas que el agente lo sustituya después de un tiempo de espera.

Una prueba de sandbox debería simular deliberadamente la incertidumbre:

1. Aprueba un reembolso parcial de un pago de prueba y asígnale un identificador de acción.
2. Envía la solicitud y haz que el cliente se comporte como si hubiera perdido la respuesta.
3. Reintenta con el mismo identificador y el mismo importe.
4. Inspecciona el estado del pago y confirma que el proveedor informa de un solo reembolso.
5. Intenta la misma solicitud con un importe diferente y confirma que tu capa de acciones la rechaza en lugar de tratarla silenciosamente como un reintento.

La última comprobación detecta un error dañino. Un desarrollador puede reutilizar un identificador por accidente mientras el agente ha cambiado el importe solicitado después de leer una nota nueva de soporte. La respuesta de diferencia del proveedor avisa de que se han confundido dos intenciones. Conserva ambas solicitudes en el registro de auditoría y exige una nueva decisión humana para el importe nuevo.

La idempotencia tampoco gestiona el razonamiento simultáneo. Dos ejecuciones del agente pueden proponer el mismo reembolso con identificadores diferentes. Antes de ejecutar, obtén el estado más reciente del pago y comprueba los reembolsos anteriores. Mejor aún, serializa las acciones sobre el mismo objeto de pago en tu pasarela para que la segunda propuesta espere el resultado de la primera. La persona revisora no debería tener que competir con dos tarjetas de aprobación para evitar un movimiento de dinero duplicado.

Las pantallas de aprobación deben mostrar la decisión, no un bloque de API

Una pantalla de aprobación solo funciona cuando una persona puede decidir a partir de los datos que aparecen en ella. Un nombre de endpoint sin contexto, una gran carga JSON y un botón «Permitir» trasladan la responsabilidad a una persona que no tiene ni el tiempo ni el contexto para descifrarlos.

Para los reembolsos, empieza por el dinero que sale de la empresa e identifica el pago original. Para las capturas, empieza por el dinero que se va a cobrar y compara la autorización con la captura solicitada. Para los cambios de suscripción, empieza por el estado de facturación anterior y posterior. Después, ofrece los identificadores de los objetos del proveedor y la carga original detrás del resumen para investigar, no como interfaz principal.

La aprobación debe estar vinculada a la solicitud exacta. Si una persona aprueba una rebaja de suscripción, la capa de acciones no puede añadir después un pago de factura inmediato, cambiar la cantidad ni cambiar la suscripción de destino. Hashea los campos revisados o vincúlalos de otra manera en el registro de ejecución, e invalida la aprobación cuando cambie un campo importante.

La aprobación por sesión también tiene su lugar. Establece que un proceso de agente concreto puede solicitar acciones durante una ejecución limitada. Debe mostrar la identidad del proceso, quién lo inició y el alcance del trabajo. No autoriza todas las acciones de pago que el proceso pueda inventar después de empezar. La aprobación de sesión responde a «¿puede este proceso solicitar trabajo?». La aprobación por llamada responde a «¿debe ocurrir exactamente esta acción financiera?».

Evita solicitar aprobación para operaciones rutinarias de lectura. Los agentes necesitan consultar el estado de un pago, recuperar una suscripción y leer el estado de reembolsos anteriores para preparar una propuesta útil. Si cada lectura abre una ventana, la gente aprobará a ciegas o desactivará todas las aprobaciones. Reserva la interrupción para los cambios de estado y asegúrate de que el flujo de lectura no exponga credenciales al agente.

Las credenciales deben quedar detrás de un límite de acción

El agente nunca debería recibir un secreto de pago, ni siquiera temporalmente, porque un proceso de agente puede dejarlo en registros, en el historial del shell, en archivos fuente, en el contexto del chat o en una solicitud a otro servicio. Ocultar un secreto después no repara las copias que no detectaste.

Coloca la credencial en un límite de acción que acepte una solicitud restringida, inyecte la credencial por sí mismo y devuelva el resultado del proveedor. El agente puede pedir que se recupere un pago o proponer un reembolso, pero no puede imprimir el secreto ni reutilizarlo en un endpoint que no hayas expuesto. Separa las credenciales de sandbox y de producción en ese límite para que un cambio de entorno no pueda hacerse mediante una variable de entorno escrita por el agente.

Sallyport mantiene las credenciales de API y SSH en una bóveda cifrada en el Mac y ejecuta llamadas HTTP compatibles sin pasar la credencial al agente conectado. Su bloqueo de bóveda, la autorización de sesión y la aprobación opcional en cada uso encajan bien con el trabajo de pagos cuando reservas la aprobación por uso para las escrituras financieras.

El límite de acción debe validar algo más que la autenticación. Debe rechazar una solicitud real enviada por una ruta de sandbox, bloquear un método HTTP no compatible, verificar que un identificador tenga el tipo esperado y exigir una aprobación registrada para las operaciones financieras que hayas designado. Son restricciones de ejecución, no sugerencias que el modelo pueda seguir cuando le convenga.

No trates un secreto amplio del proveedor de pagos como una comodidad de desarrollo. Si el agente solo necesita consultar pagos, crear reembolsos, hacer capturas y realizar una actualización limitada de suscripción, expón solo esas llamadas. Un secreto con permisos de administración de la cuenta, pagos a proveedores, disputas o datos de clientes amplía el alcance de un incidente sin una buena razón.

Un registro de auditoría debe explicar la acción y su autorización

El historial de eventos del proveedor de pagos puede indicar que ocurrió un reembolso o una actualización de suscripción. A menudo no puede indicar qué proceso de agente lo solicitó, qué pruebas consideró, si una persona lo aprobó ni qué solicitud hizo antes de reintentar. Conserva un registro de ejecución que responda a esas preguntas sin guardar la transcripción completa del agente como única prueba.

Registra el entorno, la operación, el objeto de destino, los campos enviados, el identificador de acción, la respuesta del proveedor, la identidad de la sesión del agente, el resultado de la aprobación, la identidad de la persona revisora y el orden temporal. Para las acciones que usan importes, conserva el importe y la moneda en campos separados. Para los cambios de suscripción, conserva el estado anterior y el estado posterior previsto. Guarda referencias a casos de soporte o registros de preparación y envío en lugar de duplicar texto sensible del cliente que no necesitas.

Haz que el registro de auditoría sea útil cuando haya una discrepancia. Si un cliente dice que un reembolso fue incorrecto, una persona operadora debería poder reconstruir la cadena: el agente leyó el estado del pago, propuso un reembolso parcial vinculado a un caso, una persona aprobó el importe exacto, la pasarela envió una solicitud y el proveedor devolvió un objeto de reembolso. Si falta un eslabón, corrige el sistema en lugar de pedir al personal que recuerde lo ocurrido semanas después.

La evidencia de manipulación importa porque los incidentes de pago suelen convertirse en incidentes de acceso. Una persona con permisos administrativos no debería poder borrar sin dejar rastro un registro de acción incómodo. Sallyport proyecta las sesiones de los agentes y las llamadas individuales desde un registro de auditoría cifrado y encadenado mediante hashes, y su comando sp audit verify puede verificar la cadena sin conexión y sin un secreto de bóveda.

Haz que la revisión de auditoría sea práctica. Busca propuestas rechazadas repetidamente contra el mismo pago, importes modificados después de un tiempo de espera, muchos intentos desde una identidad de proceso nueva y cambios de suscripción que generen un comportamiento inesperado en las facturas. Esos patrones apuntan a una integración defectuosa o a un agente confundido antes de convertirse en una limpieza financiera mayor.

El acceso real debe seguir a las pruebas, no al calendario

Pasa a las acciones de pago reales solo cuando las ejecuciones del sandbox demuestren que el agente propone la operación correcta, que las personas revisoras ven suficiente contexto, que los reintentos siguen siendo idempotentes y que el rechazo detiene realmente la ejecución. Un número fijo de llamadas de prueba exitosas es menos útil que contar con pruebas de los casos de fallo que producción acabará presentando.

Empieza con acceso de lectura y propuestas si tu flujo lo permite. Después, elige una operación y un caso de negocio limitado, como reembolsos que ya tengan un caso de soporte cerrado y un pago original verificado. Mantén desactivadas las capturas y los cambios de suscripción hasta haber ejercitado sus propios elementos de prueba del sandbox, sus vistas de aprobación y sus procedimientos de reversión.

Antes de la primera llamada real, ensaya la revocación. Bloquea el límite de credenciales, termina la sesión del agente, confirma que las aprobaciones pendientes no se pueden ejecutar y verifica que el registro de auditoría sigue disponible. Hazlo cuando todo el mundo esté tranquilo. Un incidente de pagos es el peor momento para descubrir que la revocación depende de que alguien encuentre el comando correcto en el terminal.

No relajes poco a poco la revisión por llamada porque el agente se haya comportado bien durante una semana. Relájala solo cuando puedas nombrar una acción delimitada, una fuente fiable de autorización, un flujo de error medible y una persona responsable de revisar las excepciones. Los reembolsos, las capturas y las modificaciones de suscripción rara vez cumplen esas condiciones al mismo tiempo. Mantén separadas sus expectativas de aprobación porque sus consecuencias también son distintas.