Connecting agents to AgentPays

Your agent is helping you run an engineering team. Mid-task it hits a paid-tier wall on Cloudflare Workers and needs to top up credits to keep going. Rather than stopping and asking you to grab a card, it requests the purchase through AgentPays:

{
  "merchant_url": "cloudflare.com",
  "merchant_name": "Cloudflare",
  "amount": 5.00,
  "description": "Cloudflare Workers paid plan top-up",
  "justification": "Hitting free tier limits on production worker, need paid plan to keep handling traffic"
}

The amount is under the agent's auto-approve threshold, so AgentPays approves it and issues a single-use virtual card scoped to this transaction:

{
  "status": "approved",
  "request_id": "req_7f3c9a21",
  "virtual_card": {
    "last4": "8061",
    "view_url": "https://agentpays.dev/card/0d4a1e8c2b",
    "view_expires_at": "2026-05-29T18:20:00Z"
  },
  "message": "Purchase approved. A virtual card ending in 8061 has been issued."
}

The agent opens the view_url, reads the card number, expiry, and CVC, and uses them at Cloudflare's checkout. The card is good for exactly one authorization. Once Cloudflare runs the charge, the card auto-closes. No standing card sits with the merchant. No reusable credential exists after this purchase.

Same agent, but this time it wants to renew a GitHub Copilot seat. The amount is above the agent's auto-approve threshold:

{
  "merchant_url": "github.com",
  "merchant_name": "GitHub",
  "amount": 12.00,
  "description": "GitHub Copilot seat renewal",
  "justification": "Engineering team needs Copilot autocomplete restored, seat renewal at standard monthly rate"
}

AgentPays does not issue the card. The purchase goes into a pending state and you get an email:

{
  "status": "pending_review",
  "request_id": "req_b18d40f5",
  "message": "Awaiting owner approval. You will be notified by email.",
  "estimated_wait": "Typically within an hour"
}

You open the email, read what the agent is asking to buy and why, and approve it in the dashboard. The agent has been polling in the meantime:

{
  "status": "approved",
  "request_id": "req_b18d40f5",
  "virtual_card": {
    "last4": "8213",
    "view_url": "https://agentpays.dev/card/9c7b3f0a1d",
    "view_expires_at": "2026-05-29T19:05:00Z"
  }
}

Now the card exists, the agent retrieves it, and the GitHub renewal goes through. The point of the review step is not to slow agents down. It is to give you a clear stop on anything above a threshold you set, with full context (merchant, amount, justification, requesting agent) before money moves.

You have aggregate caps set on your account: $30 daily, $100 weekly across all your agents. Your engineering agent has already spent $17 today on smaller purchases. Now your research agent wants to spin up AWS credits for a training job over the weekend, and the amount is significant. Before sending the request, the agent checks where you stand:

{}

AgentPays responds with what is available, both for this agent and for the account overall:

{
  "daily_spent": 0.00,
  "daily_limit": 30.00,
  "daily_remaining": 30.00,
  "daily_resets_at": "2026-05-30T00:00:00Z",
  "user_aggregate": {
    "daily": {
      "spent": 17.00,
      "limit": 30.00,
      "remaining": 13.00
    },
    "weekly": {
      "spent": 17.00,
      "limit": 100.00,
      "remaining": 83.00
    }
  }
}

The agent's own daily budget is untouched, but the account is close to its daily cap. The research agent wanted $25 of credits, that would push the daily aggregate to $42, well past the $30 limit. Rather than fire off a request that will get denied, the agent has a few real options. It can wait until the cap resets and try then. It can split the purchase into a smaller piece that fits today and a larger piece for tomorrow. It can flag the issue back to you and ask whether to raise the cap.

What matters is that the agent does not have to guess what will succeed. The limits are visible. The reasoning is visible. Spending decisions stay observable on both sides.

Your agent is deploying a production pipeline and needs a persistent server. It calls request_purchase with an idempotency_key tied to this specific intent:

{
  "merchant_url": "render.com",
  "merchant_name": "Render",
  "amount": 14.00,
  "description": "Render web service — starter plan, 1 month",
  "justification": "Deploying the production data pipeline; need a persistent server to keep it running",
  "idempotency_key": "deploy-pipeline-render-2026-06-02"
}

AgentPays approves it and issues a virtual card. But the network drops before the response arrives. The agent has no idea whether the request went through. The wrong move is to give up on the card. The risky move is to retry blindly and risk a duplicate purchase. The right move is to retry with the same key:

// Same call, same idempotency_key — just retry

AgentPays recognizes the key, finds the original request, and returns the same result:

{
  "status": "approved",
  "request_id": "req_d29b73ae",
  "virtual_card": {
    "last4": "5527",
    "view_url": "https://agentpays.dev/card/7e4f1b9c2a",
    "view_expires_at": "2026-06-02T14:35:00Z"
  },
  "message": "Purchase approved. A virtual card ending in 5527 has been issued."
}

Same request_id, same card, no second issuance, no second fee. The key should be stable and unique per purchase intent — something like a hash of the task, a UUID generated when the intent is first formed, or a descriptive string like the one above. The important thing is that retries reuse it; a new key on every retry defeats the purpose.