Agentic Rails Atlasby merces.ai

Persona

Enterprise commerce architect

Wants control, merchant-of-record status, customer data and predictable integration cost.

Verified (verified under 30 days ago)

Role

Goals

  • Expose one commerce API (ACP, UCP, or both) that every agent surface can use, backed by the existing order management system.
  • Stay merchant of record: own the order, the tax calculation, the customer relationship and the first-party data.
  • Verify agent identity at the edge (TAP, Web Bot Auth) before the agent reaches catalog or checkout endpoints.
  • Accept agent-initiated payments through the existing PSP with the same tokenization and 3DS flows.
  • Keep a signed record of what the agent and the user authorized, for use in disputes.
  • Budget the integration once instead of chasing a new protocol every quarter.

Pains

  • ACP, UCP, TAP and MPP each define their own headers, signing rules and discovery files, and vendors keep renaming fields.
  • Spec and schema drift (for example the ACP item quantity field) breaks integrations between dated versions.
  • Platform checkout can bypass merchant analytics pixels and loyalty logic, and the merchant loses the customer record.
  • RFC 9421 signing is required in several places but with different covered components and algorithms (Ed25519 in TAP samples, ES256 in UCP).
  • No liability shift exists for agent transactions, so a disputed agent order costs the merchant the same as any fraud case.
  • TAP terms are revocable and require full conformance within six months of any Visa change.

Decisions they own

  • Which protocols to implement natively and which to reach through the PSP or a commerce platform.
  • Which agents to admit: only those verified by a key directory, only registered agents on a trusted list, or all signed traffic.
  • Where to enforce purchase limits and escalation: in the merchant API, in the PSP, or at the CDN.
  • Whether to require an AP2 mandate or Verifiable Intent before accepting an agent order.
  • How long to retain signatures, mandates and intent traces for dispute evidence.

Vocabulary

  • merchant of record
  • checkout session
  • idempotency key
  • RFC 9421
  • Signature-Input
  • Content-Digest
  • well-known
  • capability
  • payment handler
  • network token
  • 3DS2
  • webhook
  • order management
  • intent_trace

Each protocol from this seat

Relevance levels: High, a main persona on the protocol page; Medium, owns, implements or verifies a step; Low, relies on or observes a step; None, no role found in the protocol page.

ERC-8004: Trustless Agents

Relevance: None

Not one of the main personas on the ERC-8004: Trustless Agents page. The responsibility table gives this persona no step.

x402

Relevance: None

Not one of the main personas on the x402 page. The responsibility table gives this persona no step.

Visa Trusted Agent Protocol

Relevance: High

Runs a large online store that wants to serve Visa-approved agents, recognize returning customers and take payment data in a signed container. Source [1, 2, 3, 4]

Goals

  • Sell to customers who shop through agents
  • Recognize returning customers from the ID Token
  • Reduce fraud on agent checkouts

Pains

  • Proprietary terms that require updates within six months
  • No test vectors for the body object signatures
  • Personal data in contextualData that brings privacy duties

Implements

  • Verification of agenticConsumer and agenticPaymentContainer
  • A mapping table from obfuscated email and phone values to accounts
  • Decryption of the payment payload with a key onboarded to Visa

Must trust

  • Its CDN's verification of the header signature
  • Visa's ID Token and key store
  • The acquirer and card rules for liability, since TAP sets none

Questions they ask

  • Do I verify the body objects myself or does my CDN do it?
  • What happens to a chargeback on an agent purchase?
  • How do I hash key-entered card data the same way Visa does?

First three steps

  1. Accept the Product Terms and read the merchant specification
  2. Ask the CDN to turn on TAP verification in log-only mode
  3. Onboard a merchant public key for the encrypted payload

Metrics they care about

  • Agent checkout conversion
  • Fraud and chargeback rate on agent orders
  • Share of agent orders matched to existing accounts

A day in the life. Malik leads payments at a fashion retailer. Agents were tripping the bot wall at checkout, so he asks the CDN to let TAP-signed requests through. His team then builds the merchant side: compare each body object's nonce with the header nonce, verify the signatures, and decrypt the payload. The ID Token does not give emails in the clear, so they build a table that maps obfuscated values to existing accounts. Legal asks who carries a dispute on an agent order. He finds no agent-specific rule from Visa and books the orders as ordinary tokenized card-not-present sales for now.

Steps in the responsibility table

  • Relies onOnboard the agent and register its key
  • Relies onHost the key store (JWKS)
  • VerifiesSign each request with a TAP tag
  • ImplementsVerify header signature, window and nonce
  • VerifiesSign the consumer and payment objects
  • OwnsVerify body objects and process payment data
  • Relies onAuthorize the card payment
  • ImplementsHandle a dispute on an agent purchase

Agentic Commerce Protocol (ACP)

Relevance: High

Builds and runs its own ACP server: checkout endpoints, order webhooks, discovery and feeds, often across several agent surfaces. Source [5, 6, 7, 8, 9]

Goals

  • One integration for several agent platforms
  • Keep pricing, tax and fraud logic authoritative
  • Reuse existing order management

Pains

  • Released spec folders change after release
  • OpenAI docs and the spec disagree on status codes and names
  • UCP asks for a similar but different integration

Implements

  • /checkout_sessions endpoints with idempotency storage for 24 hours or more
  • Payment handlers and PSP charging of vault tokens
  • Signed order_create and order_update webhooks
  • /.well-known/acp.json

Must trust

  • Agents to render totals and messages as returned
  • The PSP to reject out-of-allowance charges
  • Bearer keys to stay secret on both sides

Questions they ask

  • Which version should we pin, and at which commit?
  • Do we run ACP and UCP side by side?
  • How do we map our order states to the ACP order status list?

First three steps

  1. Pin a commit of spec/2026-04-17 and validate your examples against it
  2. Implement idempotency exactly as RFC section 6 says
  3. Add the docs-versus-spec differences to your test suite

Metrics they care about

  • Conversion by agent surface
  • Idempotency conflicts and replays
  • Chargebacks on agent orders
  • Latency of create and complete

A day in the life. Lena's team at a home goods retailer built an ACP server in a sprint. The hard part was not the endpoints but the drift: the RFC examples sent items with a quantity that their schema validator rejected, so they followed the JSON Schema and the repository's examples file. They store every idempotency key for 48 hours and return 422 on a changed body, while their client library also tolerates 409 because OpenAI's checklist says so. A month later they publish acp.json and start a UCP adapter, reusing the same order service but a separate checkout layer.

Steps in the responsibility table

  • OwnsPublish /.well-known/acp.json
  • ImplementsCreate and update the checkout session
  • OwnsReturn authoritative totals and messages
  • ImplementsCharge the token inside the allowance
  • OwnsCreate the order (merchant of record)
  • ImplementsSign and verify order webhooks
  • OwnsHandle refunds and chargebacks

UCP

Relevance: High

The business: publishes /.well-known/ucp, runs the checkout endpoints, sets status and totals, and stays merchant of record. Source [10, 11, 12, 13, 14]

Goals

  • Sell through AI Mode, Gemini and other agent surfaces without one integration per platform
  • Keep the customer relationship, its PSP and its own terms
  • Hand off to its own web checkout whenever policy needs the buyer

Pains

  • Two-layer negotiation and full-replacement updates are easy to get subtly wrong
  • Attribution gaps when checkout happens on a platform surface
  • Reported automatic enrollment of Shopify merchants in Google's native checkout without an explicit opt-in

Implements

  • The business profile with capabilities, payment handlers and a keys array
  • REST or MCP checkout endpoints with idempotency storage of 24 to 48 hours
  • continue_url handoff, confirmation emails and signed order webhooks

Must trust

  • The platform profile and keys named in UCP-Agent
  • The credential provider's handler and the token its PSP receives
  • Google to route traffic as documented in its FAQ

Questions they ask

  • Which capabilities and extensions should we advertise first?
  • Does our PSP process Google tokens?
  • When should we return requires_escalation instead of an error?

First three steps

  1. Read the v2026-08-25 overview and the checkout spec at the tag, not on main
  2. Run the samples REST server and the conformance suite against it
  3. Publish a minimal profile with checkout and one payment handler

Metrics they care about

  • Checkout completion rate by platform
  • Escalation rate and continue_url conversion
  • Idempotency conflicts (409) and duplicate orders

A day in the life. Dana leads commerce engineering at a home-goods retailer. Her team publishes a profile at /.well-known/ucp with checkout, fulfillment and a Google Pay handler, and keeps its own PSP. The first week, agent orders arrive through AI Mode, and the platform's profile and signature check out on every call. Large furniture orders need a delivery window that their API cannot take, so the checkout returns requires_escalation with a continue_url to the store's own page. Conversion on that path is lower, so she adds a scheduling field to the next release. The merchant-of-record question never comes up: refunds and disputes stay with her team, exactly as before.

Steps in the responsibility table

  • OwnsPublish /.well-known/ucp with keys
  • VerifiesAdvertise UCP-Agent and verify the platform profile
  • OwnsCompute the capability intersection
  • VerifiesFill the checkout (full-replacement updates)
  • Relies onReview and place the order in a trusted UI
  • OwnsEscalate with continue_url
  • Relies onIssue the opaque token
  • Relies onAuthorize and settle the token
  • OwnsSign the checkout and verify the AP2 mandate
  • OwnsSend signed order webhooks
  • OwnsHandle refunds and disputes

AP2

Relevance: High

Merchant: signs every checkout, verifies Checkout Mandates and open-mandate constraints, and returns Checkout Receipts. Source [15, 16, 17, 18]

Goals

  • Accept agent orders with proof of user approval
  • Keep their own checkout and payment stack
  • Clear errors when agents misbehave

Pains

  • Signature rule conflict for the Checkout JWT (issue 268)
  • Line-item matching needs a max-flow style check
  • No proof of production use to justify the work

Implements

  • checkout_jwt signing with ECDSA
  • Checkout Mandate and constraint verification
  • Checkout Receipt JWT with status and errors
  • The UCP extension when selling through UCP

Must trust

  • Its processor to verify the Payment Mandate
  • The agent to forward the exact checkout_jwt
  • Its signing key custody

Questions they ask

  • Should I sign checkouts with ES256 or Ed25519?
  • How strictly do I match line items?
  • Which UCP errors do I return?

First three steps

  1. Sign checkouts with ES256 and include enough entropy
  2. Implement checkout_hash comparison against the latest checkout_jwt
  3. Add UCP dev.ucp.common.payment.ap2_mandate to /.well-known/ucp if you sell through UCP

Metrics they care about

  • Share of agent orders with valid mandates
  • Constraint rejections per day
  • Chargebacks on agent orders

A day in the life. Tomas leads checkout engineering at an outdoor retailer that sells through UCP. His team signs every checkout with ES256 because the specification forbids deterministic signatures, even though their bot-auth setup already uses Ed25519, so they now manage two key types. Today an agent presents a closed Checkout Mandate for a tent, but the cart has a different color than the open mandate allows. His service evaluates checkout.line_items, finds no match and returns a Checkout Receipt with unresolved_constraint. Ten minutes later the same order comes back with a user-signed closed mandate and goes through. He logs the round trip for the weekly report.

Steps in the responsibility table

  • OwnsSign the checkout (checkout_jwt)
  • OwnsVerify the Checkout Mandate and constraints
  • OwnsReturn signed receipts
  • ImplementsVerify mandates and receipts in a dispute
  • ImplementsSet retention and consent policy

Mastercard Agent Pay

Relevance: None

Not one of the main personas on the Mastercard Agent Pay page. The responsibility table gives this persona no step.

Sources

  1. Trusted Agent Protocol merchant specifications (external link)Visa. Specification, primary source. Accessed .
  2. Trusted Agent Protocol Product Terms (external link)Visa. Documentation, primary source. Published . Accessed .
  3. Agentic commerce liability is still being written (external link)Worldpay. Analysis. Published . Accessed .
  4. Securing agentic commerce: helping AI Agents transact with Visa and Mastercard (external link)Cloudflare. Analysis, primary source. Published . Accessed .
  5. ACP JSON Schema, Agentic Checkout, 2026-04-17 (external link)Agentic Commerce Protocol project. Specification, primary source. Accessed .
  6. RFC: Agentic Checkout, Merchant REST API (external link)Agentic Commerce Protocol project. Specification, primary source. Accessed .
  7. ACP 2026-04-17 checkout examples (examples.agentic_checkout.json) (external link)Agentic Commerce Protocol project (OpenAI and Stripe). Specification, primary source. Accessed .
  8. Agentic Commerce (OpenAI developer documentation; full Markdown export at /commerce/llms-full.txt) (external link)OpenAI. Documentation, primary source. Accessed .
  9. RFC: Agentic Checkout, Discovery (external link)Agentic Commerce Protocol project. Specification, primary source. Accessed .
  10. UCP Official Specification overview (v2026-08-25) (external link)UCP Authors. Specification, primary source. Published . Accessed .
  11. Checkout Capability (v2026-08-25) (external link)UCP Authors. Specification, primary source. Published . Accessed .
  12. Frequently Asked Questions, Google UCP Guide (external link)Google. Documentation, primary source. Accessed .
  13. Google Universal Commerce Protocol (UCP) Guide (external link)Google. Documentation, primary source. Accessed .
  14. Google switched on AI Mode checkout for Shopify stores without asking (external link)PPC Land. News. Published . Accessed .
  15. Agentic Payment Protocol (v0.2) specification (external link)Google (google-agentic-commerce). Specification, primary source. Published . Accessed .
  16. Issue 268: Checkout JWT algorithm constraint forces dual keys under WBA (and conflicts with normative Security and Privacy guidance) (external link)GitHub (igrigorik). Other, primary source. Published . Accessed .
  17. AP2 Checkout Mandate (external link)Google (google-agentic-commerce). Specification, primary source. Published . Accessed .
  18. UCP AP2 Mandates Extension (external link)Universal Commerce Protocol. Specification, primary source. Published . Accessed .

Source details

    Loading the index.

    Enter open Esc close ? shortcuts