Agentic Checkout: Add first pass at hosted ACP implementation

[ebinnion]

Changes proposed in this Pull Request:

This PR implements the Stripe Agentic Checkout Protocol, enabling AI agents (like ChatGPT, Claude, etc.) to facilitate purchases on behalf of users through a secure, standardized REST API interface.

This implementation is specifically meant to add Stripe's hosted ACP.

In the current form, this pull request is very much draft and needs testing and probably then breaking out. This PR is meant as a starting point.

Implementation Overview

Core Components Added:

• Authentication Trait (WC_Stripe_Agentic_Authentication): Webhook signature verification to ensure requests come from Stripe
• REST API Controllers (4 endpoints):
  • POST /wc/v3/stripe/agentic/approval - Manual approval hook for order validation
  • POST /wc/v3/stripe/agentic/tax - Tax calculation hook
  • POST /wc/v3/stripe/agentic/shipping - Shipping rate calculation hook
  • Controller registration integrated with WooCommerce REST API
• Webhook Handler Extensions: Process agentic_checkout.session.completed events
• Admin UI: Manual capture interface for approved orders requiring payment capture
• Comprehensive Documentation: 787-line guide at docs/agentic-checkout.md

Security Features:

• All endpoints require valid Stripe webhook signatures
• Feature disabled by default (requires wc_stripe_agentic_checkout_enabled filter)
• Product validation prevents unauthorized item additions
• Stock validation ensures availability before approval

Trade-offs:

• Feature is opt-in via filter rather than admin setting to keep the initial implementation simple
• Manual capture required for approved orders (automatic capture can be added in future)
• Uses existing WooCommerce tax/shipping calculations rather than custom logic

How can this code break?

• Invalid webhook signatures could block legitimate agent requests
• Product/stock validation could reject valid orders if catalog data is incorrect
• Tax/shipping calculations depend on WooCommerce extensions being properly configured
• Session metadata storage could fail if order creation fails

What are we doing to make sure this code doesn't break?

• Comprehensive test coverage: 7 test files with 1,647 lines of tests covering:
  • Authentication and signature verification
  • All REST API endpoints (approval, tax, shipping)
  • Webhook handler session processing
  • Admin capture functionality
  • Controller registration
• Defensive coding: Extensive validation, error handling, and WP_Error returns
• Feature flag: Disabled by default, requires explicit opt-in
• Detailed logging: Debug logs for troubleshooting production issues

Testing instructions

Prerequisites

1. Enable the feature by adding to functions.php or a custom plugin:

   add_filter( 'wc_stripe_agentic_checkout_enabled', '__return_true' );

2. Configure Stripe webhook endpoint to receive agentic_checkout.session.completed events
3. Ensure webhook secret is configured in Stripe settings (test mode)
4. Install WooCommerce Tax and Shipping extensions if testing those calculations

Test 1: Manual Approval Endpoint

1. Send POST request to /wp-json/wc/v3/stripe/agentic/approval with valid Stripe signature
2. Include in request body:

   {
     "line_items": [
       {"product": "prod_xxx", "quantity": 2}
     ],
     "currency": "usd",
     "shipping": {
       "address": {
         "line1": "123 Main St",
         "city": "San Francisco",
         "state": "CA",
         "postal_code": "94111",
         "country": "US"
       }
     }
   }

3. Expected: Response includes approved: true with calculated amount_total
4. Verify: Products exist in catalog and are in stock

Test 2: Tax Calculation Endpoint

1. Send POST request to /wp-json/wc/v3/stripe/agentic/tax with valid Stripe signature
2. Include line items and shipping address (same format as Test 1)
3. Expected: Response includes tax amounts broken down by line item
4. Verify: Tax rates match WooCommerce tax settings for the address

Test 3: Shipping Calculation Endpoint

1. Send POST request to /wp-json/wc/v3/stripe/agentic/shipping with valid Stripe signature
2. Include shipping address in request body
3. Expected: Response includes available shipping methods with rates and display names
4. Verify: Shipping options match WooCommerce shipping zones for the address

Test 4: Webhook Processing

1. Configure Stripe CLI to listen: stripe listen --forward-to 'http://your-site.test/?wc-api=wc_stripe'
2. Trigger test webhook: stripe trigger agentic_checkout.session.completed
3. Expected:
   • Order created in WooCommerce with status "On hold"
   • Order note: "Payment authorized via Stripe Agentic Checkout. Requires manual capture."
   • Order meta includes _stripe_agentic_checkout data
4. Verify: Order appears in WooCommerce > Orders

Test 5: Manual Capture Admin UI

1. Navigate to the order created in Test 4
2. Expected: "Stripe Agentic Checkout" meta box visible in sidebar
3. Click "Capture Payment" button
4. Expected:
   • Payment captured in Stripe
   • Order status changes to "Processing"
   • Success notice displayed
5. Verify: Payment Intent shows "succeeded" status in Stripe Dashboard

Test 6: Error Handling

1. Test with invalid webhook signature
   • Expected: 401 Unauthorized response
2. Test approval with out-of-stock product
   • Expected: approved: false with reason
3. Test with feature disabled (remove filter from step 1)
   • Expected: Endpoints return 404 or feature disabled error

Test 7: Authentication Security

1. Attempt request without Stripe-Signature header
   • Expected: Request rejected with authentication error
2. Attempt request with invalid signature
   • Expected: Request rejected with signature validation error

---

• Covered with tests (7 test files, 1,647 lines of comprehensive test coverage)
• Tested on mobile (does not apply - server-side REST API)

Changelog entry

• This Pull Request does not require a changelog entry.

Changelog Entry

Add - Stripe Agentic Checkout Protocol support enabling AI agents to facilitate purchases through secure REST API endpoints for approval, tax calculation, shipping calculation, and order completion via webhooks.

Post merge

• Added testing instructions to the Release Testing Instructions wiki page
• Added the needs docs label
• Included this PR in the Release Thread scope

---

Additional Notes

Documentation: Comprehensive documentation added at docs/agentic-checkout.md covering:

• Feature overview and requirements
• Setup instructions
• REST API endpoint specifications
• Webhook handling
• Manual capture workflow
• Developer hooks and filters
• Troubleshooting guide
• Security considerations

Files Changed: 15 files, 3,998 lines added

• 7 implementation files (1,564 lines)
• 7 test files (1,647 lines)
• 1 documentation file (787 lines)

[ebinnion]

This can/should probably be deleted before merge. Leaving as-is for now as it is the implementation document produced from planning.