# Future Directions Source: https://www.agentcommercekit.com/ack-id/future-directions Potential future developments for ACK-ID and the agent identity ecosystem. ACK-ID provides a standards-based framework for managing agent identities, with a particular focus on enabling secure and compliant commerce. By leveraging DIDs and VCs, it establishes verifiable links between agents and their owners, facilitating trust in automated interactions. Establishing verifiable ownership is a crucial first step, but a complete understanding of an agent's trustworthiness involves more dynamic factors. Future development within the broader ecosystem will likely focus on standardizing aspects like **agent reputation, reliability metrics** (e.g., success/error rates), and **ethical compliance attestations**. This will allow interacting parties to not only verify who owns an agent, but also to assess an agent's performance and trustworthiness over time. ACK-ID provides a foundation upon which these richer, dynamic reputation systems can be built, enabling more nuanced trust decisions in the agent economy. # Identity Model Source: https://www.agentcommercekit.com/ack-id/identity-model Linking Agents to Owners and distinguishing Agent vs. Service Consumer Identity. ## Agent Ownership ACK-ID employs a clear model to define the relationship between the accountable **Owner** (a person or organization) and the **Agent** acting on their behalf: * **Owner Identity:** Represents the human or legal entity (e.g., a company) ultimately responsible for the agent's actions. This identity is typically long-lived and tied to real-world verification processes (like KYC/KYB). * **Agent Identity:** Represents the AI agent itself. This identity derives its authority from the Owner Identity and is used by the agent to authenticate itself during interactions. Agent Identities can be permanent or temporary (e.g., for specific tasks), but are always linked back to a verified Owner Identity. Identity model clarifying the relationship between Owner and Agent This hierarchical link is crucial for accountability and compliance in commercial interactions. It ensures that even autonomous agents operate under a clear chain of responsibility. ACK-ID employs identity standards like Decentralized Identifiers and Verifiable Credentials to implement the relationship between these identities. These standards are explored in the section [Identity Standards](/ack-id/standards). ## Agent Identity vs. Service Consumer Identity It is important to distinguish this **Agent Identity** (representing the AI agent and its owner/authority) from the identity of the **Service Consumer** (often called the end-user). The Service Consumer is the specific entity interacting with or benefiting from the agent's services at a particular time. This Consumer could be a human, another autonomous agent, a device, or a software application. A single agent may serve many different Service Consumers concurrently. Authenticating the Service Consumer involves separate, parallel mechanisms appropriate for the consumer type (e.g., OAuth/SAML for humans, API keys for applications, potentially other agent identity credentials for delegated agents). ACK-ID focuses specifically on verifying the agent entity providing the service, complementing rather than replacing Service Consumer authentication processes. # Implementation Challenges Source: https://www.agentcommercekit.com/ack-id/implementation-challenges Common challenges and mitigation strategies when implementing ACK-ID. Organizations implementing ACK-ID may encounter several common challenges when working with decentralized identity concepts like DIDs and VCs. Planning for these can help ensure a smoother deployment. ### Key Management Secure management of the cryptographic private keys associated with DIDs is critical but often complex, especially at scale. Compromised keys can lead to identity theft and unauthorized actions. **Mitigation:** Use established enterprise key management systems (KMS), consider hardware security modules (HSMs) for high-value Owner or critical Agent keys, implement robust key rotation policies, and enforce strict access controls based on the principle of least privilege. Ensure keys are appropriately isolated from less secure application components. ### Trust Anchor Establishment Determining which credential issuers (trust anchors) to trust for specific claims requires careful policy definition and ongoing governance. How do you decide which regulatory body's VC to accept, or which internal system is authoritative for specific agent capabilities? **Mitigation:** Start with a limited set of well-established trust anchors (e.g., known government issuers, specific internal authorities). Establish clear governance processes for evaluating and onboarding new trusted issuers. Consider implementing tiered trust levels based on the verification depth or the criticality of the claim being asserted. ### Revocation Efficiency Checking credential revocation status (ensuring a presented credential hasn't been invalidated since issuance) efficiently and in real-time can be demanding, potentially creating performance bottlenecks if not designed carefully. **Mitigation:** Utilize efficient, standardized revocation methods like W3C Status List 2021, which minimize the need for direct issuer lookups during verification. Implement appropriate caching strategies for revocation information with suitable time-to-live (TTL) settings. Consider using short-lived credentials for highly sensitive operations where near real-time revocation checking is paramount. ### Privacy vs. Compliance Tension Balancing the privacy benefits of selective disclosure (inherent in VCs) with regulatory requirements (which may demand more comprehensive identity data for KYC/AML) can be challenging. **Mitigation:** Carefully design VC schemas to separate different types of claims, allowing presentation of only what's necessary. Leverage the selective disclosure capabilities of VCs during presentation. Implement clear data retention and access control policies aligned with relevant privacy and financial regulations (e.g., GDPR, CCPA). ### Integration with Legacy Systems Connecting ACK-ID concepts (DIDs, VCs) with existing enterprise identity and access management (IAM) systems, user directories, or HR systems often requires careful planning and integration effort. **Mitigation:** Explore using identity federation adapters or protocols (like SAML or OpenID Connect bridges) where appropriate. Plan for progressive migration strategies rather than a wholesale replacement. Maintain compatibility layers or custom integration points during transition periods to ensure smooth interoperability between new ACK-ID based systems and legacy infrastructure. # Introduction to ACK-ID Source: https://www.agentcommercekit.com/ack-id/introduction Verifiable Identity for Agent Interactions ACK-ID Illustration In the emerging agent economy, establishing who an AI agent is — and what person or business is responsible for it — is critical for trust, security, and compliant commerce. Agent Commerce Kit's Identity protocol (ACK-ID) defines a way to securely and verifiably establish the identities of agents and link them to their human or organizational owners. ACK-ID addresses key challenges in agent identity: * **Verifiable Ownership:** Creating clear, auditable links between legal entities and the autonomous agents acting on their behalf. * **Secure Authentication:** Enabling agents to securely prove their identity to other parties in automated interactions. * **Privacy Preservation:** Allowing agents to share necessary identity attributes for compliance or authorization while preserving privacy. Essentially, ACK-ID helps answer two fundamental questions for participants in agentic workflows: As a service provider (or another agent), how can I trust that the AI interacting with me is legitimate, authorized, and represents who it claims to represent? As an agent owner or operator, how can my AI agent prove its identity and its authority to act on my behalf in a secure, standard way? ACK-ID addresses these questions by applying open standards for digital identity in a pattern specifically designed for agentic systems. ACK-ID uses and builds upon decentralized identity protocols because they enable entities to control their own digital identifiers rather than rely on central authorities, and that level of identity management is a necessity for AI agent workflows. Trust in AI is not a one-and-done decision. Trust may change over time based on an agent's behavior, its owner's changes in status, reputational factors, and more. # Lifecycle Management Source: https://www.agentcommercekit.com/ack-id/lifecycle-management Managing the lifecycle of agent identities and credentials in ACK-ID. Identities and credentials aren't static. An agent's permissions might change, an owner might transfer responsibility, or keys might be compromised. ACK-ID recognizes the need to manage the full lifecycle of DIDs and VCs to ensure the system remains secure and reflects current reality. Key lifecycle stages include: * **Issuance (Genesis):** The secure creation and distribution of DIDs for Owners and Agents, and the issuance of Verifiable Credentials (VCs) that link them or grant specific authorizations. This involves cryptographic key generation and adherence to defined issuance policies. * **Verification:** The process of validating identities and credentials during interactions, as detailed in the [Example Use Case](/ack-id/use-case-verification). This happens frequently throughout an agent's active life. * **Revocation (Sunset):** Securely invalidating credentials or DIDs when an agent is decommissioned, its permissions change, or a key is compromised. Implementing efficient and privacy-preserving status checking mechanisms (e.g., using standardized Status Lists like W3C Status List 2021) is crucial for timely revocation. * **Updates/Transfers:** Handling changes in ownership or delegated authority. This typically involves revoking old credentials and issuing new ones reflecting the updated relationships or permissions. DID documents may also need updating (e.g., changing the controller). Lifecycle Management Diagram Robust lifecycle management processes ensure that trust decisions are based on current, valid information and that the identity system remains secure throughout the operational lifespan of agents and their associated credentials. # Security and Privacy Source: https://www.agentcommercekit.com/ack-id/security-privacy Key security and privacy considerations for implementing ACK-ID. Implementing a robust identity system like ACK-ID requires careful attention to security and privacy best practices. ## Key Management Securely generating, storing, using, and rotating the cryptographic private keys associated with Owner and Agent DIDs is paramount. Compromised keys can lead to identity theft and unauthorized actions. Refer to the [Implementation Challenges](/ack-id/implementation-challenges#key-management-complexity) section for mitigation strategies like using KMS or HSMs. ## Selective Disclosure A major privacy benefit of Verifiable Credentials (VCs) is the ability for agents to reveal only the specific information necessary for a given interaction, without exposing their entire identity profile or all associated credentials. For example, an agent can present a VC proving it is authorized to make a payment up to a certain limit, without revealing other unrelated credentials it might hold. This minimizes unnecessary data exposure. ## Data Minimization Implementations should follow the principle of data minimization. Only essential identity attributes required for the specific use case should be included in VCs or requested during verification. Avoid collecting or storing unnecessary identity information. ## Standard Security Practices Beyond key management, standard security practices are essential: * **Prevent Forgery:** Rely on cryptographic signature verification for all VCs to ensure an agent truly controls the DID it claims * **Prevent Replay Attacks:** Use mechanisms like nonces or timestamps within protocols where appropriate to ensure credentials or authentication messages are not reused maliciously. * **Secure Communication:** Use encrypted communication channels (e.g., TLS/HTTPS) for all interactions involving DIDs or VCs. # Identity Standards Source: https://www.agentcommercekit.com/ack-id/standards Understanding Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs) used in ACK-ID. To implement and verify agent identity securely and interoperably, ACK-ID leverages two key W3C open standards: Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs), explained below. ## Decentralized Identifiers (DIDs) Think of DIDs as globally unique, permanent digital IDs that agents (and their owners) can create and control without needing permission from a central registration authority like ICANN for domain names or like a government for national IDs. Unlike traditional usernames or identifiers issued by a single company, DIDs are independent and cryptographically secured. An agent uses its DID to identify itself. Associated with each DID are cryptographic keys (public keys listed in a "DID Document," and private keys held securely by the controller) that allow the agent to prove control over that DID – for example, by digitally signing messages or responding to authentication challenges. ACK-ID uses DIDs to represent both Owner and Agent identities, forming the anchor for the identity model. In addition to public key information, DID Documents may optionally contain service endpoints. These endpoints can specify network locations (like URLs) where other parties can interact with the agent or related services. The official W3C Decentralized Identifier Specification is available here: [https://www.w3.org/TR/did-core/](https://www.w3.org/TR/did-core/) ## Verifiable Credentials (VCs) While DIDs provide unique identifiers, Verifiable Credentials (VCs) provide a standard way to make verifiable statements *about* those identifiers. Think of VCs as digital, tamper-proof versions of physical credentials like a driver's license, a diploma, or a membership card, but designed for the digital realm. VCs contain statements or "claims" made by a trusted **Issuer** about a **Subject** (e.g., an agent identified by its DID). These claims are digitally signed by the Issuer using their own DID and cryptographic keys. This signature allows anyone (as a **Verifier**) who trusts the Issuer to verify the authenticity and integrity of the claims about the Subject. In ACK-ID, VCs are crucial for conveying authorization and status. Practical examples include: * A licensed financial institution (Issuer) issues a VC stating that a specific Agent DID (Subject) is authorized to operate under its financial services license (Claim). This enables verifiers to trust that the agent's actions comply with financial regulations. * An enterprise (Issuer) issues a VC to an employee's Agent DID (Subject), authorizing it to access corporate resources or execute transactions (Claim). This ensures agents act within defined corporate policies. * A regulatory body (Issuer) issues a VC confirming that an Agent DID (Subject) complies with security, privacy, or ethical AI guidelines established by relevant industry standards (Claim). This reassures verifiers that the agent meets necessary operational standards. "title" The official W3C Verifiable Credentials data model specification is available here: [https://www.w3.org/TR/vc-data-model/](https://www.w3.org/TR/vc-data-model/) By using DIDs and VCs together, ACK-ID provides a standard, cryptographically secure, and privacy-preserving way to manage agent identities and permissions. This approach aligns with broader efforts in the decentralized identity community aimed at creating trustworthy digital interactions, including conceptual frameworks like the LOKA protocol which also leverage these foundational standards for agent identity and governance. # Trust Framework Source: https://www.agentcommercekit.com/ack-id/trust-framework Establishing trust in ACK-ID through Verifiable Credentials and issuer policies. Trust within ACK-ID is established by verifying the digital signatures on Verifiable Credentials (VCs) and determining whether the **Issuer** of a specific credential is authoritative for the claims being made. Implementations must define policies specifying which issuers they trust for different types of information. Examples include trusting a government authority for legal entity verification, a financial institution for account linkage, or an internal system for agent capability attestation. This concept of trusted issuers acts as the **root of trust** for verifying claims. Crucially, this verification relies on cryptography and publicly available information (like the issuer's DID document containing their public keys), allowing a **Verifier** to validate a credential **without needing to contact the original Issuer directly**. This enhances privacy compared to centralized systems where callbacks might reveal when and where credentials are used. Furthermore, mechanisms are needed to enable trust across different organizational boundaries. This might involve shared trust lists maintained by consortia, standardized federation protocols, or other methods allowing agents from different ecosystems to validate each other's credentials based on mutual agreements or shared policies. This policy-driven approach allows for flexible yet secure trust relationships tailored to specific use cases and risk appetites. # Example Use Case Source: https://www.agentcommercekit.com/ack-id/use-case-verification An example scenario illustrating how ACK-ID verifies an agent's identity and ownership. This use case illustrates how ACK-ID enables one agent to securely verify the identity and legitimate ownership of another agent, specifically ensuring it is operated by a recognized, regulated financial institution, before engaging in potentially sensitive interactions. This example focuses solely on the identity verification aspect, independent of any subsequent payment flows. ## Scenario: Verifying a Financial Agent A corporate treasury management agent ("CorpTreasury Agent"), operated by Acme Corp, needs to obtain real-time foreign exchange (FX) quotes. Acme Corp's policy mandates that its treasury agent interact only with FX services provided by known, regulated financial institutions to ensure compliance and reduce counterparty risk. The CorpTreasury Agent discovers (or is pre-configured to communicate with) an FX service agent claiming to be operated by "BankTrust," a known regulated bank. ## Identity Setup * **BankTrust (Owner):** * Establishes its Owner DID, linked to its verified legal identity and domain (e.g., `did:web:banktrust.com`). * **BankTrust FX Agent (Server Agent):** * BankTrust creates an Agent DID for its FX service (e.g., `did:web:fx.banktrust.com`). * BankTrust, as the Owner, issues an "Ownership & Authorization" VC asserting that `did:web:fx.banktrust.com` is operated by `did:web:banktrust.com` and is authorized to provide FX quoting services. * **CorpTreasury Agent (Client Agent):** * Operates under its own Agent DID, linked back to Acme Corp's verified Owner DID. * Maintains a configurable "Trust List" of DIDs corresponding to approved regulated financial institution Owners. `did:web:banktrust.com` is on this list. * Is configured with Acme Corp's policy regarding verification requirements (e.g., trusting the `did:web` domain and Trust List status for known entities). ## Interaction & Verification Flow 1. **Request:** CorpTreasury Agent sends a request for an FX quote to the agent endpoint associated with `did:web:fx.banktrust.com`. 2. **Identity and VC Exchange:** As part of establishing a secure interaction, the BankTrust FX Agent presents its Agent DID (`did:web:fx.banktrust.com`) and relevant VCs (including the Ownership & Authorization VC). 3. **CorpTreasury Agent Verification Steps:** * **VC Signature Validation:** Verifies the cryptographic signatures on the presented VCs. If any signature is invalid, the interaction is **rejected**. * **Ownership Verification:** Checks the "Ownership & Authorization" VC. It confirms the VC was issued by the claimed Owner DID (`did:web:banktrust.com`) and asserts control over the Agent DID (`did:web:fx.banktrust.com`). * **Owner Identity Resolution:** Resolves the Owner DID (`did:web:banktrust.com`). This confirms it's associated with the expected `banktrust.com` domain via the `did:web` method (relying on HTTPS security). If the DID cannot be resolved or links to an unexpected domain, the interaction is **rejected**. Note that other non-web DID methods would require different mechanics for resolving identity. * **Policy Check:** Based on Acme Corp's policy, since the Owner DID resolved correctly to the trusted domain and is on the Trust List, no further "Regulated Status" VC check is required for this interaction. 4. **Interaction Proceeds:** If all required verification steps pass successfully according to policy, the CorpTreasury Agent trusts that it is interacting with the legitimate FX agent operated by the regulated BankTrust. It proceeds with the FX quote request. ```mermaid theme={null} %%{ init: { 'theme': 'mc', 'sequenceMessageAlign': 'center' } }%% sequenceDiagram; participant Client as CorpTreasury Agent; participant Server as BankTrust FX Agent; Client->>Server: 1: Request FX Quote; Server->>Client: 2: Present Agent DID & Ownership VC; Note over Client: Start Verification Steps; Client->>Client: 3: Verify VC Signature; alt Signature Invalid Client-->>Server: Reject Interaction (Invalid Signature); else Signature Valid Client->>Client: 4: Verify Ownership Claim in VC; alt Ownership Claim Invalid Client-->>Server: Reject Interaction (Ownership Claim Invalid); else Ownership Claim Valid Client->>Client: 5: Resolve Owner DID (e.g., did:web:banktrust.com); alt Owner DID Resolution Fails Client-->>Server: Reject Interaction (Owner DID Resolution Failed); else Owner DID Resolved Client->>Client: 6: Check Owner DID against Trust List & Policy; alt Policy Check Fails (Not Trusted/Not Regulated per Policy) Client-->>Server: Reject Interaction (Policy Violation); else Policy Check Passed Note over Client: All Verification Steps Passed; Client->>Server: 7: Proceed with FX Quote Request; end end end end ``` ## Failure Scenario Example Imagine a rogue agent attempting to impersonate BankTrust's FX service. It might present an Agent DID such as `did:web:fx.banktrust.com.rogue.net`. When the CorpTreasury Agent resolves this DID and verifies the presented VCs, it would find: * The VCs are likely not signed by the legitimate `did:web:banktrust.com` Owner DID (signature verification fails). * Or, if the rogue entity created its own valid VCs, the Owner DID resolved (`did:web:banktrust.com.rogue.net`) would not be on CorpTreasury's Trust List. In either case, the verification fails, and the CorpTreasury Agent **rejects** the interaction, preventing engagement with the untrusted agent. ## Reputation and Performance Scenarios While this example focuses on verifying ownership and regulatory status, future enhancements to the ecosystem could involve additional VC-based checks. For example, before interacting, the CorpTreasury Agent might also request VCs attesting to the BankTrust FX Agent's **reputation** or **performance metrics** (e.g., average quote accuracy, transaction success rate, uptime), issued by trusted monitoring services. This would allow the CorpTreasury Agent not only to verify legitimacy but also to assess quality of service and potentially select the best agent among several verified options. ACK-ID provides the foundational layer for such future developments. # Client-Initiated Sequence Source: https://www.agentcommercekit.com/ack-pay/client-initiated-sequence Details of the ACK-Pay flow initiated by a Client Agent based on a known obligation. This sequence is employed when a Client agent needs to pay based on a known obligation (e.g., an invoice, e-commerce checkout, user instruction) without first receiving a [Payment Request](/ack-pay/payment-request-payload) from the Server/recipient. ## Sequence Steps 1. **Identify Obligation & Construct Payment Request:** The Client agent determines the need to pay a specific `recipient` a target `amount` and `currency`. It gathers necessary details from the source of the obligation (e.g., parsing an invoice, extracting data from a web checkout page, or receiving human end-user instructions). The Client then constructs the Payment Request, potentially with assistance from a known Payment Service to format the details correctly or determine recipient identifiers. 2. **Identify Payment Service:** The Client identifies a suitable Payment Service to execute the constructed Payment Request. This Payment Service may be pre-configured or dynamically discovered based on criteria like supported pay-in/pay-out methods specified or implied in the obligation, fees, speed, reputation, compliance capabilities. 3. **Initiate Transaction & Optionally Negotiate Additional Detail:** The Client interacts directly with the chosen Payment Service's endpoint for payment initiation. The specific API is defined by the Payment Service, but the request must convey: * The ultimate `recipient` identifier and the target `amount`/`currency`. * Details of the payment method the Client will use for funding. * Necessary reference information (e.g., invoice number, order ID). * Authentication credentials for the client agent (potentially leveraging ACK-ID). 4. **Approvals and HITL:** The Client and Payment Service may optionally exchange further details or Human-in-the-Loop approvals as needed (e.g., specific pay-in instructions, risk checks, or other dynamic interactions). 5. **Payment Execution:** The Client authorizes the Payment Service to execute the payment according to the selected option. The Payment Service handles the interaction with the underlying Settlement Network, including any necessary conversions or compliance checks. 6. **Receipt Issuance:** Upon successful settlement, the Payment Service (or its designated Receipt Service) issues an ACK Receipt (a Verified Credential) back to the initiating Client Agent. Optionally, the original requesting source or the final recipient may also be notified via the optional `serviceCallback` parameter if provided during initiation. ## Sequence Diagram ```mermaid theme={null} %%{ init: { 'theme': 'mc', 'sequenceMessageAlign': 'center' } }%% sequenceDiagram; participant CA as Client Agent; participant PS as Payment Service; participant RS as Receipt Service; participant SN as Settlement Network; participant SA as Server Agent; Note right of CA: Identify Obligation
(e.g., from invoice, chat instruction, web page scrape); CA<<->>CA: 1: Compose Payment Request; CA-->>PS: 2: Initiate Payment, Provide Identity Proof, Request Server Proof of Agency; rect rgba(0, 0, 255, .03) Note right of PS: Verify Client Identity; PS-->>CA: Present Identity Proof; Note right of CA: Verify Payment Service Identity; CA<<-->>PS: Payment Request Composition (if needed); end CA->>PS: 3: Initiate Payment; PS<<-->>CA: Potential human-in-the-loop approvals; PS->>SN: 4: Execute/Settle Payment; PS->>RS: 5: Request Receipt for Confirmed Payment; RS-->>PS: Issue Receipt (VC); PS-->>SA: Deliver Receipt via Optional Callback; PS->>CA: 6: Deliver Receipt; ``` *To enlarge this mermaid markdown diagram, zoom in on your browser (CMD +)* ## Examples ### Example: Automated B2B Invoice Payment Consider a manufacturing company's procurement agent that receives confirmation of successful goods delivery linked to Invoice #INV-9876 from Supplier Y (\$10,000 USD): 1. The agent identifies the obligation from the invoice data. It constructs the payment details (pay \$10,000 USD to Supplier Y, reference #INV-9876). It may optionally interact with a Payment Service API to help format these details or resolve recipient bank information if needed. 2. It uses a pre-configured Payment Service agreed upon during supplier onboarding (accepts ACH from manufacturer, settles via wire to supplier). 3. The agent calls the Payment Service API, providing the constructed payment details and its own authenticated credentials. 4. The Payment Service validates, performs compliance checks, initiates ACH debit, executes the wire transfer, and confirms settlement. 5. The Payment Service issues an ACK receipt to the manufacturer's agent, providing verifiable proof of payment linked to Invoice #INV-9876. ### Example: AI Shopping Agent Checkout Consider an AI shopping agent, funded via a user's EUR bank account (converted to EURC custodied by the agent), tasked with purchasing an item from a standard e-commerce website that accepts USD credit cards: 1. Navigate & Add to Cart: The agent navigates the website, adds the desired item to the shopping cart, and proceeds to the merchant’s checkout. 2. Parse Final Order Summary & Construct Request: On the final checkout page, the website displays the total order cost (\$50 USD) and Order ID (ORD-12345). The agent parses this to determine the `targetAmount`, `targetCurrency`, `recipientIdentifier` (merchant), and `referenceId`. It uses this information to construct an internal representation of the payment obligation, analogous to the Payment Request. 3. Identify Payment Service: The agent uses its pre-configured Payment Service that specializes in EURC-to-USD virtual card generation. 4. Initiate Payment: The agent calls the Payment Service API, providing the constructed payment details (settle \$50 USD to merchant for ORD-12345) and specifying EURC as its funding source. 5. Execute & Settle: The Payment Service debits the EURC, generates a single-use USD virtual card, programmatically inputs the card details into the merchant's checkout, and receives confirmation. 6. Issue Receipt: The Payment Service issues an ACK receipt to the shopping agent, confirming \$50 USD was paid for Order ID "ORD-12345". 7. Finalize Order (If Needed): The agent uses the confirmation/receipt to perform any final steps on the merchant site. This client-initiated sequence demonstrates the flexibility of the ACK ecosystem, allowing sophisticated payment orchestration while leveraging the core components (Payment Service, Receipt Service) and the verifiable receipt for trust and auditability. # Components and Roles Source: https://www.agentcommercekit.com/ack-pay/components-roles Key components and their roles within the ACK-Pay payment protocol. ## Role Definitions The ACK-Pay protocol defines several key components that interact to facilitate payments: * **Client Applications and Client Agents:** Software initiating service requests or payments on behalf of end-users or autonomous processes. In the Client-Initiated sequence, they are responsible for constructing the Payment Request. * **Servers, Server Agents and Service Providers:** Entities providing resources or services that may require payment and need to verify payment receipts before granting access or fulfilling requests. In the Server-Initiated sequence, they are responsible for generating and sending the Payment Request. * **Payment Service:** A crucial intermediary responsible for managing payment execution. Its functions can include: * Routing payments across different networks. * Assisting Clients in constructing Payment Requests (in Client-Initiated sequences). * Handling currency/asset conversions. * Interacting with underlying Settlement Networks. * Performing risk assessments and compliance verification (potentially using ACK-ID). * Managing human approval workflows. * Coordinating with Receipt Services. * Abstracting diverse payment methods, including traditional rails (ACH, card networks via APIs like Visa Intelligent Commerce or Mastercard Agent Pay), and blockchain networks. * Optionally acting as a bridge to other protocols by exposing compatible interfaces (e.g., functioning as an x402 Facilitator for servers using that approach). * **Receipt Service:** Generates and validates cryptographically verifiable receipts (typically as Verifiable Credentials), ensuring: * Secure credential issuance based on confirmed payment settlement. * Management of receipt status (e.g., validity, revocation). * Validation of presented receipts. *(Note: The Payment Service and Receipt Service roles may sometimes be fulfilled by the same entity).* * **Settlement Networks:** The underlying financial infrastructures that execute value transfer (e.g., traditional banking systems, card networks, blockchain networks). These roles define the actors within the ACK-Pay ecosystem that orchestrate payment flows. The next section will explore how these actors collaborate with one another. ## Component Interactions with a Payment Service The following component activity diagram illustrates a sophisticated flow involving a Payment Service. "Components and Roles Diagram" ## Component Interactions with Client-Executed Payments The following component activity diagram illustrates a simple flow in which a Client Agent executes a payment directly via an embedded Payment Service. "Components and Roles Diagram" # Core Payment Sequences Source: https://www.agentcommercekit.com/ack-pay/core-payment-sequences The two primary interaction patterns for initiating payments in ACK-Pay. ACK-Pay supports two primary interaction patterns for initiating payments, both centered around a standard [Payment Request](/ack-pay/payment-request-payload) payload: 1. **Server-Initiated Sequence:** A Server (or Service Provider) requires payment from a Client agent before granting access to a resource or completing an action. In this flow, the **Server generates and sends** the Payment Request to the Client, typically in response to an initial resource request. This is common for pay-per-use APIs or accessing paid content. [Learn more about the Server-Initiated Sequence →](/ack-pay/server-initiated-sequence) 2. **Client-Initiated Sequence:** A Client agent initiates a payment based on an external trigger or known obligation (e.g., paying an invoice, completing an e-commerce checkout, fulfilling a human end-user’s instructions). In this flow, the **Client agent constructs** the Payment Request itself, often by parsing external information (like an invoice or checkout summary) and potentially using a Payment Service to help formulate the request details before interacting with the Payment Service API for execution. [Learn more about the Client-Initiated Sequence →](/ack-pay/client-initiated-sequence) Both sequences leverage the same core [Components and Roles](/ack-pay/components-roles) (Client, Server, Payment Service, Receipt Service, Settlement Networks) and the [ACK Receipt](/ack-pay/receipt-verification) for verification. # Human Oversight Integration Source: https://www.agentcommercekit.com/ack-pay/hitl Integrating human oversight and approval into ACK-Pay payment flows. While ACK-Pay aims to facilitate automated agent commerce, it acknowledges the critical need for human judgment and control, particularly in situations involving significant financial value, risk, or compliance implications. Workflows allow for strategic human intervention points, typically managed and configured within the Payment Service or Client application policies. ## Human Oversight Scenarios Examples where human oversight may be triggered include: * **Approval Workflows:** Routing transactions for manual approval if they exceed predefined value thresholds or involve counterparties risk-flagged for review. * **Exception Handling:** Escalating payments flagged by automated risk assessment systems (e.g., potential fraud or compliance issues) for human investigation. * **Audit Reviews:** Flagging completed transactions (e.g., randomly selected, high-value, or unusual patterns) for periodic human audit to ensure policy adherence and compliance. * **Policy Management:** Humans define and manage the policies that dictate transaction rules, risk thresholds, and approval requirements within the system. ## Integration Points Human oversight may be integrated at three key points in the payment lifecycle: * **Pre-execution Approval:** Requiring explicit human sign-off *before* a payment is initiated or executed by the Payment Service. This is common for high-value transactions or payments initiated by agents with limited spending authority. * **Post-execution Review:** Flagging completed transactions for later human review and auditing, without holding up the real-time execution. * **Exception Resolution:** Escalating failed, disputed, or problematic transactions for human intervention and resolution. ## Human Approval Example Flow "Example Human Intervention" Integrating these Human-in-the-Loop mechanisms allows organizations to balance the efficiency of automation with the accountability and guardrails provided by human oversight. # Introduction to ACK-Pay Source: https://www.agentcommercekit.com/ack-pay/introduction Agent-Native Payments Protocol for the Agent Economy ACK-Pay Illustration The ACK Payment Protocol (ACK-Pay) identifies a common pattern designed to facilitate secure, verifiable, and interoperable financial transactions among autonomous agents, services, and human participants. Although some specific ACK-Pay services and implementations use only HTTP, the pattern supports a wide range of other communication mechanisms. It defines standard payloads and interactions that extend beyond HTTP, enabling payments across various communication protocols while incorporating rigorous compliance capabilities, human oversight integration, and adaptable settlement methods. The need for new financial infrastructure tailored to AI agents is underscored by recent initiatives from major payment networks, such as Visa Intelligent Commerce and Mastercard Agent Pay, which aim to enable secure, tokenized payments initiated by verified agents within their ecosystems. ACK-Pay provides an open, interoperable standard that encompasses and works alongside these network-specific solutions, and alongside stablecoin-oriented blockchain solutions such as Coinbase’s [x402](http://x402.org) and other similar 402-oriented implementations, such as l402, h402, and others that fit the general ACK-Pay pattern. While ACK-Pay can operate independently, its functionality and security are significantly enhanced when integrated with the [ACK-ID identity protocol](/ack-id/introduction), enabling stronger authentication and accountability through verifiable agent identities and clear chains of ownership. ACK-Pay addresses four fundamental elements essential to automated financial interactions: 1. **Payment Initiation:** Clearly communicating payment requirements from Services to Client agents, or enabling Clients to initiate payments based on known obligations. 2. **Execution Flexibility:** Executing payments securely across diverse financial systems via intermediary Payment Services. 3. **Receipt Verification:** Providing cryptographically verifiable receipts (as Verifiable Credentials) for payment confirmation. 4. **Oversight Integration:** Integrating strategic human oversight at critical points in the payment lifecycle. This section details the core payment flows, components, payload formats, and operational considerations for ACK-Pay. # Operational Considerations Source: https://www.agentcommercekit.com/ack-pay/operational-considerations Handling compliance, security, risk, and errors in ACK-Pay. Beyond the core payment flows and components, implementing ACK-Pay involves several important operational considerations. ## Compliance While ACK-Pay provides the structure, specific **Payment Service** implementations are responsible for integrating the compliance features required by regulations and organizational policy. This may include: * **Transaction Monitoring:** Analyzing flows for suspicious patterns (AML). * **Identity Verification:** Integrating with ACK-ID to verify Client Agent and Owner identities against KYC/KYB requirements before processing payments. * **Reporting:** Generating structured data for regulatory reporting obligations. * **Jurisdictional Rules:** Applying different compliance rules based on the geographic location of participants. * **Human Review Triggers:** Support workflows for escalating flagged transactions or compliance exceptions for human review and approval. ## Security Safeguards ACK-Pay relies on several mechanisms to ensure transaction security: * **Cryptographic Validation:** Verifying digital signatures on Payment Request tokens and ACK Receipts ensures data integrity and authenticity. * **Unique Identifiers:** Using the `requestId` helps prevent replay attacks and track specific transactions. * **Secure Communication:** Interactions should occur over encrypted channels (e.g., HTTPS, encrypted realtime messaging protocols, etc.). * **Receipt Uniqueness:** Verifiers should ensure a specific receipt is not used multiple times for the same obligation where inappropriate (e.g., for single-access resources). ## Cryptographic Key Management Secure identity operations and payment authorization depend critically on proper cryptographic key management: * **Secure Key Generation & Storage:** Generate keys with sufficient entropy and store private keys in secure environments (e.g., Hardware Security Modules, cloud provider Key Management Services, secure enclaves). Avoid storing raw private keys in code or configuration files. * **Least Privilege:** Implement the principle of least privilege for accessing and using keys. Grant components only the permissions they absolutely need (e.g., signing permission vs. key management permission). * **Key Rotation:** Establish protocols and automated processes for regularly rotating cryptographic keys to limit the impact of potential compromises. * **Isolation:** Create strong isolation between potentially less secure components (like LLM interfaces) and the components responsible for cryptographic operations (like a Payment Agent that provides a Payment Service). * **Defense-in-Depth:** Apply multiple layers of security controls (network security, access control, encryption at rest and in transit) to protect the entire system. ## Error Handling and Resilience Financial operations demand robust error handling and system resilience: * **Clear Error Taxonomy:** Develop a clear classification of errors to distinguish between temporary failures (retryable) and permanent failures (non-retryable, requiring escalation or alternative flows). * **Partial Failure Design:** Design workflows to handle partial failures gracefully where possible (e.g., if receipt generation fails after successful payment, have a mechanism to retry receipt generation). * **Intelligent Retries:** Implement retry strategies (e.g., exponential backoff with jitter) for transient network or service availability issues. * **Comprehensive Logging:** Implement detailed, structured logging for all critical operations to facilitate troubleshooting and debugging. * **Alerting:** Establish monitoring and alerting thresholds for unusual failure rates or specific critical errors. ## Observability and Monitoring Gain visibility into the health and performance of ACK-enabled systems: * **Detailed Logging:** Use structured logging with transaction correlation IDs that span different components (Client, Payment Service, Receipt Service). * **Performance Metrics:** Track key performance indicators (KPIs) for each protocol operation (e.g., payment execution latency, receipt verification time, error rates). * **Alerting:** Set up alerts for anomalous patterns (e.g., spike in payment failures, unusual transaction volumes) or system degradation. * **Distributed Tracing:** Implement distributed tracing where possible to visualize the end-to-end flow of requests across microservices or distributed components. * **Dashboards:** Create operational dashboards for monitoring system health, transaction throughput, and key business metrics. # Payment Request Source: https://www.agentcommercekit.com/ack-pay/payment-request-payload Structure and details of the ACK-Pay Payment Request. The JSON Payment Request payload is central to ACK-Pay interactions. Its origin and handling differ slightly depending on the payment sequence: * **Server-Initiated Sequence:** When payment is required by a Server, it **generates and sends** this payload structure to the Client to communicate the requirement. This payload is designed to be transport-agnostic: while delivered via the standard 402 status code when HTTP is employed, it can also be delivered over other protocols (e.g., A2A messages, WebSockets) and is not limited to HTTP. * **Client-Initiated Sequence:** When payment is initiated by a Client based on a known obligation, the Client **constructs** this payload. The Client might parse unstructured data (like an invoice, user instruction, or web checkout summary) and potentially interact with a Payment Service API to help formulate the standardized payload structure before initiating the payment execution. In both cases, the structure allows the offering of one or more ways for the Client to fulfill the payment requirement via a designated Payment Service. ## Payload Structure Every Payment Request payload contains essential properties: ```json theme={null} { "paymentRequest": { // Top-level details applying to the overall service request "id": "unique-request-id-123", "expiresAt": "2025-05-20T23:59:59Z", "description": "Premium API access (100 credits)", "serviceCallback": "https://service.example.com/webhook/payment-complete", // Array of acceptable payment methods offered "paymentOptions": [ { // Option 1: USDC on Base network "id": "usdc-base", "currency": "USDC", "network": "eip155:8453", "amount": 10000000, "decimals": 6, "recipient": "eip155:8453:0xRecipientAddressOnBase", "paymentService": "https://payments.example.com/base", "receiptService": "https://receipts.example.com/base" }, { // Option 2: Stripe payment "id": "stripe-usd", "currency": "USD", "network": "stripe", "amount": 1000, "decimals": 2, "recipient": "acct_StripeAccountID", "paymentService": "https://payments.example.com/stripe", "receiptService": "https://receipts.example.com/stripe" }, { // Option 3: USDC on Solana devnet "id": "usdc-solana-devnet", "currency": "USDC", "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "amount": 10000000, "decimals": 6, "recipient": "ExAmPLeSoLaNaAddReSS111111111111111111111111", "receiptService": "https://receipts.example.com/solana" } // ... more options ... ] }, // Signed token covering the paymentRequest structure above "paymentRequestToken": "signed-representation-of-the-entire-object" } ``` ## Key Fields Explained | Field | Type / Status | Description | | :-------------------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paymentRequestToken` | String / Required | A cryptographic token (e.g., JWT) generated by the Server, signing the `paymentRequest` payload to ensure integrity and authenticity. This token is verified by several participants in the protocol. | | `paymentRequest` | Object / Required | The main payment request object containing all payment details. | | ` id` | String / Required | A unique identifier generated for this specific payment request. Used for tracking and preventing replay attacks. | | ` expiresAt` | String / Optional | An ISO 8601 timestamp indicating when this payment request becomes invalid. Clients should not attempt payment after this time. | | ` description` | String / Optional | A human-readable description of the service or reason for the payment, useful for display or logging. | | ` serviceCallback` | String / Optional | A URL or DID URI that the Payment Service or Receipt Service can use to notify the original Server upon successful payment confirmation. Enables asynchronous workflows. | | ` paymentOptions` | Array / Required | An array containing one or more objects, each defining a distinct payment option containing the fields below. | | ` id` | String / Required | A server-defined identifier for this specific payment option. | | ` currency` | String / Required | The currency or token symbol required for this option (e.g., "USD", "USDC"). | | ` network` | String / Optional | An identifier for the required payment network (e.g., "stripe", "eip155:8453"). Helps the Client select a compatible method. | | ` amount` | Integer / Required | The required payment amount expressed as an integer in the smallest unit of the currency (e.g., cents for USD, atomic units for tokens). | | ` decimals` | Integer / Required | The number of decimal places for the specified `currency`, used to interpret the `amount`. | | ` recipient` | String / Required | Identifier for the entity receiving payment for this option (e.g., pay-in address/account ID for the `paymentService`). Format may vary by network. | | ` paymentService` | String / Optional | The URL or DID URI endpoint of the Payment Service designated to handle execution for this specific option. | | ` receiptService` | String / Optional | The URL or DID URI endpoint of the Receipt Service designated to issue/verify receipts for payments made using this option. | ## Payment Service Abstraction The `paymentOptions` listed in a Payment Request define how the designated **Payment Service** accepts funds from the Client. These options do not necessarily dictate the final currency or settlement account required by the Server Agent receiving the service request. The Payment Service acts as a crucial intermediary. It can offer numerous pay-in options (different currencies, networks, or payment methods) suitable for various Clients. Subsequently, the Payment Service handles the necessary bridging, currency conversions (FX), or other transformations required to settle the payment to the Server Agent in their desired currency and account type. This abstraction provides key benefits: * **Server Privacy:** The Server does not need to expose its final settlement account details directly to the Client. * **Client Flexibility:** The Client can pay using a method convenient for it, even if it differs from the Server's preferred settlement method. If fees are associated with bridging, FX conversions, or other transformations performed by the Payment Service, these should be communicated transparently to the Client during the payment negotiation or execution process. # Payment Service Source: https://www.agentcommercekit.com/ack-pay/payment-service The role, capabilities, and integration points for ACK Payment Services. ## The Role of the Payment Service The **Payment Service** is a crucial component within the Agent Commerce Kit (ACK) architecture. It acts as the engine for executing financial transactions according to the ACK-Pay pattern, abstracting the complexities of underlying payment rails and settlement networks away from Client and Server Agents. Whether handling a [Server-Initiated](/ack-pay/server-initiated-sequence) or a [Client-Initiated](/ack-pay/client-initiated-sequence) payment, the Client Agent interacts primarily with a designated Payment Service endpoint to fulfill the payment obligation. Server Agents do not gain access to sensitive payment or counterparty information. ## Core Responsibilities A Payment Service handles several key functions: * **Payment Execution & Settlement:** Interacting directly with various [Settlement Networks](/ack-pay/components-roles#settlement-networks) (e.g., card networks, blockchains, banking systems) to move funds according to the authorized payment details. * **Abstraction Layer:** Hiding the specific requirements and APIs of different payment rails from the Client and Server Agents. The Client interacts with the common ACK pattern, and the Payment Service handles the Settlement layer and other back-end integrations. * **Currency/Asset Conversion & Bridging:** Performing conversions between different fiat currencies, stablecoins, or other digital assets. This includes bridging between different types of rails (e.g., accepting cryptocurrency and settling via virtual card). * **Compliance & Risk Management:** Integrating necessary checks, such as verifying agent identity via [ACK-ID](/ack-id/introduction), performing KYC/KYB/AML checks, assessing transaction risk, and enforcing compliance policies based on jurisdiction or transaction type. * **Human Oversight Integration:** Providing the hooks and managing the workflows for [human approvals](/ack-pay/hitl) based on predefined policies (e.g., transaction value limits). * **Receipt Coordination:** Interacting with a designated [Receipt Service](/ack-pay/components-roles#receipt-service) to request the issuance of a verifiable ACK Receipt upon successful payment settlement. * **Request Assistance:** Optionally providing API endpoints to help agents construct well-formed Payment Request payloads from unstructured data like invoices or user instructions. ## Feature Options Payment Services act as the integration points between AI agents and the diverse landscape of existing payment systems: * **Traditional Rails:** Integrating with ACH, Wire, SEPA, and other bank transfer networks. * **Card Payments:** Utilizing APIs from providers like Stripe or PayPal to process card payments or integrating directly with emerging agent-focused solutions like [Visa Intelligent Commerce](https://corporate.visa.com/en/products/intelligent-commerce.html) or [Mastercard Agent Pay](https://www.mastercard.com/news/press/2025/april/mastercard-unveils-agent-pay-pioneering-agentic-payments-technology-to-power-commerce-in-the-age-of-ai/). * **Blockchain Protocols:** * Handling payments directly on various blockchain networks using stablecoins (USDC, EURC, etc.) or other digital assets. * Bridging to other payment protocols. For example, an ACK Payment Service could expose the necessary endpoints to function as an [x402 Facilitator](https://github.com/coinbase/x402) for Servers using that standard. Integration with protocols like Lightning Network (L402) or Fewsats could also be explored via this layer. * **Nascent Networks:** Future Payment Services, particularly those operated by regulated financial institutions, could integrate with emerging networks like the [Circle Payment Network](https://www.circle.com/cpn) to leverage new settlement capabilities. ## Cross-Currency Capabilities A Payment Service may act as an intermediary responsible for managing currency conversions, potentially using specified exchange rates and transparently handling associated fees. This allows a Client Agent to pay using one currency while the Server Agent or ultimate recipient receives settlement in another preferred currency. These capabilities are particularly valuable for agents operating across jurisdictional boundaries or in multi-currency environments. ### Example: Bridging & Conversion The Payment Service enables powerful bridging scenarios. For instance, a Client Agent holding EURC can interact with a Payment Service that accepts EURC, convert it internally to USD, generate a single-use virtual credit card (VCC), and use that VCC to pay a Server Agent who accepts only USD card payments. The complexity of the conversion and VCC generation is handled entirely by the Payment Service. If fees are involved in bridging or FX conversions, the Payment Service should transparently communicate these to the Client during the payment process. ## Discovery While a Client Agent might be pre-configured to use a specific Payment Service, it's also possible for agents to discover available Payment Services dynamically. Registries or discovery mechanisms could allow Clients to find services based on supported features (e.g., specific pay-in/pay-out rails, currency pairs), transaction fees, settlement speed, reputation, or required compliance certifications, enabling them to choose the optimal service for a given transaction. ## Reference Implementation The [ACK GitHub repository](http://github.com/agentcommercekit/ack) provides reference implementations and code examples, including conceptual implementations of Payment Service interactions used in the [Demos](/demos). These resources can help developers understand the patterns and accelerate integration. # Receipt Verification & Presentation Source: https://www.agentcommercekit.com/ack-pay/receipt-verification Using ACK Receipts (Verifiable Credentials) for payment proof. A core component of ACK-Pay is the verifiable proof of payment. The ACK Receipt system provides cryptographically secure proof using W3C Verifiable Credentials (VCs). This allows Server Agents or other relying parties to validate payments reliably without needing direct access to underlying payment systems or trusting the Client Agent's claim alone. ## ACK Receipt Format (Verifiable Credential) ACK Receipts are structured as Verifiable Credentials. This provides several benefits: * **Standardization:** Leverages the mature W3C VC data model. * **Cryptographic Security:** Receipts are digitally signed by a trusted Receipt Service, ensuring authenticity and integrity. * **Interoperability:** Can be processed and verified by any system understanding the VC data model. * **Selective Disclosure:** Allows for future extensions where only specific parts of the receipt might be shared (though typically the full receipt is needed for payment verification). *Example ACK Receipt Verifiable Credential:* ```json theme={null} { "@context": [ "https://www.w3.org/2018/credentials/v1", "https://agentcommercekit.org/contexts/payment/v1" // Example ACK context ], "id": "urn:uuid:5c358383-1d93-4956-8d0c-6e41e4d29901", // Unique receipt ID "type": ["VerifiableCredential", "PaymentReceiptCredential"], "issuer": "did:web:receipts.example.com", // DID of the trusted Receipt Service "issuanceDate": "2025-04-04T14:22:18Z", "credentialSubject": { // ID of the entity that made the payment (Client Agent DID) "id": "did:key:z6MkmCJAZansQ3d7Mi6moQoAFj6vpuPP9e4vWKsjWEY4Hd9t", "paymentRequestToken": "", "paymentOptionId": "unique-payment-option-id-123", // The payment option that was used to make the payment "metadata": { // Additional metadata about the payment, depending on the payment option "amount": 1000, // Final settled amount (e.g., 10.00 USD) "currency": "USD", // Final settled currency "decimals": 2, // Identifier of the ultimate recipient (e.g., Server Agent DID or account) "recipient": "did:web:service.example.com", "id": "unique-request-id-123", // Links back to the Payment Request (if applicable) "serviceDescription": "Premium API access (100 credits)", // From original request (if applicable) "timestamp": "2025-04-04T14:22:15Z" // Timestamp of successful settlement // Optionally include settlement transaction hash/ID if relevant // "settlementRef": "stripe_charge_id_xyz" } }, "proof": { // Standard VC proof (digital signature) "type": "Ed25519Signature2020", "created": "2025-04-04T14:22:18Z", "verificationMethod": "did:web:receipts.example.com#key-1", "proofPurpose": "assertionMethod", "proofValue": "z3..." // Signature value } } ``` See the [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) specification for more details on the general structure. ## Receipt Evidence Metadata `credentialSubject.metadata` is optional and should be treated as an extension point for verifier-specific payment evidence. Keep the core receipt fields stable, and put references or hashes to external policy, mandate, execution, and settlement records in metadata when a deployment needs a richer audit trail. Metadata fields are non-normative: ACK-Pay verifies the receipt signature and the bound payment request token, but applications decide which metadata fields are required for their own policy checks. Do not place secrets, private keys, raw payment credentials, or sensitive customer data in receipt metadata. For agent-commerce flows that compose ACK-Pay with MPP, x402, AP2, or a policy engine, a receipt can carry references like: ```json theme={null} { "credentialSubject": { "metadata": { "policyRef": "policy://merchant-spend-v3", "policySnapshotHash": "sha256:8a0f...", "mandateRef": "ap2:mandate:checkout-123", "executionRef": "urn:ack:execution:checkout-123", "executionReceiptHash": "sha256:5b1d...", "settlementNetwork": "eip155:8453", "settlementReference": "0xabc123" } } } ``` ## Receipt Verification Process When an ACK Receipt is presented by a Client Agent to a Server Agent (e.g., when retrying a request after payment), the Server performs these verification steps: Verify the cryptographic signature (`proof`) on the VC using the public key associated with the `issuer`'s DID. This ensures the receipt hasn't been tampered with since issuance. Check if the `issuer` DID (e.g., `did:web:receipts.example.com`) is present in the Server's configured list of trusted Receipt Services for the relevant context or payment method. Verify that the receipt has not been revoked by the issuer. This typically involves checking a revocation mechanism specified by the Receipt Service (e.g., querying a status list endpoint). Examine the claims within `credentialSubject.paymentRequestToken`, `credentialSubject.paymentOptionId`, and `credentialSubject.metadata` to ensure they match the service requirements: * Is the original `paymentRequestToken` valid and correctly signed? * Is the `paymentOptionId` valid and matches an expected payment option? * Is the `recipient` correct (e.g., does it match the Server Agent's expected identifier)? * Is the `amount`, `currency`, and `decimals` sufficient for the requested service? * Does the `id` match the one originally issued (if applicable in a Server-Initiated flow)? * Are the credential `issuanceDate` and settlement `timestamp` values recent enough, or has the receipt potentially expired based on policy? If all these checks pass, the Server can confidently treat the payment as valid and proceed with service delivery. # Server-Initiated Sequence Source: https://www.agentcommercekit.com/ack-pay/server-initiated-sequence Details of the ACK-Pay flow initiated by a Server requiring payment. This flow is typically used when access to a resource or service requires immediate payment before fulfillment. ## Sequence Steps 1. **Client Request & Server Validation:** The Client Agent makes an API request to the Server Agent. The Server Agent may authenticate and validate the Client Agent (potentially using ACK-ID) and/or the Client Agent's end-user (e.g., using OAuth or API tokens). 2. **Payment Request Initiation:** The Server Agent determines payment is needed. It uses a Payment Service (or generates by itself) the structured [Payment Request](/ack-pay/payment-request-payload). The Server Agent sends this Payment Request to the Client. * *Delivery Method:* The method of delivering the Payment Request depends on the underlying communication protocol: * **Over HTTP:** Over HTTP, the idiomatic approach is to return an HTTP `402 Payment Required` status code, with the Payment Request JSON payload included in the response body. * **Over Other Transports:** When using protocols like WebSockets, gRPC, or agent-to-agent communication frameworks (e.g., A2A), the Payment Request JSON payload should be embedded within the relevant application-level message or data structure used by that protocol. 3. **Client Selects Payment Option & Contacts Payment Service:** The Client receives the Payment Request. It parses the `paymentOptions` array, selects a suitable option based on its capabilities and policy, and contacts the specified `paymentService` endpoint for that option. The payment options offered in the payload are those supported by the specified Payment Service, which bridges to the Server's pay-out requirements. Thus the payment options in a Payment Request are not necessarily the same as those accepted by the Server that will ultimately receive a payment. 4. **Optional: Additional Detail Negotiation:** The Client and Payment Service may exchange further details if needed (e.g., specific pay-in instructions or counterparty info requests). Mutual identity verification using ACK-ID may also occur in this stage. 5. **Payment Execution & Conversion:** The Payment Service executes the Client’s inbound payment, performs any necessary conversions for settling with the Server Agent, and interacts with the underlying Settlement Network(s) appropriate for the payment type. 6. **Receipt Generation:** Following successful settlement confirmation, the Payment Service obtains a signed ACK Receipt (as a Verifiable Credential) from its associated `receiptService`. 7. **Receipt Delivery to Client:** The Client Agent receives the ACK Receipt from the Payment Service. 8. **Receipt Presentation and Verification:** The Client Agent retries the original API request to the Server Agent (or sends a follow-up message), presenting the ACK Receipt (e.g., in an HTTP header or message payload). * Optionally, a `serviceCallback` URL in the initial Payment Request might allow the Payment Service/Receipt Service to notify the Server directly, which may trigger Server execution or state updates without Client resubmission. 9. **Service Delivery:** The Server verifies the presented ACK Receipt (checking signature, issuer trust, revocation status, and relevant details). Upon successful verification, the Server processes the API request and returns the premium financial data. The Client Agent can store the receipt for its records. ## Sequence Diagram ```mermaid theme={null} %%{ init: { 'theme': 'mc', 'themeVariables': { 'primaryColor': '#1D4ED8', 'lineColor': '#374151', 'textColor': '#1f2937', 'sequenceMessageAlign': 'center' } } }%% sequenceDiagram; participant CA as Client Agent; participant SA as Server Agent; participant PS as Payment Service; participant RS as Receipt Service; participant SN as Settlement Network; CA->>SA: 1: Request Resource; rect rgba(0, 0, 255, .03) SA-->>CA: Request Proof of Agency; CA-->>SA: Present Identity Proof; Note right of SA: Verify Client Identity; end SA->>CA: 2: Payment Request; rect rgba(0, 0, 255, .03) CA-->>SA: Request Proof of Agency; SA-->>CA: Present Identity Proof; Note right of CA: Verify Server Identity; end CA->>PS: 3: Initiate Payment; rect rgba(0, 0, 255, .03) PS-->>CA: Request Proof of Agency; CA-->>PS: Present Identity Proof & Request Server Proof of Agency; Note right of PS: Verify Client Identity; PS-->>CA: Present Identity Proof; Note right of CA: Verify Payment Service Identity; end PS<<-->>CA: Potential human-in-the-loop approvals PS->>SN: 4: Execute/Settle; %% Note: Settlement confirmation back to PS is implied %% PS->>RS: 5: Request Receipt; RS-->>PS: Issue Receipt (VC); PS-->>SA: Deliver receipt via optional callback PS->>CA: 6: Deliver Receipt; CA->>SA: 7: Present Receipt; SA-->>SA: Verify Receipt; %% Note: Verification uses VC crypto & issuer's public info, NO callback to RS needed %% SA->>CA: 8: Deliver Resource; ``` *To enlarge this mermaid markdown diagram, zoom in on your browser (CMD +)* ## Example: Paying for Premium API Access Consider a data analysis agent ("Client Agent") needing access to a premium, rate-limited financial data API ("Server Agent"): 1. The Client Agent makes an API request to the Server Agent. 2. After authenticating and validating the Client, the Server Agent determines payment is needed. 3. The Server Agent uses a Payment Service to compose a Payment Request. The Server Agent sends the Payment Request to the Client (e.g., via HTTP 402), offering options like paying 10 USDC via Payment Service A or \$10 via Payment Service B which accepts credit cards. 4. The Client Agent selects the USDC option and contacts Payment Service A. The Client Agent verifies the Payment Service's identity. 5. Payment Service A receives the Client’s inbound USDC payment, executes any conversions necessary for settling with the Server Agent (if needed), and obtains a signed ACK Receipt from its associated Receipt Service. 6. The Client Agent receives the ACK Receipt from Payment Service A. 7. The Client Agent retries the original API request to the Server Agent, presenting the ACK Receipt (e.g., in an HTTP header). 8. The Server Agent verifies the receipt's validity (signature, issuer, amount, etc.). If valid, it processes the API request and returns the premium financial data. The Client Agent can store this receipt to prove payment if needed later, until the Receipt expires (enabling a subscription until expiration). # Summary Source: https://www.agentcommercekit.com/ack-pay/summary Summary of the ACK-Pay Payments Protocol. ACK-Pay provides a flexible and robust pattern framework for agentic financial transactions. By defining standard interactions and leveraging Verifiable Credentials for receipts, it enables secure, automated, and compliant payments across diverse systems. Its support for both [server-initiated](/ack-pay/server-initiated-sequence) and [client-initiated](/ack-pay/client-initiated-sequence) flows, coupled with the abstraction provided by [Payment Services](/ack-pay/payment-service), allows integration with various settlement rails. These include traditional finance, card networks (potentially via APIs like Stripe, PayPal, Visa, Mastercard, etc.), and blockchain-based digital assets (including via protocols like x402). When combined with [ACK-ID](/ack-id/introduction), ACK-Pay creates a powerful foundation for trust and accountability when executing payments in the emerging agent economy. # Example Use Cases Source: https://www.agentcommercekit.com/ack-pay/use-cases Examples of applications enabled by ACK-Pay. ACK-Pay enables many applications where agents need to execute financial transactions. Here are several illustrative examples of ACK-Pay use cases: * **Agent-to-Human Example:** An agent operated by an LLM provider identifies complex legal queries or generated contract clauses requiring expert validation. It uses ACK-Pay to securely pay verified human legal professionals for reviewing the LLM's output, providing specialized feedback, or contributing annotated legal data, ensuring accuracy and compliance in sensitive domains. * **Agent Payments for Services:** A portfolio management agent purchases specialized financial analysis from an expert model that has access to proprietary data, negotiating payment and executing the transaction without human intervention for routine operations below defined thresholds. * **Subscriptions:** An enterprise monitoring agent subscribes to a paywalled data feed, and manages automatic renewals and tier upgrades while notifying humans of any significant changes. * **Outcome-Based Transactions:** A marketing agent pays for customer acquisition services only when conversions occur, with receipts verifying both payment and the outcomes that triggered it. * **Real-time Data Streaming (Micropayments):** An autonomous vehicle agent continuously pays fractions of a cent via micropayments for real-time traffic data updates from multiple providers along its route, ensuring access to the most current information without large upfront commitments or high per-transaction fees associated with traditional payment rails. * **AI Shopping Assistant Purchase (Human-to-Agent):** A user employs an AI shopping agent to find and negotiate the best price for a specific product across multiple vendors. Once the agent secures the deal, the user authorizes payment directly to the agent's designated account (which then settles with the vendor) using ACK-Pay, receiving a verifiable receipt confirming the purchase details and initiating shipping. * **MCP Server Data Access:** An LLM-driven research workflow needs to access specialized data through a Model Context Protocol (MCP) server that requires payment. When the LLM attempts to access the MCP resource, the MCP client and server use ACK-Pay to facilitate the payment automatically. With valid payment confirmed, the MCP server grants access to the requested data, allowing the LLM to continue its analysis without interruption or human intervention. # End-to-End Demo Source: https://www.agentcommercekit.com/demos/demo-e2e Comprehensive example demonstrating combined ACK-ID and ACK-Pay protocol flows. ## Overview This End-to-End (E2E) demo showcases the integration and seamless interaction between ACK's core protocols: * **ACK-ID** (Identity Management) * **ACK-Pay** (Payment Processing) Through this interactive command-line demo, you'll observe a realistic flow demonstrating secure agent identity verification alongside automated, verifiable payment transactions. ## Getting Started Before running this demo, please complete the setup steps from the [Quickstart Guide](./quickstart). ## Running the Demo You can run the E2E demo using the following command from the repository root: ```sh theme={null} pnpm demo:e2e ``` Alternatively, navigate directly into the demo directory (`./demos/e2e`) and run: ```sh theme={null} pnpm run demo ``` ## Demo Overview The demo walks you through a scenario where: Agents (Client and Server) and their respective owners initialize their identities using ACK-ID standards (Decentralized Identifiers and Verifiable Credentials). Client Agent and Server Agent verify each other's identities securely and efficiently before initiating transactions (utilizing ACK-ID). Server Agent requires payment from the Client Agent (utilizing ACK-Pay), issuing a formal Payment Request specifying acceptable payment methods. Client Agent completes the payment transaction, showcasing automated payment verification. Upon successful payment, a receipt Service issues a cryptographically verifiable receipt. Using the receipt, the Client Agent successfully accesses the requested resource from the Server Agent. ## Key Components Demonstrated * Integrated Identity Verification (ACK-ID) * Payment Initiation, Processing, and Receipt Verification (ACK-Pay) * Secure Agent-to-Agent interaction with cryptographic validation ## Further Exploration * [View End-to-End Demo Source Code](https://github.com/agentcommercekit/ack/tree/main/demos/e2e) * [ACK Documentation](https://agentcommercekit.com) * [ACK-ID Protocol Details](/ack-id/introduction) * [ACK-Pay Details](/ack-pay/introduction) # ACK-ID Agent Demo Source: https://www.agentcommercekit.com/demos/demo-identity Detailed step-by-step guide demonstrating ACK-ID identity verification between agents. ## Overview **ACK-ID** is a protocol built on W3C Standards designed to ensure verifiable, secure, and compliant identity, reputation, and service discovery for autonomous agents. This interactive command-line demo guides you through: * **Owner Identity Creation**: Establish unique decentralized identifiers (DIDs) for entities (individuals or organizations) that offer AI agents. * **Agent Identity Creation**: Assign distinct DIDs to AI agents, linked to their respective owners. * **Verifiable Credential (VC) Issuance**: Generate digitally signed, tamper-proof credentials proving agent ownership. * **Agent-to-Agent Verification**: Demonstrate secure verification of agent identities before or during interactions. ## Demo Video