Skip to main content

01 · The cast & the journeys

Frame​

An AP2 transaction is a small play with a fixed cast. Knowing who does what — and who is allowed to do what — is most of the battle, because the protocol's guarantees are really statements about which role signs which artifact. There are six roles:

  • The Shopping Agent is the agent that talks to the user, discovers products, builds the cart, and drives the purchase forward. It is the conductor, but notably it is not trusted to fabricate consent or to see sensitive payment data.
  • The Credential Provider is the user's wallet: it holds the payment credentials and releases them under the right conditions.
  • The Merchant owns the catalog, signs the cart, and ultimately fulfills the order. When you need to trust what is being bought and for how much, you trust the merchant's signature.
  • The Merchant Payment Processor submits the transaction into the payment ecosystem for authorization on the merchant's behalf.
  • The Trusted Surface is a non-agentic UI — a screen the user actually trusts — where they review the real terms and give informed, signed consent. This is the one place a human's intent is captured, deliberately kept outside the agent.
  • The Network / Issuer runs the underlying payment rails, issues the credentials, and performs the final authorization, just as it does for card payments today.

These roles play out across two journeys. In the Human-Present journey the user is available right now to approve the payment in the moment. In the Human-Not-Present journey the user is not available at payment time, so they pre-authorize constraints up front and the agent acts later, within those limits, on their behalf.

Build​

The lesson code lays out the cast and both journeys as plain data and step lists:

lessons/01-roles-and-journeys/roles.py
../../lessons/01-roles-and-journeys/roles.py

The ROLES dictionary is the cast list. The two functions are the scripts. Read human_present_steps() top to bottom: the user gives the Shopping Agent a task; the agent assembles a cart with the merchant; the merchant signs the cart contents, producing the Checkout Mandate (a container holding the cart plus the merchant's signature — Lesson 02 shows exactly what's inside); the Trusted Surface shows the cart and the user signs to approve; finally the Payment Mandate is shared with the Network/Issuer and the payment executes. Notice the division of labor — the agent assembles, the merchant attests to the cart, and the human consents on a surface they trust.

human_not_present_steps() tells a different story. The user can't approve in the moment, so they approve constraints in advance — for example, "buy when the price drops below $100." That up-front approval is an open Checkout Mandate: real authority, but not yet bound to any particular cart. The Shopping Agent then waits. When a cart finally satisfies the constraints, the mandate is closed — bound to that specific cart — and payment runs.

Map​

In real deployments these six roles are logical, not necessarily six separate companies. The AP2 overview gives several non-normative examples of roles being combined: a Shopping Agent can host its own Credential Provider (the agent and the wallet are the same product), and a Merchant can act as its own Merchant Payment Processor. The protocol cares about which role signs each artifact, not how many distinct vendors are involved — so collapsing roles is fine as long as the right signatures still appear at the right steps.

Inspect​

Run it from the repo root:

uv run python lessons/01-roles-and-journeys/roles.py

You'll get the cast printed first, then the two journeys as bullet lists. Look closely at the Human-Not-Present output: the step where the open mandate becomes closed once a matching cart exists. That Open→Closed transition is where pre-authorized intent gets bound to a concrete purchase — it foreshadows Lesson 02, where we build mandates by hand, and a future lesson on autonomous, human-not-present delegation.

Check​

  • Which role signs the cart? (The Merchant.)
  • Where does the user actually consent? (On the Trusted Surface.)
  • What flips a mandate from Open to Closed? (A specific cart that satisfies the pre-approved constraints, binding the mandate to that concrete action.)

Further reading: AP2 overview.