UCP & AP2

AgentPay implements two open standards that govern how AI agents transact:

AP2 (Agent Payments Protocol) — Google’s standard for cryptographic Cart Mandates that prove a user authorized an agent to make a specific purchase under specific constraints.
UCP (Universal Commerce Protocol) — Google’s standard for the conversation between an AI agent and a merchant, built on top of AP2 + MCP + REST/JSON-RPC.

We sign AP2 mandates on every active card, expose a public JWKS for verification, and run a UCP merchant gateway at /ucp/{slug}/checkout that LatAm merchants can plug into without implementing UCP themselves.

Cart Mandate (AP2)

When you create an AgentPay card and it transitions to active (either directly or after user approval), we emit a Cart Mandate as a signed JWT. The mandate captures the user’s authorization for the agent’s purchase under specific constraints. Mandate payload structure:

{
  "iss": "https://api.agentpay.la",
  "sub": "cardholder:<uuid>",
  "iat": 1777312852,
  "exp": 1779904852,
  "jti": "<mandate-uuid>",
  "type": "ap2.cart_mandate",
  "agent": { "id": null, "type": "claude_code" },
  "cart": {
    "merchant": "namecheap.com",
    "max_amount": { "value": 100, "currency": "usd" },
    "context": "Register staging-domain.com"
  },
  "authorization": {
    "method": "approval_page",
    "evidence_id": "<approval-token-id>",
    "approved_at": 1777312852,
    "subject_email_hash": "MJaZfzJA7ZIlrun4Rtc9Q_YVuMDXkrjwE9DgIc_KA2A"
  },
  "instrument": {
    "type": "virtual_card",
    "card_id": "<card-uuid>",
    "last4": "0781"
  }
}

Algorithm: ES256 (ECDSA P-256), kid ap2-2026-04. Card creation responses include mandate_id and mandate_jwt fields. Pending-approval cards get a mandate when the user approves them.

Verifying a mandate

Anyone can verify mandates we issued without trusting our dashboard. JWKS endpoint:

GET https://api.agentpay.la/.well-known/jwks.json

Returns the public key set in standard JWKS format. Pass it to any JWT library (jsonwebtoken, pyjwt, jose, etc.) to verify signatures locally. Or use our verify endpoint:

curl -X POST https://api.agentpay.la/v1/mandates/verify \
  -H "Content-Type: application/json" \
  -d '{"jwt": "<mandate JWT>"}'

Returns { "valid": true, "payload": {...} } if the signature is valid and the mandate hasn’t expired. Returns { "valid": false, "reason": "..." } otherwise. You can also look up by mandate_id: {"mandate_id": "<uuid>"}.

UCP merchant gateway

A registered merchant exposes a UCP endpoint without writing UCP code:

POST https://api.agentpay.la/ucp/{merchant_slug}/checkout

We validate the AP2 Cart Mandate, then route the payment based on the merchant’s configured settlement mode.

Discovery

curl https://api.agentpay.la/ucp/{slug}/discovery

Returns:

{
  "version": "1.0",
  "merchant": { "slug": "your-slug", "name": "Your Brand" },
  "settlement_mode": "forward",
  "fee_bps": 50,
  "endpoints": {
    "checkout": "https://api.agentpay.la/ucp/your-slug/checkout"
  },
  "auth": {
    "method": "ap2_cart_mandate",
    "jwks_uri": "https://api.agentpay.la/.well-known/jwks.json"
  },
  "supported_currencies": ["USD", "CLP"]
}

Checkout request

POST /ucp/your-slug/checkout
{
  "version": "1.0",
  "intent": "checkout",
  "cart_mandate_jwt": "<JWT>",
  "amount": { "value": 12500, "currency": "usd" },
  "items": [
    { "name": "Product", "qty": 1, "amount": { "value": 12500, "currency": "usd" } }
  ]
}

Validation contract

Every checkout request is validated against the mandate before settlement:

Signature — verified against our JWKS.
Expiry — exp must be in the future.
Currency — request.amount.currency must match mandate.cart.max_amount.currency.
Amount cap — request.amount.value must be ≤ mandate.cart.max_amount.value.
Merchant match (if enforce_merchant_match=true) — mandate.cart.merchant must equal the merchant slug or "any".

If any check fails, the request is rejected with a 400 and the rejection is logged.

Idempotency

Replaying the same mandate JTI returns the same UcpTransaction. Safe for retries.

Settlement modes

Forward — We HMAC-sign the validated request and POST it to the merchant’s forward_url. Merchant settles via their existing rails.

POST <merchant.forward_url>
Content-Type: application/json
X-AgentPay-Signature: sha256=<hmac>
X-AgentPay-Correlation-Id: <uuid>

{
  "correlation_id": "...",
  "merchant_slug": "...",
  "amount_cents": 12500,
  "currency": "usd",
  "items": [...],
  "mandate_verified": true,
  "mandate": { "jti": "...", "iss": "...", "cart": {...}, "instrument": {...} },
  "mandate_jwt": "<original JWT>"
}

Verify the HMAC by computing hmac.new(forward_secret, body, sha256).hexdigest() and comparing to the X-AgentPay-Signature header (after the sha256= prefix). Card — The agent’s bound AgentPay virtual card is the instrument. The mandate carries the card_id. Merchant charges the card normally; the mandate is the chargeback-evidence anchor. fintoc_clp — We create a Fintoc Checkout Session. The response includes a confirmation_url the agent presents to the user. The user confirms in their bank app, funds move directly to the merchant’s collector account, and we update the UCP transaction status via Fintoc’s callback.

Response

{
  "transaction_id": "<uuid>",
  "status": "settled",
  "settlement_mode": "forward",
  "settlement_ref": "<correlation_id>",
  "payment_instrument": {
    "type": "virtual_card",
    "card_id": "<uuid>",
    "last4": "0781"
  },
  "fee_cents": 63,
  "confirmation_url": null
}

For fintoc_clp mode, status: pending_user_confirmation and confirmation_url is set.

Becoming a merchant

Email [email protected] with:

Your brand name + slug preference (URL-safe, like your-brand)
Settlement preference: forward / card / fintoc_clp
For forward mode: your existing checkout webhook URL
For fintoc_clp mode: your Fintoc collector account ID

We provision the endpoint and HMAC signing secret. See the merchant page for more details.

Get Started

Concepts

Integrations

API Reference

Cards

Transactions

Organizations

Budgets & Agents