Z-Zero Payments

intent

enable agents to purchase items (SaaS subscriptions, API credits, physical goods) without ever handling card data. z-zero routes payments through two rails: gasless USDC on Base (sponsored by Coinbase Paymaster, no ETH or gas UX) for crypto-native checkouts, and just-in-time single-use virtual cards (one amount, one merchant, 1-hour TTL, auto-burned) for traditional web merchants. the model context never sees PAN, CVV, or expiry; only single-use tokens are handled. every payment requires explicit human approval before execution, and token blast radius is capped by amount and merchant lock. use this skill when an agent needs to buy something and the operator wants full transparency, control, and zero card data leakage.

inputs

environment variables:

• Z_ZERO_API_KEY (required): Passport Key starting with zk_live_. obtained from z-zero.xyz/dashboard/agents. bootstrap value only; auto-rotates on first connect and moves to ~/.z-zero/credentials (mode 0600). if you paste the key into a conversation, it's considered burned and will be replaced on next server connect.

setup requirements:

• npx binary available in PATH.
• z-zero MCP server registered in ~/.openclaw/openclaw.json under mcpServers.z-zero:

  {
    "mcpServers": {
      "z-zero": {
        "command": "npx",
        "args": ["-y", "z-zero-mcp-server@latest"],
        "env": { "Z_ZERO_API_KEY": "${Z_ZERO_API_KEY}" }
      }
    }
  }
  

• operator wallet funded with USDC on Base (deposit address visible in dashboard).

external MCP resources:

• mcp://resources/sop: authoritative payment flow SOP. must be read once per session before any payment.

operator context:

• budget cap (if set, payment total must not exceed).
• shipping destination for cart-bound intent signing.
• explicit approval for each payment (no silence-means-yes).

procedure

1. bootstrap session: call mcp://resources/sop resource and read the full SOP once. this is the authoritative flow; do not deviate.

2. gather merchant hints: call get_merchant_hints with the target checkout platform name (e.g. "Shopify", "Etsy", "WooCommerce"). receive structured pre_steps (login flow, form IDs, variant selectors, known blocker patterns).

3. execute pre-steps: follow the merchant's pre_steps exactly (login, add to cart, navigate to checkout page). do not skip or reorder these steps.

4. reach final checkout page: navigate until the final total (subtotal + tax + shipping) is visible and unambiguous on the page. pause here.

5. audit cart vs. intent: compare the live checkout page item-by-item with what the operator originally asked for: same SKU, same quantity, same variant, same ship-to address. if any detail differs, stop immediately. no token issued yet, so a mismatch caught here costs nothing.

6. request human approval: call request_human_approval with exact parameters: merchant name, item description, quantity, unit price, shipping cost (or "calculated at checkout"), tax (if visible), final total, and destination. include a short URL or screenshot of the cart if possible. wait for operator confirmation. do not proceed without explicit approval or a confirmation message from the operator.

7. execute payment: on approval, call auto_pay_checkout. the server auto-detects checkout type (EIP-681 crypto link vs. card form) and routes accordingly. for crypto checkouts, it settles as a gasless USDC transfer on Base; for card checkouts, it issues a JIT virtual card bound to a signed intent (proof of what was authorized). do not call any endpoint directly; use auto_pay_checkout only.

8. verify and relay result: receive response with status (e.g. "completed", "declined", "timeout", "form_changed"). read signed_receipt field. call verify_receipt(receipt_id) to re-confirm. relay to operator: the exact status, merchant's verify_url (if present), and any differences in signed_receipt.diff (e.g. "charged $5 more than authorized", "item quantity changed"). do not assert from memory; quote the signed receipt.

9. handle technical failures: if checkout failed for a technical reason (not operator cancellation), call report_checkout_fail(url, failure_class, step, error_message). failure_class must be one of: card_declined_issuer, card_declined_bin_block, avs_mismatch, 3ds_required, bot_detected, form_changed, price_changed, out_of_stock, shipping_unsupported, login_required, timeout, outcome_unconfirmed, intent_mismatch, unknown. this feeds evidence for the next agent.

10. wallet operations (optional): for read-only balance checks between payments, call list_cards (aliases and balances), check_balance(alias) (spendable USD), or get_deposit_addresses (Base USDC deposit address). these require no approval.

decision points

if Z_ZERO_API_KEY is missing or empty: abort with error message. do not guess or fabricate a key. operator must export Z_ZERO_API_KEY and restart the agent.

if MCP server does not register (e.g., mcporter list shows no z-zero tools): abort with setup instructions. do not attempt to call tools that don't exist.

if get_merchant_hints returns an unknown or unsupported platform: proceed with generic checkout steps, but inform operator that merchant-specific logic is unavailable and checkout may require manual fallback (e.g. Cloudflare blocks headless browser, or form structure is non-standard).

if cart audit (step 5) detects a mismatch: stop immediately. do not request approval. inform operator of the discrepancy (e.g. "you asked for 2x item A, but cart shows 1x item A and 1x item B") and ask them to fix and restart.

if request_human_approval receives no response within a reasonable timeout (e.g., 5 minutes) or operator explicitly declines: abort payment. do not call auto_pay_checkout. do not interpret silence, delays, or vague responses ("sounds good") as confirmation. confirmation must be explicit and unambiguous.

if operator budget cap is set and final total (including shipping and tax) exceeds it: abort payment. do not request approval. report the overage to operator. do not attempt to negotiate (e.g. removing items) without explicit re-request from operator.

if auto_pay_checkout returns status declined with failure_class like card_declined_issuer or 3ds_required: inform operator of the specific failure. do not retry automatically. operator may choose to retry, use a different payment method, or cancel.

if auto_pay_checkout returns outcome_unconfirmed or timeout: call verify_receipt(receipt_id) to check if the charge actually went through (sometimes the response is lost but the merchant processed it). relay the verification result, not a guess.

if /api/tokens/resolve endpoint exists and you think you need to call it: do not. this endpoint is for server-side token injection only. calling it defeats the security model. if you think you need raw card data, you are off the rails; stop and report to operator.

if merchant is Cloudflare-protected and checkout fails with bot_detected: inform operator instead of retrying. headless Playwright cannot easily bypass Cloudflare; operator may need to manually complete the purchase or use a different merchant.

if signed_receipt.diff shows a mismatch (e.g. charged $5 more than authorized): relay the diff verbatim to operator. this is evidence of potential fraud or misconfiguration. do not assume it's okay.

output contract

successful payment flow returns:

• status: "completed" (string).
• signed_receipt: object containing:
  • receipt_id: unique identifier for this transaction.
  • merchant: name of merchant.
  • amount_charged_usd: final amount charged (number, in USD).
  • payment_method: "usdc_base" or "virtual_card" (string).
  • timestamp: ISO 8601 UTC timestamp.
  • verify_url: public URL where operator can verify the transaction with the merchant.
  • diff: object with any discrepancies vs. authorization (e.g. {"charged_amount_vs_authorized": "+5.00", "item_qty_vs_authorized": "changed"}, or empty {} if match).
  • proof: for USDC transfers, includes Base mainnet transaction hash; for card, includes last 4 of virtual card and issuer confirmation.

failed payment returns:

• status: "declined" | "timeout" | "form_changed" | "outcome_unconfirmed" | (other failure_class enum).
• failure_reason: human-readable reason.
• failure_class: one of the fixed enums (card_declined_issuer, bot_detected, etc.).
• retry_eligible: boolean (true if operator can safely retry; false if permanent).

wallet read operations return:

• list_cards: array of objects with alias, balance_usd, card_type ("virtual" or "stored"), created_at.
• check_balance: object with alias, balance_usd, currency ("USD").
• get_deposit_addresses: object with base_usdc_address (string, 0x...), network ("base"), qr_code_url (optional).

human approval request does NOT return until operator confirms or declines. operator confirmation is a synchronous message, not a background event.

receipt verification via verify_receipt(receipt_id) returns:

• verified: boolean (true if receipt is cryptographically valid and merchant confirms the charge).
• current_status: current status of the transaction at the merchant (e.g. "completed", "refunded", "chargebacked").
• amount_confirmed_usd: merchant-confirmed amount.
• proof_link: merchant's order tracking or confirmation link.

outcome signal

payment succeeded when:

• auto_pay_checkout returns status: "completed".
• signed_receipt is present and contains a valid receipt_id and verify_url.
• verify_receipt(receipt_id) returns verified: true.
• operator can see the order confirmation at the merchant (e.g. order page, email receipt, or via verify_url).
• operator receives the signed receipt and can forward it for accounting/proof.

payment failed when:

• auto_pay_checkout returns any status other than "completed".
• verify_receipt returns verified: false or a mismatch in current_status.
• operator was not asked for approval or approved but then declined.
• cart audit (step 5) detected a mismatch and payment was aborted before any token issued.
• budget cap exceeded and payment was aborted.

for wallet operations:

• balance check succeeded when check_balance returns a balance_usd value and operator sees it matches their expected funding.
• deposit address retrieved when get_deposit_addresses returns a valid Base mainnet address (0x...) and operator can copy it for USDC transfer.

operator knows it worked when:

• they see the merchant's order confirmation page or email.
• they can click or paste the verify_url from the signed receipt and the merchant confirms the charge.
• for USDC payments, they can paste the Base transaction hash into a block explorer (basescan.org) and see the gasless transfer.
• for virtual card payments, they see "card declined" or "invalid card" if they try to reuse the token (confirms it was burned after first use).
• agent relays the exact status and receipt (not a claim like "it worked"), and operator cross-checks it against the merchant.

credits: original skill by z-zero team (github.com/Dempty-glitch/Z-Zero-mcp, MIT license). enriched per Implexa quality standards.