--- name: ap2-human-present-flow description: > Implement the AP2 human-present transaction flow — the checkout process where the user is actively present to confirm cart details and payment method selection. The primary VDC in this flow is the Checkout Mandate. Use when building interactive agentic checkout with user in the loop. --- # AP2 Human-Present Transaction Flow ## Before writing code **Fetch live docs**: 1. Fetch `https://ap2-protocol.org/ap2/specification/` for the human-present flow specification 2. Web-search `site:github.com google-agentic-commerce AP2 samples human-present` for reference implementations 3. Fetch `https://github.com/google-agentic-commerce/AP2/tree/main/code/samples` for the card payment sample 4. Fetch `https://ap2-protocol.org/overview/` for flow overview ## Conceptual Architecture ### What Human-Present Means In a human-present flow, the **user is actively engaged** throughout the transaction. They review products, select items, choose a payment method, and confirm the purchase — all while interacting with the Shopping Agent. ### The Human-Present Transaction Flow The official AP2 specification describes approximately **11 high-level steps** for the human-present flow. The primary VDC in this flow is the **Checkout Mandate**. ``` Phase 1: Shopping Intent 1. User → Shopping Agent: Provides shopping prompt ("I want to buy a coffee maker") 2. SA → User: Confirms intent and collects CP preference + shipping address Phase 2: Product Discovery 3. SA → CP: Queries Credentials Provider for available payment methods 4. SA → Merchant: Presents shopping intent 5. Merchant → SA: Creates and signs Checkout Mandate(s) with product offers Phase 3: User Confirmation 6. SA → User: Displays final cart + payment options 7. User → SA: Reviews cart, selects payment method, confirms on trusted device surface Phase 4: Payment Processing 8. SA → Merchant: Sends confirmed Checkout Mandate + user attestation 9. Merchant → MPP: Submits payment for processing 10. MPP: Constructs Payment Mandate and requests credentials from CP Phase 5: Completion 11. MPP → Merchant → SA → User: Payment processed, receipt delivered ``` ### Agent Interactions (A2A Messages) Each step involves A2A protocol communication: - Shopping Agent ↔ Merchant Agent: A2A tasks with mandate DataParts - Shopping Agent ↔ Credentials Provider: A2A tasks for payment methods - Shopping Agent ↔ Payment Processor: Indirect (via Merchant) ### User Touchpoints The user is involved at these critical points: - **Step 1**: Initiates the shopping request - **Step 2**: Confirms intent and provides preferences - **Step 6-7**: Reviews cart, selects payment, and confirms on trusted device surface (attestation) - **Step 11**: Receives confirmation and receipt ### Trusted Device Surface Step 7 is a **load-bearing security step**: - User is redirected to a trusted device surface (not the agent) - User reviews the final transaction details - User provides attestation (biometric, PIN, etc.) - This is hardware-backed confirmation, not just an LLM prompt - Prevents agent manipulation of the final authorization ### Challenge Handling During the flow, any participant may trigger a challenge: - **3DS2** — Card network challenges for risk assessment - **OTP** — One-time password verification - User is redirected to a trusted surface for challenge resolution - Flow resumes after successful challenge ### Implementation Considerations - **Stateful flow** — The human-present transaction flow must maintain state across multiple agent interactions - **Timeout handling** — Users may step away; implement reasonable timeouts - **Error recovery** — Handle failures at any step with proper rollback - **Concurrent agents** — Shopping Agent may query multiple merchants in parallel - **Cart changes** — User may modify the cart between steps ### Best Practices - Display clear product information at step 6 for user review - Never skip the trusted device confirmation (step 7) - Handle 3DS/OTP challenges gracefully - Log every step for audit trail - Implement timeouts for user response steps - Support cart modification before final confirmation - Show the user exactly what they're authorizing (items, prices, total) - Test the full human-present transaction flow end-to-end Fetch the specification and sample implementations for exact message formats, mandate structures at each step, and agent communication patterns before implementing. --- Source attribution: OrcaQubits Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/ap2-agentic-payments/skills/ap2-human-present-flow/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: OrcaQubits Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/ap2-agentic-payments/skills/ap2-human-present-flow/SKILL.md Attribution basis: Source repository record Fields of work: Marketing, Product Management, Sales, Customer Support Roles: Customer Experience, Growth Marketer, Product Marketer, Sales Engineer, Technical Product Manager Specialties: API Tools: Ap2 Protocol, Shopping Agent Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 8134b4704994a81928ecaf8c00e4f974659df608e7220b68a3bae63ae4ce91d5