Agentic Payment Protocol (v0.2)¶

The Agentic Payment Protocol (AP2) provides a protocol to secure Agent-performed payment transactions. It makes use of the Agent Authorization model.

This specification describes the following:

The different roles of entities within AP2.
The verification responsibilities of these roles.
A Checkout Mandate and Receipt for securing what is being purchased.
A linked Payment Mandate and Receipt for the payment of the Checkout.
How the Checkout and Payment Mandates can be used as evidence at the time of dispute.

AP2 operates as a security feature within a Commerce Protocol. The exact details of the Commerce Protocol (e.g., catalog APIs, checkout updates, and specific APIs for communication between the different roles) are outside the scope of AP2. AP2 is designed explicitly to be compatible with the Universal Commerce Protocol (UCP) and integrates seamlessly.

Illustrative examples are provided for Human Present ('direct') and Human Not Present ('autonomous') flows.

Roles¶

AP2 considers five roles, who have different responsibilities from a processing and verification perspective. These are as follows:

Shopping Agent (SA): The Shopping Agent is the primary agent performing product discovery, building the checkout, and executing the purchase.
Credential Provider (CP): The Credential Provider is the source of Payment Credentials for the purchase. They are responsible for verifying that this Agent is authorized to access this Payment Credential, and scoping the Payment Credential appropriately.
Merchant (M): The Merchant role is responsible for providing and completing the Checkout. They verify that the Shopping Agent is approved to purchase these particular items and are responsible for the integrity of the inventory, pricing, and any merchant discounts.
Merchant Payment Processor (MPP): The Merchant Payment Processor role is responsible for processing payments for purchases. They are responsible for verifying that the Payment Credential shared by the Credential Provider has been authorized to pay for this Checkout instance.
Trusted Surface (TS): The Trusted Surface role is a UI surface that is trusted to get informed user consent for an Intent before creating a user-signed Mandate.

Note: While AP2 defines five roles, it is possible for a single entity to play multiple (or even all) of the roles. In that case, they would take on all of the responsibilities of each role they are playing.

Roles MAY always delegate their responsibilities to another party.

Agentic vs Non-Agentic¶

Many of these roles can be considered Agentic or Non-Agentic. A role is Agentic when:

Communication to or from the Role is handled by a non-deterministic LLM.

A role is considered Non-Agentic if:

Communication to and from the Role is handled using deterministic code that verifies the authenticity and correctness.
And if no processing done by the role is delegated to an LLM.

The following roles MAY be agentic or non-agentic:

Merchant
Merchant Payment Processor
Credential Provider

The following role MUST be non-agentic:

Trusted Surface

The following role is expected to be agentic:

Shopping Agent

When communication happens between two non-agentic Roles, standard web security is sufficient to ensure integrity. However, when either role is agentic, then the Agent itself is a potential attacker. As such, additional tamper-evident mechanisms are needed to ensure secure communication.

AP2 assumes that, at a minimum, the Shopping Agent is agentic. In the case where the payment journey happens directly between two non-agentic surfaces (such as a Trusted Surface communicating directly with a non-agentic Merchant), then existing e-commerce security models are sufficient.

When this document refers to validation or processing for a particular role, it MUST happen in deterministic code regardless of whether the role is agentic or not.

Mandates¶

Mandates are the core means that AP2 uses to authorize agents. See [Agent Authorization Framework][agent_authorization.md] for a description of how this works in the general case.

AP2 defines two Mandate types: Checkout Mandate and Payment Mandate.

The Checkout and Payment Mandate contents are assembled by the Shopping Agent after it has determined what task the user wishes it to perform. The exact details of how this is achieved is outside of the scope of this specification.

The Shopping Agent then uses a Trusted Surface to obtain signed Checkout and Payment Mandates, which it will use to authorize payment and complete the Checkout.

Checkout Mandate¶

The Checkout Mandate is designed to provide the Merchant cryptographic proof that the Shopping Agent is authorized to purchase the Checkout that it has assembled.

The Checkout Mandate is provided by the Shopping Agent and verified by the Merchant.

The The Merchant MUST provide a merchant-signed JWT containing the Checkout to the Shopping Agent. The closed Checkout Mandate is bound to this Checkout JWT using a cryptographic hash.

Once the Merchant has accepted or rejected the Checkout Mandate, it MUST return a Checkout Receipt.

For the full details of the Checkout Mandate and Receipt structures, see Checkout Mandate.

Mandate Versioning¶

Each AP2 Mandate type identifies its schema using the vct claim. The vct value includes a numeric suffix that acts as a schema version number (e.g. mandate.payment.1, mandate.checkout.open.1). Implementations MUST match the exact vct string, including the version suffix. A future incompatible schema revision would introduce a new suffix (e.g. .2), allowing old and new versions to be distinguished unambiguously.

Payment Mandate¶

The Payment Mandate is designed to provide the Credential Provider, Network, and Merchant Payment Processor cryptographic proof that the Shopping Agent is authorized to pay for a particular Checkout.

The Payment Mandate is provided by the Shopping Agent and verified by the Credential Provider, Network, and Merchant Payment Processor.

The Payment Mandate is bound to a particular Checkout using the cryptographic hash of the Checkout JWT. To prevent rainbow table attacks, the Checkout JWT MUST be signed using a digital signature scheme (e.g., ECDSA) and not a deterministic signature (e.g., Ed25519).

Once the Merchant Payment Processor has accepted or rejected the Payment Mandate, a signed Payment Receipt MUST be returned to the Shopping Agent, Credential Provider, and possibly Networks.

For the full details of the Payment Mandate and Receipt structures, see Payment Mandate.

Modes¶

There are two modes that AP2 can consider to operate in.

Human Present (Direct): The User directly sees the closed Checkout and approves it and its payment explicitly.
Human Not Present (Autonomous): The User sees and approves a set of constraints over what closed Checkout and Payment would meet their intent. The Shopping Agent then assembles and approves a closed Checkout and Payment Mandate on their behalf using these open Mandates.

Verifiers of Mandates always receive a closed Payment and Checkout Mandate, regardless of the mode. The difference is only in how the verification of the Mandate is performed.

In the Direct case, the signature on the closed Mandates is validated as coming from a User directly, using a User Credential or a trust list of Agent Providers.

In the Autonomous case, the closed Mandates are signed by an Agent key. Trust in this key is provided by open Mandates that are signed by the User or a trust list of Agent Providers. Constraints in these Mandates allow the verifier to verify that the Checkout and Payment match the User's intent. Only constraints relevant to the closed Mandates are shared with the verifier.

Direct (Human Present)¶

When a Shopping Agent has a Checkout JWT for the closed Checkout from the Merchant, they construct the Checkout and Payment Mandate Content and pass it to a Trusted Surface for display to the user and signing.

Upon receiving the Checkout and Payment Mandate, the Shopping Agent forwards the Payment Mandate to the Credential Provider (and possibly the Network) for Verification. Upon successful verification, the the Shopping Agent receives a payment credential.

The payment credential and a Checkout Mandate are then provided to the Merchant. The The Merchant verifies the Checkout with what it created, and initiates payment with the Merchant Payment Processor if a Merchant-initiated charge.

In the case that the payment method pushes funds to the Merchant, the Merchant will instead receive confirmation of funds sent, and confirm the receipt of those funds.

Upon completion, a Checkout Receipt is returned to the Shopping Agent, and the Payment Receipt is returned to the Shopping Agent, Credential Provider and, if applicable, the Network.

See Human Present for a detailed example.

Note: Because the User approves the closed Checkout, this can often be replaced with a traditional e-commerce journey where the Merchant and the Trusted Surface communicate directly.

Autonomous (Human Not Present)¶

When a Shopping Agent needs to operate autonomously, it will create open Checkout and Payment Mandate Content and have these authorized by the Trusted Surface. These MUST include the agent's public key as a cnf claim. This is required as it is not yet bound to a particular transaction, and so it needs to be constrained for use by the Agent. It is RECOMMENDED to set the exp claim for these Mandates to the smallest value that will allow the Shopping Agent to complete the assigned task.

After the Shopping Agent has created an appropriate Checkout, to authorize the Checkout, the Shopping Agent MAY now sign it using its Agent Key instead of getting approval on a Trusted Surface. It then MUST provide both the user-signed open Mandate and the agent-signed closed Mandate to the Verifying Parties, as described in the Direct case above.

Shopping Agents MUST NOT present any subsequent open Payment or Checkout Mandates without receiving a rejection receipt from the previous one. This is to prevent an Agent approving multiple different Checkouts using the same open Mandate.

To ensure user privacy, Shopping Agents MUST present only the disclosures from the open Mandates needed in the evaluation of the closed Mandates.

Upon completion, a Checkout Receipt is returned to the Shopping Agent, and the Payment Receipt is returned to the Shopping Agent, Credential Provider and, if applicable, the Network.

See Human Not Present for a detailed example.

Note: In the current specification, the Shopping Agent needs to determine the applicable Mandates and Disclosures ad-hoc based on the Checkout. In the future, utilizing an explicit query language in the commerce protocol can help practical interoperability.

Agent-to-Agent Delegation¶

Conceptually, it is possible to use this protocol to support delegation of Mandates from one Shopping Agent to another. This is outside the scope of the current specification.

Dispute Evidence¶

In the case of a dispute, the Checkout Mandate and Receipt, and Payment Mandate and Receipt can be brought together to provide a non-repudiable picture of the transaction. Specific details of how this is used for dispute resolution, retention, and retrieval requirements are outside the scope of this specification.

The Checkout Mandate and Receipt MAY be able to be provided by the following roles:

Shopping Agent
Merchant

The Payment Mandate and Receipt MAY be able to be provided by the following roles:

Shopping Agent
Credential Provider
Network
Merchant Payment Processor

See Verification: Dispute for the verification rules.

Note: Providing an automated method to retrieve the Checkout Mandate, from either the Shopping Agent or the Merchant, would provide substantial utility to the ecosystem. The exact details are outside the scope of the current version, but would be done by using the Payment Mandate transaction_id as the key to request it.

Verification¶

The following verification rules MUST be followed by these roles upon receipt of the Mandate.

Note: A particular role can always delegate the responsibilities to a technology provider. For example, a Merchant could have their payment processor perform verifications on their behalf. In such a case, the delegate follows the verification rules for that role instead.

Merchant¶

The Merchant MUST receive an appropriate Checkout Mandate from a Shopping Agent before completing the Checkout.

They MUST verify the Checkout Mandate as follows:

Process and verify the Checkout Mandate according to Verification and Processing Rules.
Verify that the hash of the Checkout JWT sent for approval matches the value included for the checkout_hash claim.
If open Checkout Mandates are included, verify that the closed Checkout conforms to all of the Constraints by evaluating each Constraint.

If any step fails, the Merchant MUST return a Checkout Receipt JWT containing the appropriate error message.

Credential Provider and Network¶

The Credential Provider and, if applicable, the Network MUST receive an appropriate Payment Mandate from the Shopping Agent before returning a payment credential.

They MUST verify the Payment Mandate as follows:

Process and verify the Payment Mandate according to Verification and Processing Rules.
If open Payment Mandates are included, verify that the closed Payment Mandate matches all the Constraints.

If any step fails, they MUST return a Payment Receipt JWT containing the appropriate error to the Shopping Agent.

Merchant Payment Processor¶

The Merchant Payment Processor MUST receive an appropriate Payment Credential from the Merchant before processing the transaction.

Merchant Payment Processor MUST verify the Payment Credential is appropriately scoped to the Checkout. One way this can be done is by providing the Closed Payment Mandate inside the Payment Credential.

Dispute¶

When performing verification at the time of dispute, the following steps MUST be followed to ensure the integrity of the Payment and Checkout Mandate and Receipts.

The Checkout Mandate MUST be verified according to the Merchant Verification rules.
The hash of the checkout_jwt MUST be independently computed from the included checkout_jwt.
The Checkout Receipt reference MUST match the hash of the closed Checkout Mandate. This is calculated in the same manner as the sd_hash would be.
The Payment Mandate MUST be verified according to the Merchant Payment Processor section using the checkout_hash from the Checkout Mandate.
The Payment Receipt reference MUST match the hash of the closed Payment Mandate. This is calculated in the same manner as the sd_hash would be.

After all these steps have been performed successfully, then the information contained in the Checkout Mandate and Payment Mandate is able to be used as evidence as to what the user, and each role saw.

Extension Points¶

AP2 provides several extension points to allow it to adapt to meet the needs of Agentic Commerce. These are as follows:

Mandate Constraints¶

This extension point is designed to support constraining Agent behavior, while supporting more complex autonomous use cases. To define a new constraint, the following MUST be specified:

A uniquely defined type.
A Schema, including which fields are selectively disclosable.
The evaluation algorithm.

Checkout Object¶

AP2 is agnostic to the contents of the merchant-signed Checkout JWT. It is created to be compatible with logically represented Checkout Objects, but it does provide an extension point to be adapted to other Checkout Objects. UCP itself also provides such extension points within the protocol, which is the RECOMMENDED way to support new commerce journeys.

Payment Instrument¶

AP2 is agnostic to the particular payment instrument used. New Payment Instruments are supported by defining a unique type in the Payment Instrument JSON object. If necessary, additional properties MAY be defined for that specific type.

Verifiable Digital Credential Formats (VDCs)¶

AP2 specifies the use of SD-JWTs for securing the Payment and Checkout Mandates. Payment and Checkout Mandates could be cryptographically secured by other VDCs as mentioned in Agent Authorization.