Trusted Agent Protocol

By accessing, downloading, or using this specification, you agree to the terms and conditions outlined in the Visa Trusted Agent Protocol Product Terms.

This material outlines the next phase of Agentic Commerce – focusing on how Merchants can recognize when an "approved Agent with commerce intent" is interacting with their website or server and how Merchants can make requests to the Agent (e.g. for payment or additional information).

While it is possible that Agents could have bi-lateral agreements with Merchants and interact through authenticated, secure interfaces, this protocol is applicable to the scenario when the Agent is initially unknown to the Merchant. That is, this protocol is intended for those scenarios [where the Agent is initially unknown] and includes an Agent interacting with a Merchant website or message protocols exposed by a Merchant - and an agent is directed by the user with an intent for commerce.

As agentic commerce becomes more prevalent, we believe this recognition will become necessary, as Merchants (or their Site Protection Providers) will/could confuse these Agent interactions with bots (web crawlers, etc.) or nefarious actors that could be attempting to degrade the Merchant services, be a product reseller of limited-edition releases, or be trying to actively attack the Merchant property. Additionally, it is envisaged that Merchants should have a mechanism to request payment for access to certain information (e.g. customer product reviews) or request additional information from an Agent (e.g. a consumer email address for an unrecognized consumer).

While there are a number of ways that Merchants could identify Agents, such as through user agent headers, allow/white-listing of IP addresses, registries of approved Agents, or shared keys, a more efficient mechanism is to provide linked, verifiable, purpose-identifying, and time-based signed credentials in the headers and/or in the request body of messages when interacting with a Merchant especially when it is originating with a verified intent for commerce. Each of these signatures can be ignored by Merchants that do not adopt, or have not yet adopted, this mechanism.

While there are a number of upstream processes that may occur for an Agent to determine whether a product or service is sold by a Merchant, this protocol is intended during two specific interactions with the Merchant. That is, (1) a browsing interaction, when the Agent has been initiated by a verified consumer with commerce intent and needs to determine further information about a product and whether inventory is available (e.g. in a specific size, color, etc. and shippable to an address) and to determine the final cost of a product after taxes and shipping, and (2) a payment interaction, when the Agent is providing all the information necessary to purchase a product from the Merchant or gain paid access to a Merchant resource.

For Merchants that adopt this mechanism, the purpose of this material is to describe (i) the steps that can be taken to verify each of the signatures, (ii) how the data provided by each signature can be used to identify whether the interaction originated from a trusted Agent, and (iii) how that data can be used to control, limit or complement the interaction.

The protocol is designed to enable agentic commerce at scale with a framework where an Agent can:

• Facilitate verifiable trust over existing web infrastructure (HTTP), with minimal changes required to existing merchant systems
• Securely carry various forms of payment credentials
• Communicate over a variety of channels (e.g., web, API) and protocols (e.g., MCP, ACP)

This material is intended for Merchants and Site Protection Providers to inform them how to recognize approved Agents and verify that the data agents are including in messages comply with the defined requirements.  The document defines the framework for a generic protocol and references Visa’s implementation specifications. Where examples are provided, we label them explicitly as part of the Visa implementation to distinguish them from the broader Trusted Agent Protocol.

Agent Providers (Agent) are certified AI platforms that have been onboarded as an "Agent" to Payment Schemes and are approved and trusted by the respective Payment Schemes to make payments on behalf of thei account holders.

Checkout Enablers may be used by agents to interact with Merchant websites. While the role of these Checkout Enablers is recognized, the only expectation in regard to this proposal is that these entities will pass through [to the Merchant] any message signatures and query parameters provided by the Agents.

Consumers are account holders of respective Payment Schemes that have a profile created at an Agent and have at least one payment credential linked to their profile [for the purpose of being used by the Agent to make purchases on the consumer's behalf].

Site Protection Providers are defined as systems that are typically a layer sitting in front of a Merchant's website. These systems also provide a level of protection to their customers by identifying traffic that could degrade services or be malicious. These are typically CDNs (Content Delivery Networks), trust management systems, or other such proxies.

Identity Provider is an entity that has verified the credentials used to identify a Consumer and can provide a value [containing the verified credential] that can be authenticated by the relying entity [in this case the Merchant or its Site Protection Provider].

Merchants are online entities selling goods or services and that, through their acquirer relationship, accept credentials from Payment Schemes as a payment method for these goods and services. Merchants are not required to use this proposal and do not necessarily have to be registered with the Payment Schemes to accept these payment credentials. Merchants can expose their goods or services directly to Agents through APIs or similar message protocols or through a web protocol. Merchants that expose web sites and can recognize when Agents are visiting their web properties may choose to present an agent-specific experience to the Agent - for example, present simpler html pages and/or scale down the number of checkout pages with less navigation.

Payment Schemes refer to systems that facilitate electronic payments between consumers, merchants, and financial institutions. These schemes set the rules, standards, and infrastructure for Agent initiated transactions, ensuring interoperability, security, and efficiency across various payment channels and third-party payment providers. 

Key Store will be the location on the web where Merchants or Site Protection Providers can retrieve the public keys needed to verify the signatures.

The trust model described hereunder is comprised of three distinct signatures.

• An agent recognition signature provided in the message header (HTTP header, REST API header or similar message header). This signature is intended to ensure that the Agent is a trusted agent interacting with the Merchant in order to retrieve additional information about a specific product/service sold by the Merchant or in order to make an actual purchase. This signature is provided both during the browsing and payment interactions.
• A linked and signed consumer/device identity provided in the message request body. This signature is intended to allow the Merchant to determine whether the consumer that the Agent is shopping on behalf of is known to the Merchant. That is, whether the consumer (through a consumer or device identity) has previously shopped at the Merchant or whether the consumer (through a consumer identity, loyalty number, etc.) has an account at the Merchant. This signature is provided during the browsing interaction and may be provided during the payment interaction.
• A linked and signed payment container provided in the message request body. This signature is intended to provide information related to the payment credentials and information necessary to complete or complement a purchase. The content provided in the signature is dependent upon the mechanism being used to interact with the Merchant and may contain a range of information. For example, if browser automation is being used to complete a web-based guest checkout, key entry experience, this signature may contain a hash of the payment credential data that will be key entered, while if the protocol allows the complete payment payload , this signature may contain all the data necessary to complete the payment. This signature can be provided during the payment interaction or at any point the Merchant is requesting a payment.

The following description is for any agent-to-merchant interaction and defines how a Merchant should verify the Message Signature.

The Message Signature will follow the RFC9421 standard (https://datatracker.ietf.org/doc/html/rfc9421#section-2.3-3) and contain the below minimum set of parameters that are required to be present for a trusted Agent.

Sample Browsing Request with Message Signature

URL:
    https://www.example.com/example-product
Request Headers:
  Accept:
  User-Agent:
  Signature-Input: sig2=("@authority" "@path");
     created=1735689600;
     keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";
     alg="Ed25519";
     expires=1735693200;
     nonce="e8N7S2MFd/qrd6T2R3tdfAuuANngKI7LFtKYI/vowzk4lAZYadIX6wW25MwG7DCT9RUKAJ0qVkU0mEeLElW1qg==";
     tag="agent-browser-auth"
  Signature: sig2=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA==:

Sample Checkout Request with Message Signature

URL:
    https://www.example.com/checkout
Request Headers:
  Accept:
  User-Agent:
  Signature-Input: sig2=("@authority" "@path");
    created=1735689600;
    keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";
    alg="Ed25519";
    expires=1735693200;
    nonce="e8N7S2MFd/qrd6T2R3tdfAuuANngKI7LFtKYI/vowzk4lAZYadIX6wW25MwG7DCT9RUKAJ0qVkU0mEeLElW1qg==";
    tag="agent-payer-auth"
  Signature: sig2=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA==:

Required Message Signature Fields

Below is the minimum list of fields required to be a trusted Agent. An Agent or a Payment Scheme may optionally define additional fields that could be part of the signature.

Verification Steps

The Merchant should perform the following steps to verify that the message being received has not been manipulated in any way, is not being replayed or relayed, and has been signed using a key maintained by a trusted agent.

• If the header does not contain a message signature with a Signature-Input field containing a tag of either agent-browser-auth or agent-payer-auth, the message has not been signed by a trusted agent. The Merchant may decide to block the message or use some other mechanism to determine whether the interaction can continue. The following steps only apply if the Signature-Input field contains a tag of either agent-browser-auth or agent-payer-auth.
• Minimum fields
  • If any of the fields listed in the table above are missing, the message should be blocked.
• Timestamps
  • The timestamps (created and expired) should fall within the current GMT time and should not be more than 8 minutes apart. That is, if the interval between the created and expired timestamps is greater than 8 minutes, or if the created timestamp is not in the past, or the expired timestamp is not in the future, the message should be blocked.
• Nonce
  • If maintaining a record of all nonces received in the last 8 minutes, if the nonce received matches a recorded nonce, the message should be blocked.
• Locate the public key
  • If the public key for the keyid in the Signature-Input field has not been previously retrieved and cached, refer to the Public Keys Retrieval Service section for details of how to retrieve the public key. If the public key cannot be retrieved or the public key has expired, the message should be blocked.
• Validate the signature
  • Create the signature base string. The signature base string is a canonical representation of critical request attributes—such as the authority, path, signature agent, timestamps, key identifier, nonce, and tag—formatted in a precise, structured manner. This ensures that both sender and receiver reconstruct the exact same data for signing and verification, and any alteration in order, spacing, or values will cause validation to fail.
  • Provide the signature base string and public key to the library used to validate the signature.
  • If signature validation fails, the message should be blocked.

If none of the steps above result in the message being blocked, and signature validation is successful, this implies that the signature was generated by a trusted agent and that the Agent is interacting with the Merchant to retrieve information about a specific product/service or attempting to make a payment to the Merchant for product(s)/service(s).

Based on this validation the Merchant can allow the interaction to continue while still potentially limiting the interaction to these specific steps.

An Agentic Consumer Recognition Object is provided in the message request body and contains consumer recognition data and a signature that links the content provided in the object to the message signature. That is, the Agentic Consumer Recognition Object contains a signature signed with the same private key used to sign the message signature and one of the fields signed is the same nonce present in the message signature.

The Agentic Consumer Recognition Object may contain one of more fields that can be used by the Merchant to identify the consumer that an Agent is acting on behalf of. For Visa Intelligent Commerce, Visa will provide an ID Token (see ID token section) but additional fields, such as consumer device identifiers, country and postal code, a loyalty number or an identity token provided by another entity may also be present.

The Agentic Consumer Recognition Object comprises at least the following 5 fields being present in the Object:

The following is a JSON example of the above fields as provided in the request body as defined in this material:

"agenticConsumer" {
  "nonce" : "e8N7S2MFd/qrd6T2R3tdfAuuANngKI7LFtKYI/vowzk4lAZyadIX6wW25MwG7DCT9RUKAJ0qVkU0mEeLElW1qg==",
  "IdToken" : { },
  "contextualData" : { },
  "kid" : "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U",
  "alg" : "PS256",
  "signature" : "jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA=="
}

The following section describes the processes used to validate the Agentic Consumer Recognition Object and describes the steps that can be taken to verify the signed content.

In the context of Visa Intelligent Commerce, Agents are expected to interact with a Merchant site at two points.

• The first point is when the Agent is navigating to a product detail page in order to retrieve more details about a specific product (for example, determine what materials were used in the production process) or, to determine whether the product is currently available is a specific size or color, etc.
• The second point is when the Agent is navigating to a checkout page to complete the purchase

Both of the above interactions may contain an Agentic Consumer Recognition Object and as such this section details the steps for both interactions.

The following description is for any agent-to-merchant interaction and defines how a Merchant should verify the Agentic Consumer Recognition Object.

Verification Steps

The Merchant should perform the following steps to determine whether the object being received has not been manipulated in any way, is not being replayed or relayed and has been signed using a key maintained by a trusted agent. It is at the discretion of the Merchant to determine whether the content of the object is usable even if verification is not successful.

• Minimum fields
  • If any of the fields listed in the table above are missing, the content may be inaccurate.
• Nonce
  • If the nonce contained in the object does not match the nonce received in the message signature, the content of the object may be inaccurate even if the signature verification is successful.
• Locate the public key
  • If the public key for the kid field has not been previously retrieved and cached, refer to the Public Keys Retrieval Service section for details of how to retrieve the public key. If the public key cannot be retrieved or the public key has expired, the content of the object may be inaccurate.
• Validate the signature
  • Create the signature base string. The signature base string is a canonical representation of all fields in the object in the order received except for the signature itself. This ensures that both sender and receiver reconstruct the exact same data for signing and verification, and any alteration in order, spacing, or values will cause validation to fail.
  • Provide the signature base string and public key to the library used to validate the signature.
  • If signature validation fails, the content of the object may be inaccurate.

If signature validation is successful, this implies that the signature was generated by a Visa trusted agent and that the Agent is interacting with the Merchant to retrieve information about a specific product/service or attempting to make a payment to the Merchant for product(s)/service(s). Based on this validation, or even if the validation was not successful, the Merchant may use the data to determine if they have a relationship with the consumer the Agent is acting on behalf of.

If the Merchant is using the Visa ID Token to determine whether they have an account for the consumer, as no identities are provided in the clear, the Merchant must also maintain a mapping table that can be used to match a hashed phone number or hashed email address to an actual phone number or email address of their account holder.

This section describes the potential usage of each of the fields in the Contextual Data object present in the Agentic Consumer Recognition Object.

Contextual Data (contextualData)

The object contains the following fields.

• countryCode – 2-digit country code as per ISO 3166-1 alpha-2 country code
• zip – 16 characters containing either a zip/postal code or a city/state combination
• ipAddress – IP Address of the consumer's device collected during Payment Instruction
• deviceData – A Device Data object of the consumer's device collected during Payment Instruction

This data can be used by a Merchant to determine whether a previous interaction occurred using the same device data and ipAddress and/or optimize the information provided based on the location information.

An Agentic Payment Container object is provided in the message request body and contains payment data and a signature that links the content provided in the object to the message signature.

That is, the agentic payment container object contains a signature signed with the same private key used to sign the message signature and one of the fields signed is the same nonce present in the message signature.

The Agentic Payment Container object may contain one of more fields that can be used for processing of a payment. While the implementation of this may vary depending on type of payment method used, the following is an example of how this will be implemented in the case of Visa Intelligent Commerce where the fields present are dependent on what type of payment the Merchant is requesting or how the Merchant has indicated that the payment will be processed. For example:

• If the Merchant has requested a payment using a 402 response code, a payment IOU will be present
• If the Merchant is expecting payment through a guest checkout, key entry form, a hash of the payment credentials will be present.
• If the Merchant is expecting a network token, a complete payment object will be present.
• In addition to payment data, card meta data may also be present.

The Agentic Payment Container object comprises at least the following 4 fields being present in the Object:

The following is a JSON example of the above fields including a payment credential hash as provided in the request body as defined in this material:

"agenticPaymentContainer" {
  "nonce" : "e8N7S2MFd/qrd6T2R3tdfAuuANngKI7LFtKYI/vowzk4lAZyadIX6wW25MwG7DCT9RUKAJ0qVkU0mEeLElW1qg==",
  "paymentCredentialsHash" : { }
  "kid" : "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U",
  "alg" : "PS256",
  "signature" : "jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA=="
}

The following section describes the processes used to validate the Agentic Payment Container and describes the steps that can be taken to verify the signed content.

While the implementation of this may vary depending on type of payment method used, the following example demonstrates how this will be implemented for Visa Intelligent Commerce. Agents can be expected to interact with a Merchant site at two points.

• The first point is when the Agent is navigating to a product detail page in order to retrieve more details about a specific product (for example, determine what materials were used in the production process) or, to determine whether the product is currently available is a specific size or color, etc.
• The second point is when the Agent is navigating to a checkout page to complete the purchase

In addition to these 2 points, as there may be many instances where an Agent is required to make a payment, this section details the steps for any such interactions.

The following description is for any agent-to-merchant interaction and defines how a Merchant should verify the Agentic Payment Container.

Verification Steps

The Merchant should perform the following steps to determine whether the object being received has not been manipulated in any way, is not being replayed or relayed and has been signed using a key maintained by a trusted agent. It is at the discretion of the Merchant to determine whether the content of the object is usable even if verification is not successful.

• Minimum fields
  • If any of the fields listed in the table above are missing, the content of the object is inaccurate and should not be used for processing any payment.
• Nonce
  • If a message signature was present for this interaction and the nonce contained in the object does not match the nonce received in the message signature, the content of the object is inaccurate and should not be used for processing any payment. As there may be instances where a payment is required but a message signature is not required , this step may be skipped.
• Locate the public key
  • If the public key for the kid field has not been previously retrieved and cached, refer to the Public Keys Retrieval Service section for details of how to retrieve the public key. If the public key cannot be retrieved or the public key has expired, the content of the object may be inaccurate.
• Validate the signature
  • Create the signature base string. The signature base string is a canonical representation of all fields in the object in the order received except for the signature itself. This ensures that both sender and receiver reconstruct the exact same data for signing and verification, and any alteration in order, spacing, or values will cause validation to fail.
  • Provide the signature base string and public key to the library used to validate the signature.
  • If signature validation fails, the content of the object is inaccurate and should not be used for processing any payment.

If signature validation is successful, this implies that the signature was generated by a trusted agent and that the Agent is making a payment, is interacting with the Merchant to retrieve information about a specific product/service or attempting to make a payment to the Merchant for product(s)/service(s).

The describes the potential usage of each of the possible payment objects present in the Agentic Payment Container specifically for Cards. This may vary depending on the underlying payment source.

Card Metadata (cardMetadata)

The card metadata object contains the following fields and may be present if the payment is being processed through a guest checkout, key entry form.

• lastFour – last 4 digits printed on the physical card link to the payment credential
• paymentAccountReference – reference to the underlying funding account of the payment credential
• shortDescription
• a list of CardData objects
  • contentType
  • Content object
    • mimeType
    • width
    • height

This data can be used by a Merchant when providing receipt or order updates to the consumer and to link payments made with tokens or virtual cards to a single underlying funding account.

Payment Credential Hash (credentialHash)

The payment credential hash contains a hash of the following fields and is present when the payment is being processed using a guest checkout, key entry form:

• 16-digit account number
• 2-digit expiration month
• 2-digit expiration year
• 3-digit card security code

This data can be used by the Merchant to ensure that the data being key entered is the actual data provided by the respective Payment Scheme. The Merchant achieves this by using the same above key entered information to generate a hash and compares the hashes. If the hashes do not match, the information being key entered is most likely fraudulent and the Merchant should decline the transaction.

Payment Object (payload)

The payload is encrypted using the Merchant's public key and containing the following fields, and is present when the Merchant is using an API or similar protocol to process the payment:

• A Token object
  • paymentToken
  • expirationMonth
  • expirationYear
  • cardholderName
• dynamicData
• A ShippingAddress object
• A BillingAddress object
• consumerEmailAddress
• consumerName
• consumerMobileNumber

This data is only present when using an API or similar protocol and the respective Payment Scheme is aware of the exact method the Merchant will use to process the payment.

The Merchant public key is onboarded to all the Payment Schemes that the Merchant accepts using a Payment Scheme specific API.

Browsing IOU (browsingIOU)

The Browsing IOU object contains the following fields and is present if the Merchant has requested payment using a 402 response code:

• invoiceId (received in the 402 response code)
• amount (amount received in the 402 response code)
• cardAcceptorId (CAID received in the 402 response code)
• acquirerId (AID of the acquirer with whom the funds will be settled)
• uri (the URI of the page requiring payment)
• sequenceCounter (agent tracking number)
• paymentService (the payment service with which the Agent has an account)
• kid
• alg
• signature

Prior to granting access to the resource, the Merchant must verify that the data in the IOU matches the data returned in the 402 response and verify the signature. If the data and the signature is valid, the Merchant can grant access with the expectation that the funds will be available when settlement occurs.

This section provides details on public key retrieval, ID Tokens and sample code to build the message signature base string.

Public Keys Retrieval Service

The Public Keys Retrieval service enables retrieval of cryptographic public keys from a well-known URL. For Visa's implementation, Visa will host a well-known URL. The goal would be to have a shared approach across Payment Schemes. The keys retrieved are used by Merchants for Message Signature, JWS signature and Agentic Consumer Recognition Object verification.

In the case of a Visa hosted well-known URL, cryptographic public keys will be available for retrieval to allow signature verification in the following cases:

• The ID Token provided by Visa as an object in the Agentic Consumer Recognition Object is a signed JWT in the form of a JWS
• Agentic Consumer Recognition Object, Browser IOU Object and Payment Credentials are signed in the form identified by the alg field.
• The message signature is signed in the form identified by the alg field.

For non-Visa keys, refer to the documentation for the specific JWS to determine the mechanism to retrieve public keys.

Visa publishes public keys on the web in the following well-known location (https://mcp.visa.com/.well-known/jwks) to allow discovery of the keys by the relying party. Each key must be easily identifiable so it can be selected by the relying party based on the kid or keyid specified in the header of the JWS or Signature-Input respectively.

For signature verification, key retrieval and selection process follows the steps below:

1. The relying party discovers the URI of the signature issuer by examining the JWS content (i.e. iss) or in the case of the message signature as specified in this material.
2. The relying party retrieves the set of public keys available at the well-known path as per the discovered or known URI.
3. The relying party examines JWS header or Signature-Input to discover the key ID (kid or keyid member) and cryptographic signature algorithm (alg member).
4. The relying party selects the corresponding public key that matched the key ID and performs verification of the signature following the known or indicated algorithm

The Public Key Retrieval operation retrieves a set of public keys.

Public Key Retrieval Definition

If the operation is processed successfully (status code of 2xx), the response body will return a JWK Object (JSON Web Key) with the following fields:

Refer to the common set of HTTP error status codes to determine the cause of any unsuccessful key retrieval.

The ID Token is a JSON Web Token (JWT) in line with RFC 7519 and compatible with an OpenID Connect ID Token.

The Visa implementation of the ID Token is digitally signed by Visa. Relying parties (Merchants) need to be able to validate this token using Visa's public key. The signature is compliant with JSON Web Signature (JWS) specification RFC 7515.

The header of the JWT must be compliant with the JOSE Header as specified by RFC 7519. The following table describes required fields in the JOSE Header, in accordance with RFC.

The ID Token represents a digitally-signed attestation that a Consumer has been identified by the respective Payment Scheme. The token contains Consumer Identities that allow Merchants to identify whether they have an existing account for the Consumer.

As no identities are provided in the clear, the Merchant must also maintain a mapping table that can be used to match an obfuscated phone number or obfuscated email address to an actual phone number or email address of their account holder.

Public Claims

Standard ID Token Claims

Private Claims

This is a Python example of how to create the signature base string. It can be done in any language preferred by the developer.