Recaudo Docs
Sign up

MCP & agents

Money limits for agents

Limits and approvals for when an AI agent or a connected app moves money through the API or MCP.

Who it applies to

Recaudo AI agents and apps connected over OAuth (Claude, ChatGPT or any app someone on your team connected). API keys are the business's own integrations and are not limited unless the business adds a rule for that key.

Operations that are checked

  • request_payment Request a payment: payment link, cash voucher or SPEI.
  • charge Charge a saved card or a token.
  • refund Refund a charge.
  • forgive_late_fee Forgive late fees.
  • record_payment Record a payment received outside Recaudo or mark an invoice as paid.

With nothing configured, an operation above $5,000, or one that takes the day past $50,000, waits for a person to approve it. Connected apps always need approval to refund or record payments. The business changes all of this in Settings → Agents and payments.

What the API returns

  • 200 / 201 The operation went through as usual (200 or 201).
  • 202 It is waiting for approval. The body is an agent_payment_action with status pending; check it until it changes.
  • 403 Denied by the limits (error.type agent_limit_error). Do not retry with a different amount to get around it: ask the person to do it or to change the limit.
{
    "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."
}

Checking a pending operation

Once approved, Recaudo runs the operation exactly as requested and stores the outcome in result. Possible statuses are pending, approved, rejected, denied, expired, failed and allowed. An approval nobody handles expires after 48 hours.

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

Note

From MCP use the get_agent_payment_action tool. There is deliberately no way to approve through the API: a person approves it on the web.

Idempotency-Key

Send a unique Idempotency-Key header on every money POST. If the connection drops and you repeat the request with the same key, you get the same response (with Idempotent-Replayed: true) and nothing is charged twice. Keys last 24 hours. If the first request is still running you get 409; the same key with a different body gets 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"}'
Was this page helpful? Thanks for letting us know.
Esc