One request. Three possible answers.

The preview

Access is by invitation while PayCarter is pre-launch. A company gets three kinds of token:

Send the token on every call as Authorization: Bearer <token>. Tokens are shown once when they are made, and only a hash is stored. A token can only ever act as what it was issued for: an agent cannot approve its own purchase.

How a purchase runs

1. The agent asksMerchant, amount, currency and a reason, before it reaches any checkout.
2. The rules are checkedCurrency, blocked and approved merchants, the limit per purchase, the monthly budget. The reply lists every rule and how it came out.
3. A person approves, if neededAnything above the approval threshold waits for the named approver, who gets a link to a one-screen decision.
4. The agent collects payment detailsFor that purchase only, and only once.
5. The agent reports what happenedCompleted or failed, the amount charged and the order reference. All of it lands in one audit trail.

Every purchase request has a summary that is always one of three words. It is the only field an agent needs to branch on.

An approved or pending request holds its amount against the monthly budget, so two requests cannot both squeeze under the limit. Permission lapses if it is not used in time (24 hours unless the company sets otherwise), and a lapsed, declined or failed purchase gives its budget back.

Quick start

Four calls take a purchase from request to receipt. The examples use the demo rules: a 250.00 limit per purchase, 2,000.00 a month, and approval needed above 100.00.

1. Ask to buy

curl https://api.paycarter.com/v1/intents \
  -H "Authorization: Bearer $PAYCARTER_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": { "name": "Fernhill Software", "url": "https://fernhill.example", "countryCode": "GB" },
    "amount": "240.00",
    "currency": "GBP",
    "reason": "Annual plan, design team"
  }'

240.00 is above the approval threshold, so the answer is pending:

{
  "intent": {
    "id": "int_76c3efbc6ba3406e9fcb5b9d2fdd21ff",
    "summary": "pending",
    "status": "pending",
    "merchant": { "name": "Fernhill Software", "url": "https://fernhill.example", "countryCode": "GB" },
    "amount": "240.00",
    "currency": "GBP",
    "reason": "Annual plan, design team",
    "checks": [
      { "rule": "currency", "passed": true, "detail": "Purchase is in GBP." },
      { "rule": "blocked_merchant", "passed": true, "detail": "Fernhill Software is not blocked." },
      { "rule": "per_purchase_limit", "passed": true, "detail": "Within the 250.00 GBP limit per purchase." },
      { "rule": "monthly_budget", "passed": true, "detail": "1760.00 GBP of the 2000.00 GBP monthly budget left after this purchase." },
      { "rule": "approval_threshold", "passed": false, "detail": "Above 100.00 GBP, so the approver decides." }
    ],
    "flags": [],
    "createdAt": "2026-10-12T14:09:20.711Z",
    "expiresAt": "2026-10-13T14:09:20.711Z",
    "events": [ /* the audit trail so far */ ]
  }
}

2. The approver decides

Usually on the approval screen, from a link. With the approver's token it is one call:

curl https://api.paycarter.com/v1/intents/$INTENT_ID/decision \
  -H "Authorization: Bearer $PAYCARTER_APPROVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "reason": "Renewal agreed in the budget" }'

3. Collect payment details

curl -X POST https://api.paycarter.com/v1/intents/$INTENT_ID/credential \
  -H "Authorization: Bearer $PAYCARTER_AGENT_TOKEN"

{
  "intent": { "id": "int_76c3…", "summary": "approved", "status": "credential_issued" /* … */ },
  "credential": {
    "cardNumber": "4111111111111111",
    "expirationDate": "12/2030",
    "securityCode": "123"
  }
}

This works once per purchase. A second call answers 409 credential_already_issued. PayCarter does not store or log these details.

4. Report what happened

curl https://api.paycarter.com/v1/intents/$INTENT_ID/confirmation \
  -H "Authorization: Bearer $PAYCARTER_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "amount": "240.00", "orderId": "FH-10042" }'

If the amount reported is more than was approved, the purchase is still recorded and is flagged amount_over_approved for the company to see.

Connect an agent with MCP

The same flow is available as tools over the Model Context Protocol, so an agent that speaks MCP needs no custom code.

Many MCP clients take a block like this. The key names vary, so check your client's own documentation.

{
  "mcpServers": {
    "paycarter": {
      "type": "http",
      "url": "https://api.paycarter.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_AGENT_TOKEN" }
    }
  }
}

The agent is identified by the token on the connection, never by anything it passes to a tool, so one agent cannot act as another. Approver and admin tokens are refused.

Tools

{
  "intent_id": "int_662cca55acf7451a9c3fadddb08490ff",
  "summary": "pending",
  "status": "pending",
  "merchant": "Kettle & Co",
  "amount": "129.00",
  "currency": "GBP",
  "reason": "Office kettle",
  "checks": [ /* one entry per rule */ ],
  "expires_at": "2026-10-13T14:09:20.883Z",
  "flags": [],
  "next_step": "A person has to approve this first. Check back with get_purchase. Do not send the request again."
}

Purchases API

Asking to buy

Status

summary is for agents. status says exactly where a purchase is.

Rules a company can set

• A limit per purchase, and a monthly budget per agent (calendar month, UTC).
• An approval threshold. Set it to zero and every purchase waits for a person.
• Approved merchants, blocked merchants, or both.
• How long permission lasts before it lapses.
• The named person who approves.

Approvals

When a purchase needs a person, the approver is sent a link, by a webhook into a chat channel for now, with email on the way. The link opens one screen: merchant, amount, reason, who is asking, the card, and what is left of the budget, with Approve and Decline.

A webhook receives a JSON POST with a readable text line and the same facts as separate fields:

{
  "text": "Jamie's agent (for Jamie) wants to spend 240.00 GBP at Fernhill Software: Annual plan, design team\nApprove or decline: https://api.paycarter.com/approve/int_…#…",
  "event": "approval_requested",
  "intentId": "int_76c3efbc6ba3406e9fcb5b9d2fdd21ff",
  "merchant": "Fernhill Software",
  "amount": "240.00",
  "currency": "GBP",
  "reason": "Annual plan, design team",
  "requestedBy": "Jamie's agent",
  "onBehalfOf": "Jamie",
  "approver": "Priya, Finance",
  "expiresAt": "2026-10-13T14:09:20.711Z",
  "approvalUrl": "https://api.paycarter.com/approve/int_…#…"
}

Admin API

With an admin token. Everything is confined to the admin's own company, and anything belonging to another company is reported as not found.

Errors

Errors have one shape, with a stable code to branch on and a message written for a person:

{ "error": { "code": "invalid_currency", "message": "Currency must be one of GBP, EUR, USD." } }

A purchase the rules refuse is not an error. It comes back 201 with the summary denied, so the refusal is on the record.

Not there yet

What this preview does not do, so nobody finds out the hard way:

• Real cards. It is waiting on the card networks. Until then every purchase runs on the test network.
• Sign-in for approvers and admins. Both rest on tokens and links for now.
• Safe retries. There are no idempotency keys yet. If a request to buy times out, read the purchase before sending it again.
• Signed webhooks, and events beyond approval requests.
• Usage limits and versioning. The address will gain a version policy before launch.