agentic-web-payments

name	agentic_web_payments
description	Use this skill to make purchases or pay for services on behalf of the user. AWP (Agentic Web Payments) handles policy validation, browser automation, and checkout — you just call the API.

Agentic Web Payments (AWP)

Use this when you need to purchase something — credits, subscriptions, SaaS tools, or any other online purchase the user has authorized.

AWP validates your request against the user's policy (budget, domain, per-transaction cap), then uses Browser Use to complete the checkout automatically. The user can approve or deny before the final submit.

Base URL: https://beaming-llama-618.convex.site

All bucket/status endpoints are Convex HTTP actions. The payment execute endpoint goes through Next.js (running locally) so it can trigger the checkout agent.

IMPORTANT: Refill Browser Use credits if a purchase fails due to insufficient compute

If a payment attempt fails or stalls and you suspect the cause is insufficient Browser Use credits (e.g. the browser agent timed out, returned an error mid-task, or explicitly reported low credits), you must refill before retrying.

Refill flow

1. Call GET /buckets and find the bucket whose allowed_domains includes *.browser-use.com
2. Execute a $20 credits purchase using that bucket
3. Poll until succeeded
4. Retry the original payment

Example scenario

You are asked to buy a gift on a Stripe checkout page:

1. Execute gift purchase using the shopping bucket → fails mid-task (low credits)
2. Execute $20 Browser Use credits purchase using the credits bucket → wait for approval → poll to success
3. Retry the gift purchase → wait for approval → poll to success
4. Report back: "Refilled Browser Use credits, then purchased [gift] for $X. Both payments approved and logged."

---

List buckets

Before executing a payment you need a bucket_id. Retrieve the available buckets for your API key:

GET https://beaming-llama-618.convex.site/buckets
Authorization: Bearer YOUR_API_KEY

Response:

{
  "items": [
    {
      "bucket_id": "jd7x...",
      "name": "Shopping",
      "status": "active",
      "budget_limit_cents": 5000,
      "budget_window_days": 30,
      "per_tx_cap_cents": 5000,
      "max_tx_per_window": 5,
      "allowed_domains": ["buy.stripe.com", "*.stripe.com"],
      "allowed_purposes": ["gift", "purchase"],
      "auto_approve": false
    },
    {
      "bucket_id": "k9mz...",
      "name": "Browser Use Credits",
      "status": "active",
      "budget_limit_cents": 2500,
      "budget_window_days": 30,
      "per_tx_cap_cents": 2500,
      "max_tx_per_window": 10,
      "allowed_domains": ["*.browser-use.com", "*.stripe.com"],
      "allowed_purposes": ["credits"],
      "auto_approve": false
    }
  ]
}

Pick a bucket whose status is "active", whose allowed_domains covers your merchant URL, and whose allowed_purposes matches your purchase. Use that bucket's bucket_id in the execute call.

Execute a payment

POST http://localhost:3000/api/payments/execute
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "idempotency_key": "<unique string — generate one per payment attempt>",
  "bucket_id": "YOUR_BUCKET_ID",
  "merchant_url": "https://merchant.com/checkout",
  "amount": 10,
  "currency": "USD",
  "purpose": "short description of why you are making this purchase"
}

amount is in dollars (10 = $10.00).

idempotency_key must be unique per payment attempt. Use a random string like pay_<timestamp>_<random>. If you retry the same payment, reuse the same key — you will get the original result back, not a duplicate charge.

purpose should be a clear, honest description of what the payment is for. The user sees this in their dashboard.

Response

{
  "payment_id": "pay_abc123",
  "status": "queued" | "blocked" | "running" | "succeeded" | "failed",
  "reason_code": "domain_not_allowed",
  "card_id": "card_xyz"
}

If status is blocked, the payment was rejected by policy. Do not retry — report the reason_code to the user.

Check status

GET https://beaming-llama-618.convex.site/status?payment_id=<id>
Authorization: Bearer YOUR_API_KEY

Poll this until status is succeeded or failed. Browser Use may take 30–90 seconds to complete checkout.

Rules

• Call GET /buckets first to find a valid bucket_id — do not guess IDs
• Always check Browser Use credit balance before any non-Browser Use purchase (see above)
• Only purchase from merchant URLs covered by the bucket's allowed_domains
• Always set a clear, honest purpose that matches the bucket's allowed_purposes
• Poll status to completion before reporting back to the user
• If blocked, explain the reason_code to the user — do not retry without their intervention
• If the user needs to approve, wait — they will see the approval request in their AWP dashboard
• Never execute more than one payment at a time — wait for each to complete before starting the next