> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A agentic-commerce transact skill

> Let an external buyer agent discover your A2A agent card, place an order against your agent under a scoped and revocable payment mandate, and receive an authorization decision — then pay through the existing payment-request rails.

# A2A agentic-commerce transact skill

An external buyer agent — a shopping assistant on another platform, an A2A-conformant peer tenant, or a third-party commerce network — discovers your agent's public A2A card and places an order against it. The buyer does not hold an Orbit credential and never touches your PSP. Instead, your agent evaluates the order against a **payment mandate** the buyer's principal has already issued, returns a structured **authorization decision**, and — only when that decision is `authorized` — mints a pay-by-link through the payment-request rails you already use.

This is agentic commerce on Orbit: a peer-to-peer checkout where the trust boundary is a spend-capped, revocable mandate, not a shared platform secret, and where money moves only through the existing payment-request path after the mandate authorizes it.

## What the mandate decides

The `transact` skill is the bridge between two primitives that already ship on the commerce pillar:

1. **Agent payment mandate** — an AP2-style authorization layer. A principal issues a spend-capped, revocable mandate once; the agent then spends against it; either party can revoke at any time. The mandate **only decides whether a charge is allowed** — it never moves money. This invariant is the load-bearing distinction: the mandate is a decision gate, not a payment instrument. The actual charge still exits caller-side through the hosted pay-by-link or native in-thread checkout.
2. **Omni-cart** — a channel-agnostic checkout state machine (`browsing` → `cart_active` → `awaiting_payment` → `paid`) that reconciles a cart snapshot against a charge amount server-side, so a buyer agent cannot under- or over-pay relative to the lines it submitted.
3. **The `transact` skill** — the federation-bound glue that joins them. It accepts a cart and a mandate from an inbound A2A message, cross-checks the requested charge against the cart total, authorizes the charge against the mandate's cryptographic consent, advances the checkout funnel, and returns a structured decision.

The skill is pure and side-effect free: it mirrors the commerce cores. Validation, cross-checking, authorization, and funnel advancement all happen in-process; the only persistence is the caller's responsibility (advancing the mandate's authoritative cumulative spend on an authorized result).

## Opt an agent in

A tenant opts a specific agent into agentic commerce through the agent's existing `config` JSONB. No schema migration, no new credential store, and no new endpoint are required — set the flag on the agent definition you already have:

```bash theme={null}
curl -X PATCH https://api.orbit.devotel.io/api/v1/agents/agent_abc \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "a2a_transact": {
        "enabled": true,
        "merchant": "mnt_acme",
        "currency": "USD"
      }
    }
  }'
```

| Field | Type | Purpose |
| - | - | - |
| `config.a2a_transact.enabled` | boolean | Advertise the `transact` skill on the agent card and accept inbound transact tasks. |
| `config.a2a_transact.merchant` | string \| null | The seller's merchant id; when set, the charge's merchant must match it so a buyer cannot bind the purchase to a different merchant. |
| `config.a2a_transact.currency` | string \| null | Default ISO-4217 currency the seller trades in. |

Until `enabled` is `true`, the `transact` skill is absent from the card and inbound transact tasks are not dispatched to the agent. The agent's discovery mode still governs whether the card is reachable at all — see [A2A federation](/agents/a2a-federation) for the discovery-mode table.

## Authorize a charge

When a buyer agent invokes `transact`, it submits a cart, a mandate snapshot, and the charge it wants to make. The skill runs five checks in order, short-circuiting on the first failure:

1. **Cart non-emptiness** — a cart must contain something to buy (`cart_empty`).
2. **Single currency** — a mixed-currency cart can never reconcile against a single-currency charge or mandate (`cart_mixed_currency`).
3. **Seller-merchant binding** — when the seller has declared a merchant, the charge's merchant must match it (`seller_merchant_mismatch`).
4. **Charge equals cart total** — the requested charge amount must equal the server-derived cart subtotal, and the currency must match (`cart_total_mismatch`). A buyer agent cannot under- or over-charge.
5. **Mandate authorization** — the charge is authorized against the principal-issued mandate: the consent digest is re-verified, expiry and revocation are checked, the merchant and category allowlists are enforced, and the per-transaction and cumulative caps are applied.

The cumulative `totalCap` is enforced against the **seller-authoritative** cumulative spend — the spend already committed under this mandate across prior transact calls, sourced from the seller's own task history — not the `spent` value the buyer agent reports on its submitted snapshot. The buyer fully controls the snapshot it submits, so its self-reported `spent` is not trusted for the cap check; the seller's authoritative spend overrides it before authorization, so the total ceiling holds across calls and a buyer cannot reset it by re-submitting a fresh snapshot.

### The consent digest

Authorization is bound to the **principal-issued mandate's SHA-256 consent digest** — a commitment over the mandate's immutable scope (principal, agent, allowlists, caps, currency, expiry) — not to the platform-wide A2A HMAC secret. The digest is re-verified on every evaluation. Any tampering with the scope changes the digest, so the runtime can prove the mandate presented at charge-time is the exact one the principal consented to. See [Authorization mandates](/agents/authorization-mandates) for the consent-digest model the payment mandate reuses.

### The decision response

On an authorizing decision, the skill commits the spend against the mandate (advancing `spent` and `authorizationCount`, possibly flipping `status` to `exhausted`), drives the checkout funnel to `awaiting_payment`, and returns the structured decision:

```json theme={null}
{
  "status": "authorized",
  "reason": "ok",
  "cart": {
    "cartId": "cart_01",
    "lineCount": 1,
    "itemCount": 2,
    "subtotal": 48.00,
    "currency": "USD",
    "mixedCurrency": false
  },
  "authorization": {
    "authorized": true,
    "reason": "ok",
    "mandateId": "mand_abc",
    "chargeReference": "ref_2026_01"
  },
  "mandate": {
    "id": "mand_abc",
    "spent": 48.00,
    "authorizationCount": 1,
    "status": "active"
  },
  "checkoutState": "awaiting_payment",
  "nextAction": "mint_payment_request"
}
```

A decline returns `status: "declined"` with the specific `reason` that failed and `nextAction: "none"` — the seller mints nothing and the buyer agent surfaces the reason upstream. Cart-level declines (`cart_empty`, `cart_mixed_currency`, `cart_total_mismatch`, `seller_merchant_mismatch`) return `authorization: null` because the mandate was never consulted; mandate-level declines return the authorization detail with the deny reason.

## AP2 and Verifiable-Credential interop

The mandate and the `transact` skill interoperate with agent-payment networks that use W3C Verifiable Credentials as proof: Mastercard Agent Pay (AP2), PayPal, and Google-side agent networks. A mandate issued on one of those networks arrives as an Ed25519-signed Verifiable Credential proof, with the issuer resolved through JWKS or DID document resolution — no shared secret exchanged with the seller.

The seller accepts mandates from a provisioned network the same way it accepts a hosted pay-by-link: the `transact` skill validates the submitted mandate snapshot, re-verifies the consent digest, and authorizes the charge. The proof-of-issuance and the issuer's signing key are resolved through the network's published JWKS or DID endpoint, so a seller admits mandates from agent networks it has configured without holding a per-tenant shared secret. When the selected network is not provisioned for your deployment, the transact path falls back to the standard hosted pay-by-link on an authorized result.

## End-to-end worked sample

A supplement shop publishes an agent (`agent_acme`) with discovery `public` and `config.a2a_transact.enabled = true`. A shopping assistant on another platform discovers the agent card and sees the `transact` skill. A buyer has issued a payment mandate capped at $100/transaction and $500 total, allowlisted to merchant `mnt_acme`.

1. **The buyer agent invokes `transact`** with a cart and the mandate snapshot:

```json theme={null}
{
  "cartId": "cart_01",
  "lines": [
    {
      "productRetailerId": "prod_whey_2kg",
      "name": "Whey Isolate 2kg",
      "quantity": 2,
      "unitPrice": 24.00,
      "currency": "USD"
    }
  ],
  "mandate": {
    "id": "mand_abc",
    "agentId": "agent_acme",
    "principalId": "usr_buyer_42",
    "maxPerTransaction": 100,
    "totalCap": 500,
    "currency": "USD",
    "allowedMerchants": ["mnt_acme"],
    "allowedCategories": [],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "consentDigest": "sha256:9f2c…",
    "expiresAt": 1762665600000,
    "createdAt": 1762579200000,
    "updatedAt": 1762579200000,
    "revokedAt": null
  },
  "charge": {
    "amount": 48.00,
    "currency": "USD",
    "merchant": "mnt_acme",
    "reference": "ref_2026_01"
  }
}
```

2. **The skill evaluates the request.** The cart subtotal is $48.00, single-currency, merchant matches the seller, the charge equals the cart subtotal, and the mandate authorizes a $48 charge within the $100 per-transaction and $500 total caps. The decision comes back `authorized` with `nextAction: "mint_payment_request"`.

3. **The seller mints the pay-by-link.** On the authorized decision, the seller's caller mints a hosted payment request through the existing `POST /api/v1/commerce/payment-request` rail — the same rail a human-driven WhatsApp checkout uses. The buyer agent receives the link and the buyer pays on the hosted checkout page; the PSP capture is reconciled against the cart amount server-side.

4. **The mandate advances.** The seller persists the authorized decision, so the mandate's authoritative cumulative spend reflects $48 on the next call. A subsequent $460 charge still fits the $500 total cap; a $460.01 charge is declined with `total_cap_exceeded`.

The buyer agent never saw a PSP credential, never touched the seller's contact records, and the seller never trusted the buyer's self-reported `spent` — the cap held against the seller-authoritative spend.

## Revocation and audit

A mandate is revocable by either party at any time. The principal revokes consent (a buyer withdraws authority); the seller revokes the agent's ability to spend (a tenant severs an agent). Revocation is terminal: a revoked mandate authorizes no further charges, and a charge attempted against a revoked mandate is declined with `mandate_revoked` before any pay-by-link is minted.

Every transact evaluation, every mandate issue and revoke, and every registry mutation is audit-logged on per-tenant tables, so the full federation edge — peer discovery, mandate issuance, each transact decision, revocation — is attributable to an operator from your side alone. See [Agent identity governance](/compliance/agent-identity-governance) for the tenant-owned inventory and decommission controls that govern the agent identities that issue and spend against mandates.

## See also

* [A2A federation](/agents/a2a-federation) — the endpoint-by-endpoint reference: discovery modes, the two transports, the peer registry the transact skill rides on.
* [Set up A2A federation between tenants](/guides/a2a-federation-setup) — the working order of operations for standing up the federation edge this skill requires.
* [Authorization mandates](/agents/authorization-mandates) — the consent-digest model the payment mandate reuses.
* [Agent identity governance](/compliance/agent-identity-governance) — tenant-owned inventory and bulk decommission for the agent identities that transact.
* [Commerce hub overview](/guides/commerce-hub-overview) — the five checkout rails, including the agent-mandate and storefront sub-surfaces.
* [Commerce API reference](/api-reference/commerce) — the payment-request and mandate endpoints the transact skill bridges.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.