Recaudo Docs
Crear cuenta

MCP y agentes

Límites de dinero para agentes

Límites y aprobaciones para cuando un agente de IA o una app conectada mueve dinero por la API o el MCP.

A quién aplica

A los agentes de IA de Recaudo y a las apps conectadas por OAuth (Claude, ChatGPT u otra que alguien de tu equipo conectó). Las API keys son integraciones del propio negocio y no se limitan, salvo que el negocio cree una regla para esa llave.

Operaciones que se revisan

  • request_payment Pedir un pago: link de pago, ficha de efectivo o SPEI.
  • charge Cobrar a una tarjeta guardada o a un token.
  • refund Reembolsar un cargo.
  • forgive_late_fee Condonar moratorios.
  • record_payment Registrar un pago recibido por fuera o marcar pagada una factura.

Sin configuración, una operación arriba de $5,000 o que pase de $50,000 en el día espera a que una persona la apruebe. A las apps conectadas, reembolsar y registrar pagos siempre les pide aprobación. El negocio cambia todo esto en Configuración → Agentes y pagos.

Qué responde la API

  • 200 / 201 La operación pasó como siempre (200 o 201).
  • 202 Quedó esperando aprobación. El cuerpo es un agent_payment_action con status pending; consulta su estado hasta que cambie.
  • 403 Se negó por los límites (error.type agent_limit_error). No reintentes con otro monto para darle la vuelta: pide a la persona que lo haga o que cambie el límite.
{
    "object": "agent_payment_action",
    "id": "9f1c2b4e-7a0d-4e2f-9b1a-3c5d7e9f1a2b",
    "action": "request_payment",
    "amount": 12500,
    "currency": "MXN",
    "status": "pending",
    "actor": {
        "type": "oauth_app",
        "label": "Claude"
    },
    "expires_at": "2026-11-07T18:00:00-06:00",
    "message": "This operation needs approval from a person at the business. Check its status with GET /v1/agent-payment-actions/9f1c2b4e-7a0d-4e2f-9b1a-3c5d7e9f1a2b."
}

Consultar una operación pendiente

Cuando se aprueba, Recaudo hace la operación tal como se pidió y guarda el resultado en result. Los estados posibles son pending, approved, rejected, denied, expired, failed y allowed. Una aprobación que nadie atiende se vence a las 48 horas.

curl https://recaudo.app/api/v1/agent-payment-actions/9f1c2b4e-7a0d-4e2f-9b1a-3c5d7e9f1a2b \
  -H "Authorization: Bearer sk_live_..."

Nota

Desde el MCP usa la herramienta get_agent_payment_action. A propósito no hay forma de aprobar por la API: lo aprueba una persona en la web.

Idempotency-Key

Manda un encabezado Idempotency-Key único en cada POST de dinero. Si se corta la conexión y repites la petición con la misma llave, recibes la misma respuesta (con Idempotent-Replayed: true) y no se cobra dos veces. La llave dura 24 horas. Si la primera petición sigue corriendo responde 409; si usas la misma llave con otro cuerpo, 422.

curl -X POST https://recaudo.app/api/v1/payment-links \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 5d1f0c2e-order-1043" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500.00, "description": "Pedido 1043"}'
¿Te sirvió esta página? Gracias por avisarnos.
Esc