# Z-ZERO Agent Skill — Payment SOP
Version: 2.0 | Updated: 2026-03-19

⚠️  AGENT: Read this ENTIRE page before using any payment tool.
    This is your SOP. Missing a step causes checkout failures.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PART 1: PAYMENT WORKFLOW (SOP)

You are connected to the Z-ZERO MCP Server. You will NEVER see or handle a real credit card number.
Follow this checklist precisely — in order.

### Step 0 — Proactive Info Collection (DO THIS FIRST)

When the user sends a product link and asks to buy:
1. IMMEDIATELY ask for shipping info in ONE message:
   - Full name
   - Shipping address (street, city, state/province, country, postal code)
   - Email
   - Phone (if required by merchant)
   - Product options (size, color, quantity) if applicable

2. Do NOT wait until you reach the shipping form. Ask NOW.

3. Start browsing the product page IN PARALLEL while user responds.

Special cases:
- "use my old info" → recall from conversation history
- Digital goods (software, API key, download) → only email needed, skip address
- Use judgment — this is where LLM intelligence matters

### Step 1 — Verify Intent & Price

- Confirm exactly what to buy and the expected price in USD
- If unknown, browse the merchant's pricing page first

### Step 2 — Check Balance

- Call check_balance with the user's card_alias (default: Card_01)
- If insufficient → STOP and ask user to top up at /dashboard/agent-wallet

### Step 3 — Platform Detection (Speed Boost)

Before browsing checkout, detect platform:

| URL signal | DOM signal | Platform key | What you get |
|---|---|---|---|
| etsy.com in URL | — | _platform_etsy | Full flow: variations → cart → guest → shipping → card → review |
| /checkouts/ in URL or cdn.shopify.com scripts | window.Shopify JS object | _platform_shopify | Card selectors + iframe handling |
| No URL match | woocommerce in body class | _platform_woocommerce | WooCommerce Stripe Elements |
| No match | — | use domain from URL | Domain-specific hints if any |

Call: get_merchant_hints(platform_key_or_domain)
→ Returns pre_steps and selectors from DB
→ This is 4× faster than generic mode

### Step 4 — Card Issuance Gate

Only call request_payment_token when BOTH are true:
1. Shipping info has been submitted on the form
2. Card input fields (or payment iframe) are visible on current page

If EITHER is false → DO NOT request token. Keep navigating first.

Find the FINAL total (after shipping + tax) before requesting token.

### Step 5 — Request JIT Token

- Call request_payment_token with exact amount and merchant name
- You receive a token (temp_auth_...). Valid for 1 hour. Single-use.

### Step 6 — Execute Payment

- Call execute_payment with token + checkout_url + hints from Step 3
- MCP bridge injects card data, clicks Pay, burns token automatically

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PART 2: HYBRID EXECUTION MODEL

LLM handles thinking. Scripts handle clicking.

🧠 LLM territory:
- User conversation and context ("use old info", "this is digital")
- Platform recognition and exception handling
- Unexpected popups, CAPTCHAs, errors

🤖 Script territory (NO LLM per click):
- For known platforms → follow pre_steps from get_merchant_hints as a deterministic script
- Each click follows the pre_steps list in order
- Only fall back to LLM when a scripted step fails or something unexpected appears

WHY: Each LLM call adds ~2-3s latency.
- 11-step Etsy checkout with LLM-per-step = ~25s overhead
- Same flow with script-first = near-zero overhead

RULE: If you got pre_steps from get_merchant_hints → follow them mechanically.
      Do NOT reason about each step individually. Just execute in order.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PART 3: AUTO-ROUTING (Web3 vs Fiat)

When you call auto_pay_checkout, Z-ZERO auto-detects the best payment path:

Detection flow:
  auto_pay_checkout(url)
         │
         ▼
  Does page have window.ethereum or EIP-681 links?
         │
        YES ──────► Path 2: USDC on Base (gasless smart account)
         │
         NO
         │
         ▼
                    Path 1: JIT Visa Card
                    request_payment_token → execute_payment

Payment Paths Summary:
| Path | Mechanism | Playwright? | Fail Risk |
|---|---|---|---|
| 1: JIT Visa | Playwright form fill | Yes | Medium |
| 2: Gasless USDC (Base) | Coinbase Smart Account + Paymaster | No | Low |

For physical goods → auto_pay_checkout may return PRICE_NOT_FOUND (price only appears after shipping).
In that case: use browser tools manually, follow Part 1 SOP above.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PART 4: FAILURE REPORTING (Self-Healing Loop)

Z-ZERO is a self-improving system. Report failures so all agents benefit.

RULE: "Did I successfully complete the purchase the user asked for?"
- NO → report_checkout_fail(checkout_url)
- YES → done, no report needed

REPORT these (form/website is the cause):
✅ Form too complex, don't know how to fill
✅ Card fill failed (wrong selector, unknown iframe)
✅ Page blocked by CAPTCHA or bot detection
✅ Unexpected redirect or popup

DO NOT REPORT these (user/money is the cause):
❌ User cancelled or said "stop"
❌ Insufficient balance
❌ Token expired before you reached checkout
❌ Price mismatch (handled via cancel_payment_token)

How to report:
1. Call report_checkout_fail(url) with checkout URL, error_type, error_message
2. Tell user the purchase failed, include the checkout URL
3. URL goes to DB → admin reviews → hints created for future agents

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PART 5: CRITICAL RULES (Never Break These)

- NEVER print token in chat — treat as sensitive even though temporary
- NEVER loop: if execute_payment returns success: false → inform user, do NOT retry
- NEVER accept card numbers in chat
- PRICE MUST MATCH: if checkout shows higher price than token → cancel_payment_token first, then request new token
- PHYSICAL GOODS: Always collect shipping info BEFORE navigating to checkout

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PART 6: MAINTENANCE (Run at session start)

✅ MCP version warnings arrive automatically via the X-MCP-Version response header
   → If a response includes an update warning, relay it to your human user — no separate tool call needed

✅ Platform hints are in the DB — no need to memorize selectors
   → Always call get_merchant_hints(domain) to get latest selectors
   → DB is updated as new checkouts are discovered