# Agentic Payments

AI agents that transact within policy. Two products on one API: a shopper-facing commerce **widget** (Product A) you embed in a store, and an in-account **treasury agent** (Product B) that pays a merchant's own suppliers and payouts on instruction — every payment bounded by a spend policy and an approval threshold.

## Overview

**Product A — Shopper widget.** An embeddable conversational commerce assistant. A shopper chats with the agent, builds a cart from your ingested catalogue, and pays — by stablecoin/on-chain rail or by card (a hosted card checkout, so shoppers without an Aurea account can pay too).

**Product B — Treasury agent.** An in-account agent that moves a merchant's own money (supplier payments, payouts, subscriptions) on instruction. Every payment runs through the **PolicyGuard**: per-transaction, daily, weekly, monthly and velocity limits, recipient allow/deny lists, and an approval threshold above which a payment is parked for manual sign-off.

Each agent is isolated — its own id, API keys, spend policy, mandates and executions. Policy checks run server-side; reservations are held on a spend ledger and only settled once the rail confirms.

> ℹ️ The module is gated by a per-deployment feature flag and a per-tenant flag. When it is off for your deployment or tenant, every route returns `404`. Ask your Aurea contact to enable it before integrating.

## Base URL

All Agent Payments endpoints live under a single prefix:

```bash
https://api.aureahub.com/v1/agent-payments
```

## Authentication

The module uses two credential types depending on who is calling.

### Tenant-admin JWT (management)

Almost every route — creating agents, policies, mandates, keys, ingesting catalogues, executions, analytics — requires a **tenant-admin** JWT bearer token. Access tokens are short-lived (~15 minutes); use your refresh token to renew them. See [Authentication](https://docs.aureahub.com/docs/authentication.md) for the token lifecycle.

```bash
curl https://api.aureahub.com/v1/agent-payments/agents \
  -H "Authorization: Bearer YOUR_TENANT_ADMIN_JWT"
```

A platform `admin` (super-admin, tenant-independent) may act on a specific tenant by adding `?tenantId=` to the request. A `tenantadmin` is always scoped to their own tenant and any `?tenantId=` they pass is ignored.

```bash
# platform admin acting on a specific tenant
curl "https://api.aureahub.com/v1/agent-payments/agents?tenantId=TENANT_UUID" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT"
```

### Scoped merchant API keys (shopper-facing)

The shopper-facing commerce routes — `/commerce/products`, `/commerce/checkout`, `/commerce/checkout/:id`, `/commerce/checkout/:id/card` and `/chat` — accept **either** a scoped merchant API key **or** a tenant-admin JWT. There are two key types:

- **Publishable** — `apk_live_…`. Public-safe: ship it in the browser/widget. It is *origin-restricted* (only the allowed origins you configure may use it) and *rate-limited*. The key pins the tenant and agent, so the request body cannot target another merchant.
- **Secret** — `ask_live_…`. Server-side only; never expose it in a browser. Returned exactly once at creation.

Pass a key in any of these headers: `X-Aurea-Key`, `X-Merchant-Key`, or `Authorization: Bearer apk_live_…`.

The only unauthenticated route in the module is the payment provider's callback that settles card checkouts. Aurea verifies its signature against the raw request body; you never call it.

## SDK

Typed TypeScript SDK on npm — it ships both the embeddable widget and the management client:

```bash
npm install @aureahub/agent-pay
```

## Embed the widget (Product A)

Drop the assistant into any storefront. The publishable key (`apk_live_…`) is public-safe — origin-restricted and rate-limited — so it is fine to ship in the browser.

```html
<div id="aurea-agent"></div>
<script src="https://pay.aureahub.com/widget.global.js"></script>
<script>
  const client = AureaAgentPay.createClient({
    baseUrl: "https://api.aureahub.com",
    merchantKey: "apk_live_..."
  });
  AureaAgentPay.mountWidget('#aurea-agent', {
    client,
    agentId: "AGENT_UUID",
    merchantRecipient: "YOUR_PAYOUT",
    enableCard: true
  });
</script>
```

## Ingest your catalogue

The agent answers shoppers from your product catalogue. Ingestion is an **explicit** call — it is never automatic. Crawl your store once, and re-run whenever the catalogue changes. The crawler detects a JSON product feed, a Shopify products endpoint, or JSON-LD product markup.

```js
const mgmt = AureaAgentManage.createManagementClient({
  baseUrl: "https://api.aureahub.com",
  token // tenant-admin bearer token
});

// Crawl + ingest a storefront URL (explicit, not automatic):
await mgmt.ingestUrl(agentId, "https://your-store.example");
```

You can also push a structured product feed directly instead of crawling — see `POST /commerce/feed` in the API reference.

## API Reference

Every endpoint — agents, API keys, policies, mandates, executions, approvals, commerce, refunds & disputes, webhooks, analytics, KYA, MCP, scheduler and tenant settings — is documented field-by-field in the [Agentic Payments — API Reference](https://docs.aureahub.com/docs/agentic-api.md).

---

Web version: https://docs.aureahub.com/#agentic-payments