Recaudo Docs
Criar conta

MCP e agentes

Limites de dinheiro para agentes

Limites e aprovações para quando um agente de IA ou um app conectado movimenta dinheiro pela API ou pelo MCP.

A quem se aplica

Aos agentes de IA do Recaudo e aos apps conectados por OAuth (Claude, ChatGPT ou outro que alguém da sua equipe conectou). As API keys são integrações do próprio negócio e não têm limite, a não ser que o negócio crie uma regra para essa chave.

Operações revisadas

  • request_payment Pedir um pagamento: link de pagamento, boleto em dinheiro ou SPEI.
  • charge Cobrar um cartão salvo ou um token.
  • refund Reembolsar uma cobrança.
  • forgive_late_fee Perdoar juros de mora.
  • record_payment Registrar um pagamento recebido por fora ou marcar uma fatura como paga.

Sem configuração, uma operação acima de $5,000, ou que passe de $50,000 no dia, espera a aprovação de uma pessoa. Para apps conectados, reembolsar e registrar pagamentos sempre pede aprovação. O negócio muda tudo isso em Configurações → Agentes e pagamentos.

O que a API responde

  • 200 / 201 A operação passou normalmente (200 ou 201).
  • 202 Ficou esperando aprovação. O corpo é um agent_payment_action com status pending; consulte até mudar.
  • 403 Negada pelos limites (error.type agent_limit_error). Não tente de novo com outro valor para contornar: peça à pessoa que faça ou que mude o limite.
{
    "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 uma operação pendente

Quando aprovada, o Recaudo executa a operação como foi pedida e guarda o resultado em result. Os status possíveis são pending, approved, rejected, denied, expired, failed e allowed. Uma aprovação que ninguém atende vence em 48 horas.

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

Nota

No MCP use a ferramenta get_agent_payment_action. De propósito não há como aprovar pela API: uma pessoa aprova na web.

Idempotency-Key

Envie um cabeçalho Idempotency-Key único em cada POST de dinheiro. Se a conexão cair e você repetir a requisição com a mesma chave, recebe a mesma resposta (com Idempotent-Replayed: true) e nada é cobrado duas vezes. A chave dura 24 horas. Se a primeira requisição ainda estiver rodando, a resposta é 409; a mesma chave com outro corpo dá 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"}'
Esta página ajudou? Obrigado por avisar.
Esc