AP2 Checkout (mock)

Drive the AP2 unified demo purchase flow via mcporter against local mock MCP servers (merchant, buyer, credentials provider, MPP). All settlement is simulated.

One-command install (recommended for demo)

From your AP2 clone (installs skill, patches OpenClaw, starts mock backend):

cd "$AP2_HOME"
npx -y file:code/samples/python/scenarios/a2a/unified/clawhub/npm/ap2-agent-checkout install

Then restart the OpenClaw gateway. Manual steps below are only needed if you skip the installer.

First-time setup (manual)

1. Clone AP2 and set AP2_HOME to the repository root (the folder that contains code/):

export AP2_HOME="/path/to/AP2"

2. Start the mock backend (triggers 8091–8094, MCP HTTP 8100–8103):

cd "$AP2_HOME/code/samples/python/scenarios/a2a/unified"
chmod +x openclaw/start_ap2_backend.sh openclaw/stop_ap2_backend.sh
./openclaw/start_ap2_backend.sh

3. Point mcporter at this skill's mcporter.json (after ClawHub install, use the skill directory):

# After clawhub install (adjust if your skills dir differs):
export MCPORTER_CONFIG="$HOME/.openclaw/workspace/skills/ap2-checkout/mcporter.json"

4. Enable skills in ~/.openclaw/openclaw.json: mcporter and ap2-checkout → enabled: true. Restart the gateway.

5. Verify (optional): run scripts/check-backend.sh from this skill folder with AP2_HOME set.

See references/setup.md for ports and troubleshooting.

Session identity

Use a stable session_id per chat (Feishu channel + peer id, or any unique string). Pass it to every ap2-buyer.* tool.

mcporter list ap2-buyer --schema
mcporter list ap2-merchant --schema

Mode selection (always first)

mcporter call ap2-buyer.set_ap2_session_config_tool \
  session_id=CHAT_ID presence_mode=hnp payment_method=card merchant=shoe
mcporter call ap2-buyer.get_ap2_session_config_tool session_id=CHAT_ID

Follow merchant_instruction from get_ap2_session_config.

Trusted Surface (user approval)

Before signing mandates, show a clear summary (item, price cap, payment rail). Wait for explicit yes / approve / 确认.

mcporter call ap2-buyer.register_trusted_surface_approval \
  session_id=CHAT_ID price_cap=200 payment_method=card \
  item_id=supershoe_limited_edition_gold_sneaker_womens_9_0

Plain-text budget or "pay by card" alone is not approval.

HNP flow (delegated drop)

1. Set config → hnp + card or x402.
2. Build item_id as \x3Cslug>_0 (lowercase, non-alphanumeric → _). Do not call search_inventory for shoes.
3. mcporter call ap2-merchant.check_product item_id=... constraint_price_cap=200
4. Mandate summary → user approval → register_trusted_surface_approval.
5. Sign mandates — mandate_request must be a JSON string inside --args:

mcporter call ap2-buyer.assemble_and_sign_mandates --args '{
  "session_id": "CHAT_ID",
  "mandate_request": "{\"item_id\":\"...\",\"price_cap\":200,\"qty\":1}"
}'

6. Poll: mcporter call ap2-buyer.check_constraints session_id=CHAT_ID price=299 available=false
7. If stock 0, user runs (replace ITEM_ID and PRICE from tool results):

curl -X POST "http://127.0.0.1:8091/trigger-price-drop?item_id=ITEM_ID&price=199&stock=10"

8. When meets_constraints is true: assemble_cart → create_checkout → payment/checkout presentations → issue_payment_credential (presence_mode=hnp) → complete_checkout → verify_checkout_receipt_tool. Emit purchase_complete JSON and stop.

HP flow (buy now)

1. Set config → hp + card or x402.
2. search_inventory or check_product → assemble_cart.
3. Once: create_hp_open_mandates (no checkout_jwt yet).
4. create_checkout with open_checkout_mandate_id and payment_method.
5. Checkout summary → user 确认 → register_trusted_surface_approval.
6. assemble_and_sign_immediate_mandates with checkout_jwt, checkout_jwt_hash, amount_cents, etc.
7. issue_payment_credential (presence_mode=hp) → complete_checkout → purchase_complete.

Never call create_hp_open_mandates twice per purchase. Never re-run assemble_cart / create_checkout after user confirmed.

Payment rail switch

set_ap2_session_config_tool with new payment_method → clear_open_mandate_session_tool → re-approve → sign again.

Stop backend

cd "$AP2_HOME/code/samples/python/scenarios/a2a/unified" && ./openclaw/stop_ap2_backend.sh